← API Documentation

Orders API

Manage orders in your store. An order is a customer purchase, moving
through a few statuses from pending to fulfilled.

Related resources:

Order Downloads for digital delivery
Fulfillments for shipping and tracking
Refunds for refunds against an order

Endpoints

List Orders - GET /api/v1/orders/
Get Order - GET /api/v1/orders/{id}/
Update Order - PUT /api/v1/orders/{id}/

List Orders

Retrieve a paginated list of orders for your store.

Endpoint: GET /api/v1/orders/

Permission Required: Read

Query Parameters

Parameter	Type	Description
`after`	string	Cursor for pagination. Order public ID to return orders after
`status`	string	Filter by order status (`pending`, `paid`, `fulfilled`)
`refund_status`	string	Filter by refund status (`none`, `partially_refunded`, `refunded`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/?status=paid" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "data": [
    {
      "id": "ord_d0b6fmv28q6vn14peun0",
      "number": 1001,
      "customer_id": "cus_d0b6fmv28q6vn14peun0",
      "status": "paid",
      "refund_status": "none",
      "shipping": 599,
      "total": 2599,
      "discount": 0,
      "discount_reason": null,
      "billing_zip": "12345",
      "shipping_needed": true,
      "items": [],
      "downloads": [],
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z"
    }
  ],
  "has_more": true
}

The list response does not load line items or downloads, so items and
downloads are empty. Fetch a single order to see them.

Error Responses

Invalid cursor parameter

Status: 400 Bad Request

{
  "error": "Invalid 'after' parameter",
  "code": "INVALID_FIELD"
}

Failed to list orders

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Get Order

Retrieve a single order by its public ID. This response includes the order's
line items and its downloads for digital items.

Endpoint: GET /api/v1/orders/{id}/

Permission Required: Read

Path Parameters

Parameter	Type	Description
`id`	string	Order public ID (e.g., `ord_d0b6fmv28q6vn14peun0`)

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here"

Response

Status: 200 OK

{
  "id": "ord_d0b6fmv28q6vn14peun0",
  "number": 1001,
  "customer_id": "cus_d0b6fmv28q6vn14peun0",
  "status": "paid",
  "refund_status": "none",
  "shipping": 599,
  "total": 2599,
  "discount": 0,
  "discount_reason": null,
  "billing_zip": "12345",
  "shipping_needed": true,
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "product_id": "pro_d0b6fmv28q6vn14peun0",
      "product_name": "Premium T-Shirt",
      "variant_name": "Small Red",
      "quantity": 1,
      "price": 1999
    }
  ],
  "downloads": [
    {
      "id": "dwn_d0b6fmv28q6vn14peun0",
      "product_name": "Ebook",
      "variant_name": "PDF",
      "download_url": "https://studio.easel.engineering/downloads/...",
      "download_count": 1,
      "downloads_remaining": 4,
      "status": "active",
      "expires_at": "2023-02-01T10:00:00Z",
      "created_at": "2023-01-01T10:00:00Z"
    }
  ],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z"
}

A guest order has customer_id set to null.

Error Responses

Order not found

Status: 404 Not Found

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

Failed to get order

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Update Order

Update an existing order's status.

Endpoint: PUT /api/v1/orders/{id}/

Permission Required: Write

Path Parameters

Parameter	Type	Description
`id`	string	Order public ID (e.g., `ord_d0b6fmv28q6vn14peun0`)

Request Body

{
  "status": "fulfilled"
}

Fields

Field	Type	Required	Description
`status`	string	Yes	Order status: `pending`, `paid`, or `fulfilled`

Discounts and billing details are not editable through this endpoint.

Request

curl -X PUT "https://studio.easel.engineering/api/v1/orders/ord_d0b6fmv28q6vn14peun0/" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -d '{
    "status": "fulfilled"
  }'

Optional Headers:

Idempotency-Key: Unique string to prevent duplicate order updates (see Idempotency)

Response

Returns the updated order.

Status: 200 OK

{
  "id": "ord_d0b6fmv28q6vn14peun0",
  "number": 1001,
  "customer_id": "cus_d0b6fmv28q6vn14peun0",
  "status": "fulfilled",
  "refund_status": "none",
  "shipping": 599,
  "total": 2599,
  "discount": 0,
  "discount_reason": null,
  "billing_zip": "12345",
  "shipping_needed": true,
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "product_id": "pro_d0b6fmv28q6vn14peun0",
      "product_name": "Premium T-Shirt",
      "variant_name": "Small Red",
      "quantity": 1,
      "price": 1999
    }
  ],
  "downloads": [],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T11:30:00Z"
}

Error Responses

Invalid JSON body

Status: 400 Bad Request

{
  "error": "Invalid JSON body",
  "code": "INVALID_JSON"
}

Missing required field

Status: 400 Bad Request

{
  "error": "Order status is required",
  "code": "MISSING_FIELD"
}

Invalid status

Status: 400 Bad Request

{
  "error": "Status must be 'pending', 'paid', or 'fulfilled'",
  "code": "INVALID_FIELD"
}

Order not found

Status: 404 Not Found

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

Failed to update order

Status: 500 Internal Server Error

{
  "error": "Internal server error",
  "code": "INTERNAL_ERROR"
}

Order Object

Fields

Field	Type	Description
`id`	string	Order public ID
`number`	integer	Human-readable order number
`customer_id`	string\|null	Customer public ID, or `null` for a guest order
`status`	string	Order status: `pending`, `paid`, `fulfilled`
`refund_status`	string	`none`, `partially_refunded`, or `refunded`
`shipping`	integer	Shipping cost in the store's smallest currency unit
`total`	integer	Total order amount in the store's smallest currency unit
`discount`	integer	Discount amount in the store's smallest currency unit
`discount_reason`	string\|null	Reason for the discount
`billing_zip`	string\|null	Billing ZIP code
`shipping_needed`	boolean	Whether the order contains physical items
`items`	array	Order line items (single order only)
`downloads`	array	Download records for digital items (single order only)
`created_at`	string	ISO 8601 timestamp
`updated_at`	string	ISO 8601 timestamp

Order Status Values

pending - Order created but not yet paid
paid - Payment received
fulfilled - Order shipped or completed

Order Item Object

The items array lists the line items on an order. The order_variant_id is
the value you pass to the Fulfillments endpoints when you
ship all or part of an order.

Field	Type	Description
`order_variant_id`	string	Ordered line item public ID, used in fulfillments
`product_id`	string	Product public ID
`product_name`	string	Product name
`variant_name`	string	Variant name
`quantity`	integer	Quantity ordered
`price`	integer	Unit price in the store's smallest currency unit

Download Object

See Order Downloads for the full download object.