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
• Shipments for shipping and tracking
• Refunds for refunds against an order
• Order Documents for the invoices and credit notes issued for an order
• Webhooks to be told when an order is created or canceled

Endpoints

• List Orders - GET /api/v1/orders/
• Get Order - GET /api/v1/orders/{order_id}/
• Update Order - PUT /api/v1/orders/{order_id}/
• List Order Events - GET /api/v1/orders/{order_id}/events/

List Orders

Retrieve a paginated list of orders for your store, oldest first. Each order is as whole as Get Order returns it, with its line items, taxes, downloads, and documents, so a tool catching up on orders needn’t fetch each one again. A tool’s first sync can start from a date with created_after.

Endpoint: GET /api/v1/orders/

Scope Required: orders:read

Query Parameters

Every page comes oldest first, whether you page forward with after or back with before. The response reports has_more, which is true when another page lies beyond this one in the direction you’re paging. after and before cannot be used together. The filters combine with each other and with the cursors. An invalid limit, status, refund_status, or created_after returns INVALID_REQUEST_ERROR.

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",
      "location_id": null,
      "status": "paid",
      "refund_status": "none",
      "currency": "USD",
      "shipping": 599,
      "total": 2598,
      "discount": 0,
      "discount_reason": null,
      "discount_code": null,
      "billing_country": "US",
      "billing_zip": "97204",
      "billing": {
        "name": "Sam Rivera",
        "email": "sam@example.com",
        "address": {
          "line1": "1120 SW 5th Ave",
          "line2": null,
          "city": "Portland",
          "region": "OR",
          "postal_code": "97204",
          "country": "US"
        }
      },
      "shipping_address": {
        "name": "Sam Rivera",
        "address": {
          "line1": "1120 SW 5th Ave",
          "line2": null,
          "city": "Portland",
          "region": "OR",
          "postal_code": "97204",
          "country": "US"
        }
      },
      "phone": "+15035551234",
      "shipping_needed": true,
      "items": [
        {
          "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
          "product_id": "pro_d0b6fmv28q6vn14peun0",
          "product_name": "Premium T-Shirt",
          "variant_name": "Small Red",
          "sku": "TS-S-RED",
          "quantity": 1,
          "price": 1999,
          "line_total": 1999,
          "delivery": "physical"
        }
      ],
      "downloads": [],
      "documents": [],
      "created_at": "2023-01-01T10:00:00Z",
      "updated_at": "2023-01-01T10:15:00Z",
      "canceled_at": null,
      "canceled_by": null,
      "gift_option": null,
      "gift_note": null,
      "shipping_rate": {"name": "Ground", "transit": {"min": 3, "max": 5}},
      "tax": 0,
      "prices_include_tax": false,
      "taxes": [],
      "gift_card": null,
      "amount_charged": 2598,
      "buyer": {
        "company": null,
        "tax_id": null,
        "tax_id_status": null,
        "vies": null
      },
      "reverse_charge": null,
      "non_eu_reverse_charge": null
    }
  ],
  "has_more": true
}

Error Responses

Invalid query parameter

Status: 400 Bad Request

A malformed after or before, both at once, an invalid limit, a status or refund_status that isn’t one of its values, or a created_after that isn’t an RFC 3339 time returns INVALID_REQUEST_ERROR, with the offending parameter named in the error message:

{
  "error": "Invalid 'created_after' parameter: must be an RFC 3339 time, such as 2026-01-01T00:00:00Z",
  "code": "INVALID_REQUEST_ERROR"
}

Cursor not found

An after or before that names no order of the store.

Status: 404 Not Found

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

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, with its line items, taxes, downloads for digital items, and documents.

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

Scope Required: orders:read

Path Parameters

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",
  "location_id": null,
  "status": "paid",
  "refund_status": "none",
  "currency": "USD",
  "shipping": 599,
  "total": 5040,
  "discount": 400,
  "discount_reason": "10% off",
  "discount_code": "WELCOME10",
  "billing_country": "US",
  "billing_zip": "90012",
  "billing": {
    "name": "Sam Rivera",
    "email": "sam@example.com",
    "address": {
      "line1": "200 N Spring St",
      "line2": "Apt 4",
      "city": "Los Angeles",
      "region": "CA",
      "postal_code": "90012",
      "country": "US"
    }
  },
  "shipping_address": {
    "name": "Sam Rivera",
    "address": {
      "line1": "1600 Sunset Blvd",
      "line2": null,
      "city": "Los Angeles",
      "region": "CA",
      "postal_code": "90026",
      "country": "US"
    }
  },
  "phone": "+13105551234",
  "shipping_needed": true,
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "product_id": "pro_d0b6fmv28q6vn14peun0",
      "product_name": "Premium T-Shirt",
      "variant_name": "Small Red",
      "sku": "TS-S-RED",
      "quantity": 1,
      "price": 1999,
      "line_total": 1999,
      "delivery": "physical"
    },
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun1",
      "product_id": "pro_d0b6fmv28q6vn14peun1",
      "product_name": "Ebook",
      "variant_name": "PDF",
      "sku": "",
      "quantity": 1,
      "price": 2001,
      "line_total": 2001,
      "delivery": "digital"
    }
  ],
  "downloads": [
    {
      "id": "ovd_d0b6fmv28q6vn14peun0",
      "product_name": "Ebook",
      "variant_name": "PDF",
      "download_url": "https://shop.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"
    }
  ],
  "documents": [
    {
      "id": "odc_d0b6fmv28q6vn14peun0",
      "kind": "invoice",
      "number": "INV-1001",
      "authority_code": null,
      "url": "https://invoices.example.com/d/8f2a1c/INV-1001.pdf",
      "issued_at": "2023-01-01T10:05:00Z",
      "refund_id": null,
      "external_source": "invoicing",
      "external_id": "48211",
      "created_at": "2023-01-01T10:05:03Z",
      "updated_at": "2023-01-01T10:05:03Z"
    }
  ],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T10:15:00Z",
  "canceled_at": null,
  "canceled_by": null,
  "gift_option": {
    "name": "Gift wrap",
    "description": "Kraft paper with a cotton ribbon.",
    "price": 500
  },
  "gift_note": "Happy birthday, Sam!",
  "shipping_rate": {"name": "Ground", "transit": {"min": 3, "max": 5}},
  "tax": 341,
  "prices_include_tax": false,
  "taxes": [
    {
      "country": "US",
      "region": "CA",
      "name": "Sales tax",
      "rate": "7.25",
      "taxable": 4699,
      "tax": 341,
      "tax_id": null
    }
  ],
  "gift_card": {
    "last4": "QX4P",
    "amount": 1000
  },
  "amount_charged": 4040,
  "buyer": {
    "company": null,
    "tax_id": null,
    "tax_id_status": null,
    "vies": null
  },
  "reverse_charge": null,
  "non_eu_reverse_charge": null
}

An order placed for no one, such as a sale in the shop to someone who gave no name or email, has customer_id set to null. A guest who checks out with an email is a customer, so their orders have one.

billing and shipping_address are personal data, so they are null unless the API key also has customers:read. See Billing Object and Shipping Address Object.

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/{order_id}/

Scope Required: orders:write

Path Parameters

Request Body

{
  "status": "fulfilled"
}

Fields

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",
  "location_id": null,
  "status": "fulfilled",
  "refund_status": "none",
  "currency": "USD",
  "shipping": 599,
  "total": 2598,
  "discount": 0,
  "discount_reason": null,
  "discount_code": null,
  "billing_country": "US",
  "billing_zip": "97204",
  "billing": null,
  "shipping_address": null,
  "phone": "+15035551234",
  "shipping_needed": true,
  "items": [
    {
      "order_variant_id": "orv_d0b6fmv28q6vn14peun0",
      "product_id": "pro_d0b6fmv28q6vn14peun0",
      "product_name": "Premium T-Shirt",
      "variant_name": "Small Red",
      "sku": "TS-S-RED",
      "quantity": 1,
      "price": 1999,
      "line_total": 1999,
      "delivery": "physical"
    }
  ],
  "downloads": [],
  "documents": [],
  "created_at": "2023-01-01T10:00:00Z",
  "updated_at": "2023-01-01T11:30:00Z",
  "canceled_at": null,
  "canceled_by": null,
  "gift_option": null,
  "gift_note": null,
  "shipping_rate": {"name": "Ground", "transit": {"min": 3, "max": 5}},
  "tax": 0,
  "prices_include_tax": false,
  "taxes": [],
  "gift_card": null,
  "amount_charged": 2598,
  "buyer": {
    "company": null,
    "tax_id": null,
    "tax_id_status": null,
    "vies": null
  },
  "reverse_charge": null,
  "non_eu_reverse_charge": null
}

This example’s key lacks customers:read, so billing and shipping_address are null.

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

List Order Events

Retrieve an order’s history, newest first: what happened to it, when, and who did it. Events are read-only. Easel records each one in the same transaction as the change it describes, such as a refund or a shipment, and never edits or deletes them; a correction is a later event.

Endpoint: GET /api/v1/orders/{order_id}/events/

Scope Required: orders:read

Query Parameters

Events come newest first either way. The response reports has_more, which is true when more events follow in the direction of travel: older ones, or newer ones with before. A malformed after or before, both at once, or an invalid limit returns INVALID_REQUEST_ERROR.

Request

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

Response

Status: 200 OK

{
  "data": [
    {
      "id": "oev_d0b6fmv28q6vn14pev05",
      "type": "status_changed",
      "actor": { "type": "user", "name": "Ada" },
      "details": { "from": "paid", "to": "fulfilled" },
      "created_at": "2023-01-02T09:00:00Z"
    },
    {
      "id": "oev_d0b6fmv28q6vn14pev04",
      "type": "shipment_created",
      "actor": { "type": "user", "name": "Ada" },
      "details": {
        "shipment_id": "shp_d0b6fr728q6vn14peuu0",
        "shipment_number": 1,
        "items": [
          { "order_variant_id": "orv_d0b6fmv28q6vn14peuog", "quantity": 1 }
        ]
      },
      "created_at": "2023-01-02T09:00:00Z"
    },
    {
      "id": "oev_d0b6fmv28q6vn14pev02",
      "type": "paid",
      "actor": { "type": "customer", "name": null },
      "details": { "amount": 2598 },
      "created_at": "2023-01-01T10:00:00Z"
    }
  ],
  "has_more": true
}

Error Responses

Order not found

Status: 404 Not Found

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

Order Event Object

Actor Object

Event Types

Amounts are in the store’s smallest currency unit. Each item in items has an order_variant_id and a quantity. New event types may be added, so ignore types you don’t recognize.

Order Object

Fields

Billing Object

Who the order is billed to, shown only to an API key with customers:read.

The address object:

Shipping Address Object

Where the order’s goods go, shown only to an API key with customers:read. Use it, not billing_country, for the goods’ destination, which decides, for example, whether a sale is an export.

Buyer Object

The company and tax number the buyer gave at checkout, for their invoice, and how the tax number was checked. Checkout asks for them only when the store has an EU VAT registration: its home, its primary site’s default country, is in the EU, or it has a tax registration in an EU country. For any other store every field is always null.

The vies object:

Reverse Charge

A sale from an EU business to a business in another EU country is reverse charged: the seller charges no VAT, and the buyer accounts for it in their own country. Checkout reverse charges an order only when all of these hold:

• The store is VAT registered in the EU country it’s established in, its home, which is its primary site’s default country, with a whole-country tax registration there
• The buyer gave an EU VAT number and VIES verified it. When VIES can’t answer, VAT is charged as usual
• The VAT number is from the buyer’s billing country, and that country isn’t the store’s home. A buyer in the store’s own country pays VAT like anyone there
• Goods ship to the VAT number’s country. Digital products, which EU VAT treats as electronically supplied services, are supplied where the buyer is established, so the sale’s tax destination must be the VAT number’s country
• A Northern Ireland (XI) VAT number covers goods only, shipped to Northern Ireland itself, a BT postcode; goods to Great Britain are an export
• An order of goods and digital products is reverse charged only when both parts would be. An order of only gift cards supplies nothing yet, so it isn’t

The legal basis is the VAT Directive: Article 138 for goods, and Article 196 for services. The invoice for a reverse-charged order must say “Reverse charge”, cite the exemption for its supply_kind, and show the store’s VAT number, seller_tax_id.

A reverse-charged order has tax 0, an empty taxes, and a total of the net the buyer paid. When prices include tax, the VAT in them comes off instead, as deduction, so the buyer pays the net price and the merchant receives what they would from a consumer.

goods and services split the discount between them by value, so together they add up to what the buyer paid for everything but gift cards.

These are the fields of a reverse-charged order from a store in Portugal to a German business, with prices that include VAT:

{
  "currency": "EUR",
  "total": 10500,
  "billing_country": "DE",
  "tax": 0,
  "prices_include_tax": true,
  "taxes": [],
  "buyer": {
    "company": "Beispiel GmbH",
    "tax_id": "DE123456789",
    "tax_id_status": "verified",
    "vies": {
      "consultation_number": "WAPIAAAAZ3x5Fv9B",
      "name": "Beispiel GmbH",
      "address": "Hauptstr. 1, 10115 Berlin",
      "checked_at": "2026-10-01T09:00:00Z"
    }
  },
  "reverse_charge": {
    "supply_kind": "goods",
    "deduction": 2415,
    "goods": 10500,
    "services": 0,
    "seller_tax_id": "PT512345678"
  }
}

Non-EU Sellers

A store established outside the EU, its home being outside the EU, may still be registered for EU VAT, through the non-Union One-Stop Shop or directly in an EU country, and charges EU consumers VAT. It charges an EU business no VAT, and sets non_eu_reverse_charge, only when all of these hold:

• The store has a tax registration in an EU country
• The buyer gave an EU VAT number of their billing country, and VIES verified it. When VIES can’t answer, VAT is charged as usual
• A Northern Ireland (XI) number never qualifies
• Digital products, which EU VAT treats as electronically supplied services, are taxed where the buyer is (VAT Directive Art. 44) and the buyer accounts for the VAT (Art. 196). The sale’s tax destination must be the VAT number’s country, and the store must have no location there: a location there may take part in the sale, which would make the store established there for it (Art. 192a), so VAT is charged
• Goods must ship to the VAT number’s country from outside the EU, with duties and import VAT unpaid, so that the buyer imports them and pays the import VAT (Art. 201); the One-Stop Shop for imports covers only sales to consumers. A store that clears customs itself (duties paid) sells the goods inside the EU and must not rely on this. A store with any location in an EU country charges VAT on goods, since they could ship from inside the EU
• An order of goods and digital products qualifies only when both parts would

non_eu_reverse_charge has the same fields as reverse_charge, but supply_kind says why no VAT was charged, which the invoice must say too:

seller_tax_id is the store’s VAT number from a registration directly in an EU country, preferring the buyer’s, or null for a store registered only through the non-Union One-Stop Shop, whose number is for that scheme’s returns alone.

The EC sales list includes these orders’ services, which a store identified for VAT in an EU country must report (Art. 262(1)©), when the store is registered directly in an EU country. Their goods, being imports, never appear, and a store registered only through the non-Union One-Stop Shop has no EC sales list to file.

Order Shipping Rate Object

The shipping rate as the buyer chose it. It is copied onto the order at purchase, so renaming, repricing, or deleting the site’s rate later never changes it. Its price at purchase is the order’s shipping.

Gift Option Object

The gift option as the buyer bought it. It is copied onto the order at purchase, so editing or deleting the site’s gift option later never changes it.

The gift option’s price is part of total, charged on its own apart from the items and shipping. A discount code never reduces it, and a refund can cover it like any other part of the total.

Gift Cards

When a gift card paid part or all of an order, gift_card names it by the last four characters of its code and says how much it paid, and amount_charged is what was charged to the buyer’s card. An order a gift card paid in full has an amount_charged of 0. See Gift Cards.

Order History Events

An order’s history (GET /api/v1/orders/{order_id}/events/) records gift cards with these event types. Their details carry gift_card_id and gift_card_last4, never the code:

• gift_card_redeemed - A gift card paid amount of the order
• gift_card_issued - The order bought a gift card worth amount, emailed to the address in to
• gift_card_refunded - A refund put amount back on the gift card, with refund_id

An order a gift card paid in full has no paid event, since nothing was charged.

Order Status Values

• pending - Order created but not yet paid
• paid - Payment received
• fulfilled - Every item has shipped, or the order had nothing to ship

Canceled Orders

A buyer with a storefront account can cancel their own order for a short time after paying, set per site by cancel_window_minutes (see Sites), as long as no shipment exists and no download link has been used. Canceling refunds the order in full through Stripe, puts its shipped items back on stock, and revokes its download links.

A canceled order keeps its status, has refund_status refunded, and sets canceled_at and canceled_by. It can’t take a shipment: creating one returns 409 Conflict with the code ORDER_CANCELED.

Order Item Object

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

product_name, variant_name, sku, and delivery are kept from checkout, so renaming or changing the product later doesn’t change them. A line sold before Easel kept them shows what the product is now instead, and a delivery of physical if the product is gone. A gift_card line is a multi-purpose voucher, which isn’t taxed when it’s sold.

Order Tax Object

The taxes array breaks an order’s tax down by the jurisdictions that charged it, as they were when the order was placed. They never change afterward, even if the store’s registrations or rates do. A reverse-charged order has none.

Download Object

See Order Downloads for the full download object.