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": "pro_d0b6fmv28q6vn14peun0",
  "name": "Example Product",
  "status": "active",
  "created_at": "2023-01-01T00:00:00Z"
}

List Responses

List endpoints return paginated results:

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

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
• Response includes has_more boolean indicating if additional results are available

Example:

GET /api/v1/products/?after=123

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 (max 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",
    "type": "simple"
  }'

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 - if not provided, requests are processed normally

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: pro_d0b6fmv28q6vn14peun0
• Orders: ord_d0b6fmv28q6vn14peun0
• Customers: cus_d0b6fmv28q6vn14peun0

Monetary Values

All monetary values are represented as integers in the smallest currency unit for your store's currency. The currency is set account-wide when you create your account (e.g., cents for USD, yen for JPY):

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

API Reference