API Documentation

PRE-RELEASE WARNING: This API is currently in pre-release and undergoing rapid development. Breaking changes are occurring frequently as we work toward a stable v1 release. Please use caution when building production systems against this API during the pre-release period.

The Easel API is a powerful, RESTful HTTP API that gives you programmatic access to your e-commerce store. With the API, you can build custom applications, integrate with third-party services, automate business processes, and create unique shopping experiences.

What can you do with the API?

• Manage your catalog: Create, update, and organize products and variants
• Process orders: Handle order fulfillment, track shipments, and manage returns
• Customer management: Store customer information, manage addresses, and track purchase history
• Inventory control: Monitor stock levels, set up automatic reordering, and manage multiple locations

Why use the API?

• Automate repetitive tasks: Save time by automating inventory updates, order processing, and customer communications
• Scale your business: Handle high-volume operations that would be impractical through manual processes
• Custom workflows: Implement business logic that's specific to your industry or operational needs
• Real-time data: Keep all your systems in sync with up-to-date information
• Flexibility: Build exactly what you need without being limited by standard interface constraints

Base URL

/api/v1/

Authentication

All API endpoints require authentication using Bearer tokens. See the Authentication documentation for details.

Response Format

All API responses use JSON format with consistent structure:

Success Responses

{
  "id": "prd_123",
  "name": "Example Product",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z"
}

List Responses

List endpoints return paginated results:

{
  "products": [
    {
      "id": "prd_123",
      "name": "Example Product"
    }
  ],
  "pagination": {
    "has_next_page": true,
    "has_previous_page": false,
    "next_cursor": 456
  }
}

Error Responses

Error responses include a descriptive message and error code:

{
  "error": "Product not found",
  "code": "NOT_FOUND"
}

Pagination

List endpoints support cursor-based pagination using the after query parameter:

• after: Return results after this ID (cursor)
• Results are ordered by ID
• Maximum page size is determined by domain.PageLimit

Example:

GET /api/v1/products?after=123

HTTP Status Codes

• 200 OK - Request successful
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required or invalid
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Rate Limiting

API requests are rate limited per store. Rate limit information is returned in response headers:

• X-Ratelimit-Limit: Total requests allowed per window
• X-Ratelimit-Remaining: Requests remaining in current window
• X-Ratelimit-Reset: Unix timestamp when the rate limit resets

Data Types

Timestamps

All timestamps are returned in RFC3339 format (ISO 8601):

2023-01-01T00:00:00Z

IDs

Public IDs are used for all external-facing identifiers:

• Products: prd_123abc
• Orders: ord_456def
• Customers: cus_789ghi

Monetary Values

All monetary values are represented as integers in the smallest currency unit (e.g., cents for USD):

{
  "price": 1999,  // $19.99
  "total": 2599   // $25.99
}

API Reference