Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Carts, Checkout, Introduction Orders API
description: 'A cart contains a list of the products that a shopper adds to the cart while browsing your catalog. In the context of a cart, a selected product is called a cart item.
A cart item identifies the product, the product price, the quantity selected, and the total price for the quantity selected. The cart displays a running total of the cost for the selected products plus the calculated tax.
You can allow your shoppers to add custom text to a product when adding an item to their carts. This is useful, for example, if you have a product like a T-shirt that can be personalized. See [Add product to cart](/docs/api/carts/manage-carts#add-product-to-cart).
After a shopper checks out, the cart is converted to an order, and you can manually delete the cart. If you don''t delete the cart, it is purged automatically after seven days.
The preview cart feature allows you to set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart. See [Create a Preview Cart](/docs/api/carts/create-a-cart#preview-cart).
The following diagram shows a typical cart workflow:
### Multiple Carts
Buyers often make purchases based on jobs that they need to perform or outcomes they need to achieve and therefore require more than one shopping cart. For example, a corporate buyer places orders for multiple locations. Each location has a different frequency of ordering and require different products. The buyer can create one cart per location, fill the carts, and then check out the carts quickly. Similarly, shoppers can also create multiple carts for the ease of managing various shopping experiences, such as birthdays or holidays.
Each cart is discrete and separate. Any updates or changes to one cart has no effect on the other carts. A cart persists, that is, it stays with the buyer or shopper even after they use the cart in a checkout. Carts remain available after a checkout.
'
contact:
name: Elastic Path
url: https://elasticpath.com
version: 26.0313.7324347
x-version-timestamp: 2026-03-13 21:22:42+00:00
license:
name: MIT
url: assets/LICENSE
servers:
- url: https://useast.api.elasticpath.com
description: US East Production Server
variables: {}
- url: https://euwest.api.elasticpath.com
description: EU West Production Server
variables: {}
security:
- bearerAuth: []
tags:
- name: Orders
description: 'An Order is created through the [checkout](/docs/api/carts/checkout) endpoint within the Carts API.
An order is created after a customer checks out their cart. On creation, the order is marked unpaid. The customer is prompted for a shipping address, a billing address, and a payment method. After the order is successfully paid, you can trigger an inventory process and a shipping process.
You can keep a history of orders associated with the customer account.
### Reorder
A re-order is when a shopper copies items from a previous order from their order history into a cart of their choice. If a shopper re-orders to an empty cart, the same quantities as the past order are applied. If the shopper re-orders to an existing cart, and orders the same item, the quantity increases. If an item is out of stock, the item is not added to the cart, and the shopper sees an insufficient stock error. The tax for the items in a re-order is not applied. For more information, see [Tax Items](/docs/api/carts/tax-items).
'
paths:
/v2/orders:
parameters: []
get:
tags:
- Orders
summary: Get all Orders
description: 'This endpoint returns all orders with custom flow fields. The pagination offset is set to fetch a maximum of 10,000 orders. If the store has 10,000 orders, and you fetch the orders without using filters, an error is returned. Use a filter to view orders when the order is beyond the 10,000 mark.
:::note
- Pass the `X-Moltin-Customer-Token` header to limit orders to a specific customer. See [Customer Tokens](/docs/customer-management/customer-management-api/customer-tokens).
- Pass the `EP-Account-Management-Authentication-Token` header to limit orders to a specific account. See [Account Management Token](/docs/api/accounts/post-v-2-account-members-tokens).
- You can use pagination with this resource. For more information, see [pagination](/guides/Getting-Started/pagination).
:::
### Filtering
The following operators and attributes are available for filtering orders.
| Attribute | Type | Operator | Example |
| :--- | :--- | :--- | :--- |
| `status` | `string` | `eq` | `eq(status,complete)` |
| `payment` | `string` | `eq` | `eq(payment,paid)` |
| `shipping` | `string` | `eq` | `eq(shipping,unfulfilled)` |
| `name` (`customer.name`) | `string` | `eq` / `like` | `like(name,Brad*)` |
| `email` (`customer.email`) | `string` | `eq` / `like` | `like(email,*@elasticpath.com)` |
| `customer_id` | `string` | `eq` / `like` | `eq(customer_id, e5a0d684-a4af-4919-a348-f66b0b4955e0)` |
| `account_id` | `string` | `eq` / `like` | `eq(account_id,3d7200c9-a9bc-4085-9822-63e80fd94a09)` |
| `account_member_id` | `string` | `eq` / `like` | `eq(account_member_id,2a8a3a92-2ccd-4b2b-a7af-52d3896eaecb)` |
| `contact.name` | `string` | `eq` / `like` | `eq(name,John Doe)` |
| `contact.email` | `string` | `eq` / `like` | `eq(email,John Doe)` |
| `shipping_postcode` | `string` | `eq` / `like` | `like(shipping_postcode,117*)` |
| `billing_postcode` | `string` | `eq` / `like` | `like(billing_postcode,117*)` |
| `with_tax` | `integer` | `gt`/`ge`/`lt`/`le` | `ge(with_tax,10000)` |
| `without_tax` | `integer` | `gt`/`ge`/`lt`/`le` | `ge(without_tax,10000)` |
| `currency` | `string` | `eq` | `eq(currency,USD)` |
| `product_id` | `string` | `eq` | `eq(product_id,6837058c-ae42-46db-b3c6-7f01e0c34b40)` |
| `product_sku` | `string` | `eq` | `eq(product_sku,deck-shoe-001)` |
| `created_at` | `date` | `eq` / `gt` / `ge`/ `le` / `lt` | `gt(created_at,YYYY-MM-DD)` |
| `updated_at` | `date` | `eq` / `gt` / `ge`/ `le`/ `lt` | `lt(updated_at,YYYY-MM-DD)` |
| `external_ref` | `string` | `eq` / `like` | `like(external_ref, 16be*)` |
| `order_number` | `string` | `eq` / `like` | `like(order_number, 123*)` |
### Includes
You can include related resources with the order response by using the `include` query parameter.
| Name | Optional | Type | Description | |:-----|:---------|:-----|:------------| | `include` | Optional | `string` | Comma-delimited string of entities that can be included. The information included are `items`, `tax_items`, `custom_discounts`, or `promotions`. |
'
operationId: getCustomerOrders
parameters:
- name: x-moltin-customer-token
in: header
description: A customer token to access a specific customer's orders.
style: simple
schema:
type: string
examples:
- '{{customerToken}}'
- name: include
in: query
description: Comma-delimited string of entities to include (items, tax_items, custom_discounts, promotions).
required: false
style: form
explode: false
schema:
type: string
examples:
- items
- items,tax_items
- items,tax_items,custom_discounts
- name: page[limit]
in: query
description: The maximum number of records per page.
required: false
style: form
explode: true
schema:
type: integer
minimum: 1
maximum: 100
default: 20
- name: page[offset]
in: query
description: The number of records to offset the results by.
required: false
style: form
explode: true
schema:
type: integer
minimum: 0
maximum: 10000
default: 0
- name: filter
in: query
description: Filter expression for searching orders. See filtering documentation for available operators and attributes.
required: false
style: form
explode: false
schema:
type: string
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/OrderCollectionResponse'
deprecated: false
/v2/orders/{orderID}:
parameters: []
get:
tags:
- Orders
summary: Get an Order
description: 'Use this endpoint to retrieve a specific order.
### Includes
You can include related resources with the order response by using the `include` query parameter.
| Name | Required | Type | Description |
|:----------|:---------|:---------|:------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The included options are `items`, `tax_items`, `custom_discounts`, or `promotions`. |'
operationId: getAnOrder
parameters:
- name: orderID
in: path
description: The ID of the order.
required: true
style: simple
schema:
type: string
- name: include
in: query
description: Comma-delimited string of entities to include (items, tax_items, custom_discounts, promotions).
required: false
style: form
explode: false
schema:
type: string
examples:
- items
- items,tax_items
- items,tax_items,custom_discounts
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEntityResponse'
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Order not found
value: "{\n \"errors\": [\n {\n \"detail\": \"Order not found\",\n \"status\": \"404\",\n \"title\": \"Not Found\"\n }\n ]\n}\n"
deprecated: false
put:
tags:
- Orders
summary: Update an Order
description: "You can only update custom data, `shipping`, `shipping_address`, and status of orders. All other settings in the order object are immutable.\n\n This endpoint allows you to:\n\n- **Update an order number and external reference**: You can update an existing order that does not have an `order_number` and `external_ref`, modify the `order_number` and `external_ref` values, or remove them by passing an empty value in the `order_number` and `external_ref` fields.\n- **Cancel an order**: You can cancel an order only if it has not been fulfilled.\n- **Fulfill an order**: You can fulfill a paid order only.\n\n:::caution\n\nYou can update `shipping`, `shipping_address`, and status of an order only if the order is not fulfilled. You can use the refund API to refund an order only if the payment status is `paid`. Canceling an order does not automatically refund a payment. You must refund the orders manually.\n\n:::\n\n:::note\n\n- This request is only accessible to client credentials token users with Seller Admin role.\n- Non client credentials token users cannot access this endpoint. See [Permissions](/docs/authentication/tokens/permissions).\n- The `order_number` will appear as the invoice number in Authorize.net transactions.\n\n:::\n"
operationId: updateAnOrder
parameters:
- name: orderID
in: path
description: The unique identifier of the order.
required: true
style: simple
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrdersUpdateRequest'
examples:
CancelAnOrder:
summary: Cancel an Order
value:
data:
type: order
status: cancelled
FulfillAnOrder:
summary: Fulfill an Order by ID. You can fulfill a paid order only.
value:
data:
type: order
shipping: fulfilled
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Bad Request
value: "{\n \"errors\": [\n {\n \"detail\": \"Request could not be processed\",\n \"status\": \"400\",\n \"title\": \"Bad Request\"\n }\n ]\n}\n"
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Validation error
value: "{\n \"errors\": [\n {\n \"detail\": \"Order cannot be updated in its current state\",\n \"status\": \"422\",\n \"title\": \"Unprocessable Entity\"\n }\n ]\n}\n"
deprecated: false
/v2/orders/{orderID}/items:
parameters: []
get:
tags:
- Orders
summary: Get Order Items
description: 'Use this endpoint to retrieve order items.
### Includes
You can include related resources with the order items response by using the `include` query parameter.
| Name | Required | Type | Description |
|:----------|:---------|:---------|:------------|
| `include` | Optional | `string` | Comma-delimited string of entities that can be included. The included options are `tax_items`, `custom_discounts`, or `promotions`. |'
operationId: getOrderItems
parameters:
- name: orderID
in: path
description: The ID of the order.
required: true
style: simple
schema:
type: string
- name: include
in: query
description: Comma-delimited string of entities to include (tax_items, custom_discounts, promotions).
required: false
style: form
explode: false
schema:
type: string
examples:
- tax_items
- tax_items,custom_discounts
- tax_items,custom_discounts,promotions
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/OrderItemCollectionResponse'
deprecated: false
/v2/orders/anonymize:
parameters: []
post:
tags:
- Orders
summary: Anonymize Orders
description: 'You can anonymize an order when it is fulfilled, canceled, or fully refunded.
When anonymization is successful, Personal Identifiable Information such as customer details, `shipping_address`, and `billing_address` are replaced with *.
'
operationId: anonymizeOrders
parameters: []
requestBody:
description: ''
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/OrdersAnonymizeRequest'
- examples:
- data:
order_ids:
- '{{orderID}}'
contentMediaType: application/json
examples:
default:
value:
data:
order_ids:
- '{{orderID}}'
required: false
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrdersListResponse'
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
example:
errors:
- detail: 'Order has status: order:incomplete, payment:unpaid, shipping:unfulfilled; only fulfilled or refunded or cancelled orders may be anonymized'
status: 422
title: Could not anonymize orders
meta:
order_id: 496c29a1-6e7a-4ab6-a4e7-d1ec9a08b85e
deprecated: false
/v2/orders/{orderID}/confirm:
parameters: []
post:
tags:
- Orders
summary: Confirm Order
description: 'Use this endpoint to confirm an order. Confirming an order finalizes it and makes it ready for processing.
'
operationId: confirmOrder
parameters:
- name: orderID
in: path
description: The unique identifier of the order to confirm.
required: true
style: simple
schema:
type: string
responses:
'200':
description: Order confirmed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Required field missing
value: "{\n \"errors\": [\n {\n \"detail\": \"Request could not be processed\",\n \"status\": \"400\",\n \"title\": \"Bad Request\"\n }\n ]\n}\n"
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Order not found
value: "{\n \"errors\": [\n {\n \"detail\": \"Order not found\",\n \"status\": \"404\",\n \"title\": \"Not Found\"\n }\n ]\n}\n"
'422':
description: Unprocessable Entity
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
examples:
default:
summary: Validation error
value: "{\n \"errors\": [\n {\n \"detail\": \"Order cannot be confirmed in its current state\",\n \"status\": \"422\",\n \"title\": \"Unprocessable Entity\"\n }\n ]\n}\n"
components:
schemas:
OrderPriceData:
title: OrderPriceData
type: object
properties:
amount:
description: The amount for this item.
type: number
examples:
- 10000
currency:
description: The currency this item.
type: string
examples:
- USD
includes_tax:
description: Whether this price is tax inclusive.
type: boolean
examples:
- false
Response.Meta.Orders:
type: object
properties:
page:
$ref: '#/components/schemas/Response.PaginationPage'
results:
$ref: '#/components/schemas/Response.PaginationResults'
AddressCommon:
type: object
required:
- first_name
- last_name
- line_1
- postcode
- country
properties:
first_name:
description: First name of the recipient.
type: string
examples:
- John
last_name:
description: Last name of the recipient.
type: string
examples:
- Doe
company_name:
description: Company of the recipient.
type: string
examples:
- John Doe Enterprises
line_1:
description: First line of the address.
type: string
examples:
- 1 Sunny Street
line_2:
description: Second line of the address.
type: string
examples:
- Apartment 123
city:
description: City of the address.
type: string
examples:
- Los Angeles
postcode:
description: Post code of the address.
type: string
examples:
- '92802'
county:
description: County of the address.
type: string
examples:
- Orange
country:
description: Country of the address.
type: string
examples:
- US
region:
description: State, province, or region of the address.
type: string
examples:
- CA
Response.PageLinks:
type: object
properties:
current:
description: Always the current page.
type: string
first:
description: Always the first page.
type: string
last:
description: If there is only one page, it is `null`.
type: string
next:
description: If there is only one page, it is `null`.
type: string
prev:
description: if the user is on the first page, it is `null`.
type: string
RelationshipItem:
title: RelationshipItem
description: Relationship data entry
required:
- type
- id
type: object
properties:
type:
description: The type of related resource.
type: string
id:
description: The ID of the related resource.
type: string
format: uuid
Response.PaginationResults:
type: object
properties:
total:
description: The total page count.
type: integer
RelationshipArray:
title: RelationshipArray
description: Array of relationships
type: object
properties:
data:
description: Individual relationships
type: array
items:
$ref: '#/components/schemas/RelationshipItem'
OrdersListResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/OrderResponse'
required:
- data
OrderEntityResponse:
title: OrderEntityResponse
type: object
properties:
data:
$ref: '#/components/schemas/OrderResponse'
included:
description: 'Optional included data such as order items, tax items, custom discounts, and promotions.
'
type: object
properties:
items:
description: Array of order items included in the response.
type: array
items:
$ref: '#/components/schemas/OrderItemResponse'
tax_items:
description: Array of tax items included in the response.
type: array
items:
$ref: '#/components/schemas/TaxItemResponse'
custom_discounts:
description: Array of custom discounts included in the response.
type: array
items:
$ref: '#/components/schemas/CustomDiscountResponse'
promotions:
description: Array of promotions included in the response.
type: array
items:
$ref: '#/components/schemas/CondensedPromotionResponse'
errors:
type: array
description: Array of error objects, if any errors occurred.
items:
$ref: '#/components/schemas/Response.ErrorItem'
CustomAttributes:
title: CustomAttributes
type: object
description: "Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n \"is_member\": {\n \"type\": \"boolean\",\n \"value\": true\n },\n \"membership_level\": {\n \"type\": \"string\",\n \"value\": \"premium\"\n }\n}\n```\n"
additionalProperties:
type: object
required:
- type
- value
properties:
type:
type: string
description: The type of the custom attribute value.
enum:
- string
- integer
- boolean
- float
value:
description: The value of the custom attribute.
type:
- string
- boolean
- number
Response.PaginationPage:
type: object
properties:
current:
description: The current page.
type: integer
limit:
description: The maximum number of records per page for this response. You can set this value up to 100.
type: integer
offset:
description: The current offset by number of records, not pages. Offset is zero-based.
type: integer
total:
description: The total page count.
type: integer
TransactionEntityResponse:
type: object
properties:
data:
type: object
$ref: '#/components/schemas/TransactionResponse'
required:
- data
OrderResponse:
title: OrderResponse
type: object
properties:
type:
description: Specifies the type of object being returned. You must use `order`.
type: string
const: order
order_number:
description: Specifies a user-managed, optional field used as an alternative to the existing `order_id`. If provided, the order-number will be sent to Authorize.net instead of the `order_id`, and will appear as the invoice number in Authorize.net transactions.
type: string
examples:
- 1234
external_ref:
description: An optional external ID reference for an order. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. It can be used to include an external reference from a separate company system.
type: string
examples:
- e-123456789
id:
description: Specifies the unique identifier of the order.
type: string
format: uuid
readOnly: true
examples:
- aa854b8f-5930-476d-951a-e9b9cfbdefb1
status:
description: Specifies the status of the order, such as `incomplete`, `complete`, `processing`, or `cancelled`.
type: string
enum:
- complete
- incomplete
- cancelled
- processing
payment:
description: Specifies the status of the payment, such as `unpaid`, `authorized`, `paid`, or `refunded`.
type: string
enum:
- authorized
- paid
- unpaid
- refunded
- partially_paid
- partially_authorized
shipping:
description: Specifies the status of the shipment, such as `fulfilled` or `unfulfilled`.
type: string
enum:
- unfulfilled
- fulfilled
anonymized:
description: Specifies if the order is anonymized.
type: boolean
examples:
- false
payment_intent_id:
description: Stripe Payment Intent ID. Please see Stripe's Payment Intent [documentation](https://docs.stripe.com/api/payment_intents) for more information on Payment Intents.
type: string
examples:
- pi_3MtwBwLkdIwHu7ix28a3tqPa
custom_attributes:
$ref: '#/components/schemas/CustomAttributes'
links:
type: object
meta:
$ref: '#/components/schemas/OrderMeta'
billing_address:
$ref: '#/components/schemas/BillingAddress'
contact:
$ref: '#/components/schemas/Contact'
customer:
$ref: '#/components/schemas/Customer'
shipping_address:
$ref: '#/components/schemas/ShippingAddress'
relationships:
type: object
properties:
items:
$ref: '#/components/schemas/RelationshipArray'
custom_discounts:
$ref: '#/components/schemas/RelationshipArray'
promotions:
$ref: '#/components/schemas/RelationshipArray'
customer:
$ref: '#/components/schemas/SingleRelationship'
account:
$ref: '#/components/schemas/SingleRelationship'
account_member:
$ref: '#/components/schemas/SingleRelationship'
store:
$ref: '#/components/schemas/SingleRelationship'
OrderMeta:
title: OrderMeta
type: object
properties:
timestamps:
$ref: '#/components/schemas/OrderTimestamps'
display_price:
description: Order pricing information including amounts, tax, discounts, and payment details.
type: object
properties:
with_tax:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
without_tax:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
tax:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
discount:
$ref: '#/components/schemas/DiscountFormattedPriceData'
balance_owing:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
paid:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
authorized:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
without_discount:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
shipping:
$ref: '#/components/schemas/NonNegativeFormattedPriceData'
shipping_discount:
$ref: '#/components/schemas/DiscountFormattedPriceData'
is_manual:
description: Specifies if the order was created manually.
type: boolean
OrdersUpdateRequest:
title: OrdersUpdateRequest
type: object
properties:
data:
oneOf:
- $ref: '#/components/schemas/OrdersAddressData'
- $ref: '#/components/schemas/OrdersCancelData'
- $ref: '#/components/schemas/OrdersFulfilledData'
OrderItemResponse:
title: OrderItemResponse
type: object
properties:
type:
description: The type represents the object being returned.
type: string
examples:
- order_item
id:
description: The unique identifier for this order item.
type: string
format: uuid
readOnly: true
examples:
- 68bf8510-bebf-47b1-96ba-8a9930c7d928
quantity:
description: The quantity of this item were ordered.
type: number
examples:
- 1
product_id:
description: The unique identifier for this order item.
type: string
format: uuid
readOnly: true
examples:
- 4e9c6098-9701-4839-a69c-54d8256d9012
subscription_offering_id:
description: The unique identifier for the subscription offe
# --- truncated at 32 KB (66 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-orders-api-openapi.yml