Elastic Path Checkout API
The checkout workflow ties together many of the key concepts covered in this section. When a customer initiates the checkout process, an order is created from the cart. The order is incomplete until after a successful payment is made. A complete order can be shipped and the product deducted from inventory counts.  ### Summary of the checkout workflow 1. Add a product to a cart. A cart and its reference number is generated. 2. Manage the cart items. For example, you might add items, remove items, and change quantities. 3. Check out the cart. An incomplete order is created. 4. Pay for an order: provide billing and shipping details, if you are a new customer. The order is now in the processing status. 5. If using a manual gateway, after you authorize and capture it, Composable Commerce considers the order complete. If you use a third-party integration supported by Composable Commerce (such as Stripe), after the third-party gateway authorizes and captures the payment, the order becomes complete. Usually capture does not occur at the same time as authorization. For more information, see the Capture section. 6. After the order is shipped, you can manually flag it as fulfilled. ### Carts When a product is added to a cart, a cart is generated together with its unique reference ID that on checkout becomes a part of the order ID. If you are using our JavaScript software development kit, generating a cart reference ID is done for you; otherwise, add a cart reference generator to your functionality. ### Promotions and custom items Optionally, apply a promotion code on a cart, or add custom_items to modify the product price (typically to handle taxes, customs, or shipping). ### Checkout You can checkout a cart with an associated customer name and email (customer object). Typically, this would be used for new customers or ones that prefer to shop as guests. Use the `customer.id` checkout option to checkout for an existing customer. After a successful checkout is completed, the response contains an order. Email addresses that either begin or end with a period, or contain consecutive periods, are considered invalid, resulting in the following error: ```json "errors": [ { "status": 400, "source": "data.customer.email", "title": "format", "detail": "Does not match format 'email'" } ] ``` ### Payments On checkout, an incomplete order is created. You can then use a third-party integration to handle your payment gateway. If the payment gateway is supported by Composable Commerce, such as Stripe, the payment is processed externally but handled internally. When a successful validation is returned, Composable Commerce flags the order as complete. If you are using a payment method not officially supported by Composable Commerce, the gateway needs to be implemented and handled manually. After the payment has been authorized and captured either through Commerce Manager or API, the status of an order becomes complete. ### Shipping The status of an order and the status of shipping are handled separately, and so an order can be complete but not shipped. Orders that have not been shipped yet have a status of unfulfilled. This flag is generated automatically by Composable Commerce when an order is created. Currently, you can only update the shipping status manually, through the API. After the order is shipped, flag its shipping status as fulfilled. ### Inventory If enabled, you can manage your stock. As such, your stock is automatically updated as soon as a product is checked out.
POST
/v2/carts/{cartID}/checkout
Checkout API
#
Documentation
Specifications
Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Carts, , Orders Introduction Checkout 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: Checkout
description: "\nThe checkout workflow ties together many of the key concepts covered in this section. When a customer initiates the checkout process, an order is created from the cart. The order is incomplete until after a successful payment is made. A complete order can be shipped and the product deducted from inventory counts.\n\n\n\n### Summary of the checkout workflow\n\n1. Add a product to a cart. A cart and its reference number is generated.\n2. Manage the cart items. For example, you might add items, remove items, and change quantities.\n3. Check out the cart. An incomplete order is created.\n4. Pay for an order: provide billing and shipping details, if you are a new customer. The order is now in the processing status.\n5. If using a manual gateway, after you authorize and capture it, Composable Commerce considers the order complete. If you use a third-party integration supported by Composable Commerce (such as Stripe), after the third-party gateway authorizes and captures the payment, the order becomes complete. Usually capture does not occur at the same time as authorization. For more information, see the Capture section.\n6. After the order is shipped, you can manually flag it as fulfilled.\n\n### Carts\n\nWhen a product is added to a cart, a cart is generated together with its unique reference ID that on checkout becomes a part of the order ID. If you are using our JavaScript software development kit, generating a cart reference ID is done for you; otherwise, add a cart reference generator to your functionality.\n\n### Promotions and custom items\n\nOptionally, apply a promotion code on a cart, or add custom_items to modify the product price (typically to handle taxes, customs, or shipping).\n\n### Checkout\n\nYou can checkout a cart with an associated customer name and email (customer object). Typically, this would be used for new customers or ones that prefer to shop as guests. Use the `customer.id` checkout option to checkout for an existing customer. After a successful checkout is completed, the response contains an order.\n\nEmail addresses that either begin or end with a period, or contain consecutive periods, are considered invalid, resulting in the following error:\n```json\n\"errors\": [\n {\n \"status\": 400,\n \"source\": \"data.customer.email\",\n \"title\": \"format\",\n \"detail\": \"Does not match format 'email'\"\n }\n]\n ```\n\n### Payments\n\nOn checkout, an incomplete order is created. You can then use a third-party integration to handle your payment gateway. If the payment gateway is supported by Composable Commerce, such as Stripe, the payment is processed externally but handled internally. When a successful validation is returned, Composable Commerce flags the order as complete.\n\nIf you are using a payment method not officially supported by Composable Commerce, the gateway needs to be implemented and handled manually. After the payment has been authorized and captured either through Commerce Manager or API, the status of an order becomes complete.\n\n### Shipping\n\nThe status of an order and the status of shipping are handled separately, and so an order can be complete but not shipped. Orders that have not been shipped yet have a status of unfulfilled. This flag is generated automatically by Composable Commerce when an order is created. Currently, you can only update the shipping status manually, through the API. After the order is shipped, flag its shipping status as fulfilled.\n\n### Inventory\n\nIf enabled, you can manage your stock. As such, your stock is automatically updated as soon as a product is checked out.\n"
paths:
/v2/carts/{cartID}/checkout:
parameters: []
post:
tags:
- Checkout
summary: Checkout API
description: "When a Cart is ready for checkout, you can convert the cart to an order. The cart remains and can be modified and checked out again if required.\n\nA cart can be checked out with a customer ID, customer object, or with an account by authenticating with the `Client Credentials Token`.\n\nAfter a successful checkout, a response that contains the order is returned. If the cart is linked to a shipping group, the shipping group is also associated with the order after checkout.\n\nYou can checkout using one of the following methods:\n- **Customer ID**: You can checkout a cart with an existing customer ID.\n- **Guest Checkout** (Checkout with Customer Object): You can checkout a cart with an associated customer name and email.\n- **Checkout with Account**: The shopper authenticates with the `Client Credentials` Token.\n- **Checkout with Account Management Authentication Token**: The shopper authenticates with the `Implicit Token` and the `EP-Account-Management-Authentication-Token`.\n\n:::note\n\n- The cart currency is set when the first item is added to the cart.\n- The product being added to the cart requires a price in the same currency as the other items in the cart. The API returns a 400 error if a price is not defined in the correct currency.\n- To ensure that a free gift is automatically applied to an order, set the promotion to automatic. The checkout process will not be successful if free gift items are out of stock. See [Errors](#errors) section.\n\n:::\n\n:::caution\n\n- By default, carts are automatically deleted 7 days after the last update. You can change this setting by [updating cart settings](/docs/api/carts/put-v-2-settings-cart).\n- Your inventory is modified during checkout and payment of an order. For more information about the changes in the inventory, see the [Inventory](/docs/api/pxm/inventory/inventories-introduction) section.\n\n:::\n\n You can pass `order_number` and `external_ref` in the checkout endpoint or when [updating an order](/docs/api/carts/update-an-order). The `order_number` is an optional, user-managed field that is used as an alternative to `order_id`. When processing transactions through Authorize.net, the `order_number` is sent instead of the `order_id`, and it will appear in the invoice number section. If no `order_number` is provided, the `order_id` is sent to Authorize.net on payment by default. There are no duplication restrictions on the `order_number` value.\n\n### Next Steps\n\nAfter a cart has been converted to an Order using either of the previous methods, you most likely want to capture payment for order. See [Paying for an Order](/docs/api/carts/payments).\n\n### Errors\n\nThe following error response is returned during checkout when an eligible item is added to the cart, and the free gift is out of stock.\n\n```json\n{\n \"errors\": [\n {\n \"status\": 400,\n \"title\": \"Insufficient stock\",\n \"detail\": \"There is not enough stock to add gift2 to your cart\",\n \"meta\": {\n \"id\": \"f2b68648-9621-45a3-aed6-1b526b0f5beb\",\n \"sku\": \"gift2\"\n }\n }\n ]\n}\n```\n"
operationId: checkoutAPI
parameters:
- name: cartID
in: path
description: The ID of the cart that you want to checkout.
required: true
style: simple
schema:
type: string
- name: EP-Account-Management-Authentication-Token
in: header
description: An account management authentication token that identifies the authenticated account member.
style: simple
schema:
type: string
examples:
- '{{accountToken}}'
requestBody:
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CustomerCheckout'
- $ref: '#/components/schemas/AccountCheckout'
examples:
CheckoutWithCustomerID:
summary: Checkout with Customer ID
value:
data:
order_number: order-1234
external_ref: e-123456789
customer:
id: c8c1c511-beef-4812-9b7a-9f92c587217c
billing_address:
first_name: John
last_name: Doe
company_name: Moltin
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
shipping_address:
first_name: John
last_name: Doe
phone_number: (555) 555-1234
company_name: Moltin
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
instructions: Leave in porch
CheckoutWithCustomerObject:
summary: Guest Checkout (Checkout with Customer Object)
value:
data:
order_number: order-1234
external_ref: e-123456789
customer:
email: john@moltin.com
name: John Doe
billing_address:
first_name: John
last_name: Doe
company_name: Moltin
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
shipping_address:
first_name: John
last_name: Doe
phone_number: (555) 555-1234
company_name: Moltin
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
instructions: Leave in porch
CreateCheckoutWithAccount:
summary: Create Checkout with Account
value:
data:
order_number: order-1234
external_ref: e-123456789
account:
id: 8cee1b9e-3e39-4d5f-bd4a-86cdb985c6ee
member_id: 338f84bf-e6c9-4704-9f33-2708addd462b
contact:
email: john@email.com
name: John Doe
billing_address:
first_name: John
last_name: Doe
company_name: ElasticPath
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
shipping_address:
first_name: John
last_name: Doe
company_name: ElasticPath
phone_number: (555) 555-1234
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
instructions: Leave in porch
CreateCheckoutWithAccountManagementAuthenticationToken:
summary: Create Checkout with Account Management Authentication Token
value:
data:
order_number: order-1234
external_ref: e-123456789
contact:
email: john@email.com
name: John Doe
billing_address:
first_name: John
last_name: Doe
company_name: ElasticPath
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
shipping_address:
first_name: John
last_name: Doe
company_name: ElasticPath
phone_number: (555) 555-1234
line_1: 1234 Disney Drive
line_2: Disney Resort
city: Anaheim
county: Orange
region: CA
postcode: '92802'
country: US
instructions: Leave in porch
required: false
responses:
'201':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/OrderEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
deprecated: false
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
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
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
RelationshipArray:
title: RelationshipArray
description: Array of relationships
type: object
properties:
data:
description: Individual relationships
type: array
items:
$ref: '#/components/schemas/RelationshipItem'
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
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
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 offering for this order item.
type: string
format: uuid
readOnly: true
examples:
- 69a39623-e681-415e-83c0-e1281010c77d
name:
description: The name of this order item.
type: string
examples:
- Product 123
sku:
description: The SKU code for the order item.
type: string
examples:
- IFD-1
location:
description: The stock location for this order item.
type: string
readOnly: true
unit_price:
$ref: '#/components/schemas/OrderPriceData'
value:
$ref: '#/components/schemas/OrderPriceData'
discounts:
type: array
items:
$ref: '#/components/schemas/DiscountData'
links:
type: object
meta:
type: object
properties:
display_price:
type: object
properties:
with_tax:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
without_tax:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
tax:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
discount:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
without_discount:
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
discounts:
type: object
additionalProperties:
type: object
properties:
amount:
type: number
examples:
- -1000
currency:
type: string
examples:
- USD
formatted:
type: string
examples:
- -$1.00
constituents:
type: object
description: Detailed breakdown of discount constituents by ID
additionalProperties:
type: object
properties:
amount:
type: number
description: The discount amount
currency:
type: string
description: The currency code
formatted:
type: string
description: The formatted discount amount
original_price:
description: The product's original catalog price before any catalog-level sales, tiered pricing adjustments, or cart/item level promotions are applied. This value is sourced from the product's `meta.original_display_price` field in the catalog response. See [Get a Product](/docs/api/pxm/catalog/get-by-context-product).
$ref: '#/components/schemas/OrderItemFormattedUnitPriceData'
timestamps:
$ref: '#/components/schemas/Timestamps'
relationships:
type: object
properties:
cart_item:
type: object
properties:
data:
type: object
properties:
type:
description: The type represents the object being returned.
type: string
examples:
- order_item
id:
description: The unique identifier for this item.
type: string
format: uuid
readOnly: true
examples:
- 5601a4b1-9d13-42d3-8fb7-03b35169d1b6
taxes:
description: Related tax items.
type: object
properties:
data:
oneOf:
- type: 'null'
- type: array
items:
$ref: '#/components/schemas/RelationshipItem'
promotions:
description: Related promotions.
type: object
properties:
data:
oneOf:
- type: 'null'
- type: array
items:
$ref: '#/components/schemas/RelationshipItem'
catalog_id:
description: The unique identifier of the catalog associated with the product is shown if `catalog_source=pim` is set.
type: string
examples:
- default
catalog_source:
description: The catalog source. Always `pim` or `legacy`.
type: string
examples:
- pim
- legacy
bundle_configuration:
description: Configuration for bundle produ
# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-checkout-api-openapi.yml