← API Documentation

Orders API

Manage orders in your store. Orders represent customer purchases and can be in various states from pending to fulfilled.

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 ID to return orders after (e.g., `ord_d0b6fmv28q6vn14peun0`)
`status`	string	Filter by order status (`pending`, `paid`, `fulfilled`)
`refund_status`	string	Filter by refund status

Request

curl -X GET "https://studio.easel.engineering/api/v1/orders/?status=paid&after=ord_d0b6fmv28q6vn14peun0" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

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

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": "Failed to list orders",
  "code": "LIST_ERROR"
}

Get Order

Retrieve a single order by its public ID.

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" \
  -H "Content-Type: application/json"

Response

Status: 200 OK

{
  "id": "ord_d0b6fmv28q6vn14peun0",
  "number": 1001,
  "customer_id": "456",
  "status": "paid",
  "refund_status": "none",
  "shipping": 599,
  "total": 2599,
  "discount": 0,
  "discount_reason": null,
  "billing_zip": "12345",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z"
}

Error Responses

Missing order ID

Status: 400 Bad Request

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

Order not found

Status: 404 Not Found

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

Failed to get order

Status: 500 Internal Server Error

{
  "error": "Failed to get order",
  "code": "GET_ERROR"
}

Update Order

Update an existing order's status, discount, or other mutable fields.

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",
  "discount": 500,
  "discount_reason": "Customer service adjustment",
  "billing_zip": "54321"
}

Fields

Field	Type	Required	Description
`status`	string	Yes	Order status: `pending`, `paid`, or `fulfilled`
`discount`	integer	No	Discount amount in cents (must be non-negative)
`discount_reason`	string	No	Reason for the discount
`billing_zip`	string	No	Billing ZIP code

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",
    "discount": 500,
    "discount_reason": "Customer service adjustment"
  }'

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": "456",
  "status": "fulfilled",
  "refund_status": "none",
  "shipping": 599,
  "total": 2599,
  "discount": 500,
  "discount_reason": "Customer service adjustment",
  "billing_zip": "12345",
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T11:30:00Z"
}

Error Responses

Missing order ID

Status: 400 Bad Request

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

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"
}

Invalid discount

Status: 400 Bad Request

{
  "error": "Discount must be non-negative",
  "code": "INVALID_FIELD"
}

Order not found

Status: 404 Not Found

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

Failed to update order

Status: 500 Internal Server Error

{
  "error": "Failed to update order",
  "code": "UPDATE_ERROR"
}

Order updated but failed to retrieve

Status: 500 Internal Server Error

{
  "error": "Order updated but failed to retrieve",
  "code": "GET_ERROR"
}

Order Object

Fields

Field	Type	Description
`id`	string	Order public ID
`number`	integer	Human-readable order number
`customer_id`	string	Customer ID (as string)
`status`	string	Order status: `pending`, `paid`, `fulfilled`
`refund_status`	string	Refund status
`shipping`	integer	Shipping cost in cents
`total`	integer	Total order amount in cents
`discount`	integer	Discount amount in cents
`discount_reason`	string\|null	Reason for discount
`billing_zip`	string\|null	Billing ZIP code
`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/completed