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 RESTful HTTP API for your ecommerce store. Use it to keep inventory in sync, or to pull orders and customer data into your own tools.

What can you do with the API?

• Manage your catalog: Create and update products, variants, options, images, and tags
• Process orders: Update order status, record fulfillments and refunds, and manage digital downloads
• Manage customers: Store customer information and their addresses
• Configure storefronts: Manage sites, pages, collections, and discount codes

Base URL

/api/v1/

Authentication

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

Response Format

All API responses use JSON format. Single resources are returned as a JSON object:

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

List endpoints wrap results in a data array:

{
  "data": [
    {
      "id": "pro_d0b6fmv28q6vn14peun0",
      "name": "Example Product"
    }
  ],
  "has_more": true
}

Some list endpoints are not paginated and return only data.

Error responses include a descriptive message and an error code:

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

Common error codes include INVALID_JSON, MISSING_FIELD, INVALID_FIELD, NOT_FOUND, DUPLICATE, and INTERNAL_ERROR.

Pagination

The product list supports cursor-based pagination using the after and
before query parameters, plus limit:

• after: Return results after this public ID
• before: Return results before this public ID
• limit: Number of results to return (default 10, max 100)
• after and before cannot be used together

The order and customer lists support after only. Order lists also accept
status and refund_status filters, and customer lists accept email and
search filters. Paginated responses include a has_more boolean.

Example:

GET /api/v1/products/?after=pro_d0b6fmv28q6vn14peun0&limit=20

Idempotency

To ensure safe retries of write operations (POST and PUT requests), you can provide an Idempotency-Key header. This prevents duplicate operations if a request is retried due to network issues or timeouts.

How it Works

1. Include an Idempotency-Key header with a unique string (1 to 255 characters) in your POST or PUT request
2. If the request succeeds, the response is cached for 24 hours
3. Subsequent requests with the same key return the cached response without executing the operation again
4. The X-Idempotency-Replayed header indicates whether the response was replayed from cache

Example

curl -X POST "https://studio.easel.engineering/api/v1/products/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "name": "Premium T-Shirt",
    "description": "High-quality cotton t-shirt"
  }'

Response Headers

• X-Idempotency-Replayed: false - Request was processed normally
• X-Idempotency-Replayed: true - Response was returned from cache

Important Notes

• Idempotency keys are scoped to your store and API key
• Only successful responses (2xx status codes) are cached
• The request body must match exactly for the cached response to be returned
• Different request methods or paths require different idempotency keys
• Keys are optional. Without a key, requests are processed normally

HTTP Status Codes

• 200 OK - Request successful
• 201 Created - Resource created
• 204 No Content - Request successful, no response body
• 400 Bad Request - Invalid request data
• 401 Unauthorized - Authentication required or invalid
• 403 Forbidden - Insufficient permissions
• 404 Not Found - Resource not found
• 405 Method Not Allowed - Unsupported HTTP method
• 409 Conflict - Resource already exists
• 429 Too Many Requests - Rate limit exceeded
• 500 Internal Server Error - Server error

Rate Limiting

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

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

When the limit is exceeded, the API returns 429 Too Many Requests.

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: pro_d0b6fmv28q6vn14peun0
• Orders: ord_d0b6fmv28q6vn14peun0
• Customers: cus_d0b6fmv28q6vn14peun0
• Variants: prv_d0b6fmv28q6vn14peun0
• Sites: sit_d0b6fmv28q6vn14peun0

Paginated list cursors use these public IDs.

Monetary Values

All monetary values are integers in the smallest currency unit for your store's currency (for example, cents for USD and yen for JPY):

{
  "price": 1999,
  "total": 2599
}

Platform Stats

GET /api/v1/platform/stats/ returns aggregate platform statistics. This
endpoint does not require authentication.

{
  "data": {
    "total_customers": 1000,
    "total_orders": 2500,
    "total_sales": 12500000,
    "total_trial_stores": 40,
    "total_paying_stores": 120,
    "arr": "12960.00",
    "updated_at": "2023-01-01T00:00:00Z"
  }
}

API Reference