Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Carts, Checkout, Orders Introduction Cart Management 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: Cart Management
description: 'A Cart contains the product and custom cart items that a user intends to purchase. After a Cart is ready for Checkout, you can use the [Checkout endpoint](/docs/api/carts/checkout) to convert the cart to an order.
:::note
- Adding, modifying, or removing any cart items, custom items, or promotions always returns the cart meta, calculated using the calculation method. This is useful to update the client with up-to-date totals.
- We will automatically delete carts 7 days after they were last updated.
- If you do not pass a `X-MOLTIN-CURRENCY` header specifying what currency you would like the cart to use, the products in the cart are converted to your default currency.
:::
'
paths:
/v2/carts:
parameters: []
get:
tags:
- Cart Management
summary: Get Carts
description: 'Retrieves a list of carts. The carts returned depend on the authentication method used:
| Authentication Method | Header | Returns |
| :--- | :--- | :--- |
| **Customer Token** | `X-Moltin-Customer-Token` | Carts for the specified customer. See [Customer Tokens](/docs/customer-management/customer-management-api/customer-tokens). |
| **Account Token** | `EP-Account-Management-Authentication-Token` | Carts for the specified account. See [Account Management Token](/docs/api/accounts/post-v-2-account-members-tokens). |
| **Client Credentials** | `Authorization: Bearer <token>` | All carts or only registered carts, controlled by the `show_all_carts` setting. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart). |
**Client Credentials Behavior:**
- When `show_all_carts` is `true`: Returns all carts in the store.
- When `show_all_carts` is `false`: Returns only registered carts (associated with customers or accounts).
**Sorting**
Carts are sorted in descending order by `updated_date`. For more information, see [Pagination](/guides/Getting-Started/pagination).
'
operationId: getCarts
parameters:
- name: EP-Account-Management-Authentication-Token
in: header
description: An Account Management Authentication token to access a specific account's carts.
style: simple
schema:
type: string
examples:
- '{{accountToken}}'
- name: X-Moltin-Customer-Token
in: header
description: A customer token to access a specific customer's carts.
style: simple
schema:
type: string
examples:
- '{{customerToken}}'
- name: include
in: query
required: false
style: form
explode: false
schema:
type: array
description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).
example:
- custom_discounts
items:
type: string
const: 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 carts. For more information about filtering, see [Filtering](/guides/Getting-Started/filtering).
**Supported Fields:**
- `account_ids`: Filter carts by associated account ID (UUID format)
- `name`: Filter carts by cart name (case-insensitive)
**Supported Operators:**
- `contains(field,value)`: Contains value in array field
- `ilike(field,value)`: Case-insensitive string matching
**Examples:**
- `contains(account_ids,"c24e5698-3b54-491b-9225-559c7a9cf2b2")` - Find carts associated with a specific account
- `ilike(name,"Shopping Cart")` - Find carts with name matching "Shopping Cart" (case-insensitive)
- `ilike(name,"*cart*")` - Find carts with names containing "cart" (wildcard search)
**Combining Filters:**
You can combine multiple filters using the `:`, and `|` operator for and and or respectively:
- `contains(account_ids,"abc123"):ilike(name,"Holiday Cart")` - Find carts matching both conditions
- `contains(account_ids,"abc123")|ilike(name,"Holiday Cart")` - Find carts matching either condition.
'
required: false
style: form
explode: false
schema:
type: string
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/CartCollectionResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
'403':
description: Unauthorized call
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
deprecated: false
post:
tags:
- Cart Management
summary: Create a Cart
description: "\nCreates a cart. Call this endpoint each time a customer creates a cart.\n\nEach shopper can have multiple carts. Use the carts API to create a cart. The carts are distinct from one another. Shoppers can add different items to their carts. They can check out one of the carts without affecting the content or status of their other carts.\n\nAfter the shopper checks out the cart, the cart remains available to the shopper. The cart is persistent and stays with the shopper after it is used.\n\nYou can create a cart to specify custom discounts. You can enable custom discounts when the `discount_settings.custom_discounts_enabled` field is set to `true`. Default is set from cart discount settings for the store. See [Update Cart Settings](/docs/api/carts/put-v-2-settings-cart).\n\nYou can also create a cart when inventory checks are not performed until checkout by setting the `inventory_settings.defer_inventory_check` field to `true`. Again the default is set from cart discount settings for the store. See [Update Cart Settings](/docs/api/carts/put-v-2-settings-cart).\n\n### Preview Cart\n\nYou can 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.\n\n:::caution\n- Once the cart is in preview mode, you cannot revert it to a regular cart.\n- Carts with `snapshot_date` are same as preview carts.\n- You cannot checkout a cart that includes a `snapshot_date`.\n- To delete a promotion preview cart, use [Delete a cart](/docs/api/carts/delete-a-cart) endpoint.\n- The promotion preview cart has the same expiration time as a regular cart based on the store's [cart settings](/docs/api/carts/put-v-2-settings-cart).\n- Preview cart interactions skip inventory checks and events, allowing users to preview future carts without impacting related external systems.\n:::\n\n### Custom Attributes\nYou can create custom attributes for the cart object to include additional information, enabling promotions that target specific cart attributes.\nFor example:\n```\n\"custom_attributes\":{\n \"membership\": {\n \"type\": \"string\",\n \"value\": \"VIP\"\n }\n}\n```\nSee [adding cart custom attributes in promotions builder](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#adding-cart-custom-attributes)\n\nCart custom attributes remain with the corresponding cart for the extent of its lifecycle. These custom attributes carry over to the resulting order objects on checkout and those on carts are deleted with their carts upon cart deletions.\nCustom attributes can be updated or removed using a PUT request. To delete specific custom attributes, simply exclude the unwanted attribute objects from the PUT request body.\n\n### Contact Email\nYou can attach an email to carts via the `contact.email` field. These values help identify guest shopper carts and, in the case of promotions with maximum usage settings for guest and registered shopper, track per-shopper promotion usages.\nSee [Create Max Uses Per Shopper Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-max-use-limit-promotion-codes)\n\nFor example:\n```\n\"contact\": {\n \"email\": \"tester@email.com\"\n}\n```\n\nPlease note, this value is not supported for registered shopper carts (that is, carts with accounts or customers associated), as these carts already have email values associated via the shopper details. Accordingly, requests to add contact email information to registered shopper carts (and vice versa) result in error messages.\n\n### Errors\n\n- `400 Bad Request` : This is returned when the submitted request does not adhere to the expected API contract for the endpoint.\n\n - For example, in the case of string fields, this error might indicate issues in the length or format of submitted strings. For more information about valid string fields, refer to Safe Characters section.\n - In the case of preview carts (those with `snapshot_date`), an error is returned for invalid actions, such as removing the preview date, setting a preview date in the past, or attempting to checkout a cart with a `snapshot_date`.\n"
operationId: createACart
parameters:
- name: EP-Account-Management-Authentication-Token
in: header
description: An Account Management Authentication token for the account to be associated with the cart.
style: simple
required: false
schema:
type: string
examples:
- '{{accountToken}}'
- name: X-Moltin-Customer-Token
in: header
description: A customer token for the customer to be associated with the cart.
style: simple
required: false
schema:
type: string
examples:
- '{{customerToken}}'
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CartsRequest'
examples:
Create Cart:
value:
data:
name: Bob's cart
description: For Holidays
discount_settings:
custom_discounts_enabled: true
Create Preview Cart:
value:
data:
name: promotion preview cart
description: preview promotions
snapshot_date: '2026-09-10T00:12:00Z'
Create a Cart with Custom Attributes:
value:
data:
name: cart with custom attributes
description: cart description
custom_attributes:
affiliate_link:
type: string
value: https://site.com?tag=influencer04-20
Create a Cart with Contact Email:
value:
data:
name: cart with contact email
description: cart description
contact:
email: tester@email.com
Create a Cart with Deferred Inventory Check:
value:
data:
name: cart with deferred inventory check
description: cart description
inventory_settings:
defer_inventory_check: true
responses:
'201':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/CartEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
'403':
description: Unauthorized call
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
deprecated: false
/v2/carts/{cartID}:
parameters: []
get:
tags:
- Cart Management
summary: Get a Cart
description: 'Use this endpoint to retrieve a specific cart. If a cart ID does not exist, a new cart will be automatically created. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs in the `relationships` section.
You can easily get a new or existing cart by providing the unique cart reference in the request. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs in the relationships section.
:::note
- The default cart name is Cart. However, you can update the cart name as required. Ensure that the string length of the name is greater than or equal to one. Follow the safe character guidelines for name and description naming. For more information about cart ID naming requirements, see the [Safe Characters](/guides/Getting-Started/safe-characters) section.
- Outside of the JS-SDK, we don''t handle creating cart references. You need to create your own.
:::
:::caution
An empty cart is returned for any carts that don''t currently exist. For more information about the cart items object, see [Get Cart Items](/docs/api/carts/get-cart-items).
:::
### Query parameters
| Name | Required | 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: getACart
parameters:
- name: cartID
in: path
description: The unique identifier for this cart that you created.
required: true
style: simple
schema:
type: string
- name: include
in: query
required: false
style: form
explode: false
schema:
type: array
description: A comma-separated list of resources to include. See [Characteristics of Include Parameter](/guides/Getting-Started/includes#characteristics-of-include-parameter).
example: custom_discounts
items:
type: string
enum:
- custom_discounts
- promotions
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/CartEntityResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
deprecated: false
put:
tags:
- Cart Management
summary: Update a Cart
description: 'Updates cart properties for the specified cartID.
You can update a cart to specify custom discounts. You can enable custom discounts when the `discount_settings.custom_discounts_enabled` field is set to `true`. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart).
You can also create a cart when inventory checks are not performed until checkout by setting the `inventory_settings.defer_inventory_check` field to `true`. Again the default is set from cart discount settings for the store. See [Update Cart Settings](/docs/api/carts/put-v-2-settings-cart).
'
operationId: updateACart
parameters:
- name: cartID
in: path
description: The unique identifier of a cart created by you.
required: true
style: simple
schema:
type: string
requestBody:
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CartsRequest'
examples:
Update a Cart:
value:
data:
name: my cart
description: my first cart
discount_settings:
custom_discounts_enabled: false
use_rule_promotions: true
snapshot_date: '2026-09-10T00:12:00Z'
Remove Payment Intent from a Cart:
value:
data:
payment_intent_id: ''
Update Cart with Custom Attributes:
value:
data:
name: cart with custom attribute
description: cart description
custom_attributes:
affiliate_link:
type: string
value: https://site.com?tag=influencer04-21
Update Cart with Contact Email:
value:
data:
name: cart with contact email
description: cart description
contact:
email: tester@email.com
required: false
responses:
'200':
description: ''
headers: {}
content:
application/json:
schema:
$ref: '#/components/schemas/CartEntityResponse'
'403':
description: Unauthorized call
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
'422':
description: Unprocessable Content
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorItem'
deprecated: false
delete:
tags:
- Cart Management
summary: Delete a Cart
description: "You can delete a cart, including the items, name, description, and remove all associations.\n\n### Errors\n\nThe following error message is received when you attempt to delete a cart that is associated with a customer. Before deletion, ensure that the cart is disassociated.\n\n```json\nmessage: {\n errors: [\n {\n status: 400,\n title: 'Last cart',\n detail: 'This is the last cart associated with a customer and it cannot be deleted, try disassociating instead'\n }\n ]\n }\n````\n"
operationId: deleteACart
parameters:
- name: cartID
in: path
description: The unique identifier of the cart that you want to delete.
required: true
style: simple
schema:
type: string
responses:
'204':
description: No Content
headers: {}
content: {}
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/Response.ErrorResponse'
deprecated: false
components:
schemas:
BaseCartResponse:
title: BaseCartResponse
type: object
properties:
id:
description: The unique identifier for the cart. Use SDK or create it yourself.
type: string
name:
description: The name of this cart.
type: string
examples:
- cart name
description:
description: A description of the cart.
type: string
examples:
- cart description
contact:
$ref: '#/components/schemas/CartContact'
discount_settings:
$ref: '#/components/schemas/DiscountSettings'
inventory_settings:
$ref: '#/components/schemas/InventorySettings'
item_settings:
$ref: '#/components/schemas/ItemSettings'
payment_intent_id:
description: Stripe-assigned unique identifier for the linked Payment Intent
type: string
custom_attributes:
$ref: '#/components/schemas/CustomAttributes'
snapshot_date:
description: The snapshot date for the cart.
type: string
format: date-time
links:
type: object
properties:
self:
description: A link to that specific resource.
type: string
examples:
- https://useast.api.elasticpath.com/v2/carts/1
meta:
type: object
properties:
display_price:
type: object
properties:
with_tax:
$ref: '#/components/schemas/FormattedPriceData'
without_tax:
$ref: '#/components/schemas/FormattedPriceData'
tax:
$ref: '#/components/schemas/FormattedPriceData'
discount:
$ref: '#/components/schemas/FormattedPriceData'
without_discount:
$ref: '#/components/schemas/FormattedPriceData'
shipping:
$ref: '#/components/schemas/FormattedPriceData'
shipping_discount:
$ref: '#/components/schemas/FormattedPriceData'
timestamps:
$ref: '#/components/schemas/CartTimestamps'
promotion_suggestions:
description: Array of promotion suggestions
type: array
items:
type: object
properties:
bundle:
description: Bundle configuration with promotion targets
type: array
items:
type: object
properties:
auto_add_free_gift:
description: Whether to automatically add free gift
type: boolean
cart_item_id:
description: Cart item ID for the target
type: string
quantity:
description: Quantity for the promotion
type: integer
targets:
description: Array of target SKUs
type: array
items:
type: string
additionalProperties: true
code:
type: string
info:
type: string
message:
type: string
promotion_id:
type: string
relationships:
type: object
properties:
customers:
anyOf:
- $ref: '#/components/schemas/RelationshipArray'
- type: object
maxProperties: 0
items:
anyOf:
- $ref: '#/components/schemas/RelationshipArray'
- type: object
properties:
data:
oneOf:
- type: 'null'
- type: array
items:
type: object
properties:
id:
type: string
type:
type: string
required:
- data
accounts:
anyOf:
- $ref: '#/components/schemas/RelationshipArray'
- type: object
maxProperties: 0
custom_discounts:
$ref: '#/components/schemas/RelationshipArray'
promotions:
$ref: '#/components/schemas/RelationshipArray'
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
RelationshipArray:
title: RelationshipArray
description: Array of relationships
type: object
properties:
data:
description: Individual relationships
type: array
items:
$ref: '#/components/schemas/RelationshipItem'
Response.PaginationResults:
type: object
properties:
total:
description: The total page count.
type: integer
CartsRequest:
title: CartsRequest
type: object
properties:
data:
type: object
properties:
description:
type: string
description: The cart description.
examples:
- cart description
discount_settings:
$ref: '#/components/schemas/DiscountSettings'
inventory_settings:
$ref: '#/components/schemas/InventorySettings'
item_settings:
$ref: '#/components/schemas/ItemSettings'
name:
description: The cart name provided by the shopper. A cart name must contain 1 to 255 characters. You cannot use whitespace characters, but special characters are permitted. For more information, see the [Safe Characters](/guides/Getting-Started/safe-characters) section.
type: string
examples:
- my cart name
contact:
$ref: '#/components/schemas/CartContact'
snapshot_date:
description: This optional parameter sets a reference date for the cart. If this parameter is set, it allows the cart to act as one that might occur on that specified date. For example, such future carts might acquire future-enabled discounts, allowing users to test and validate future interactions with carts. The snapshot_date must be in the format 2026-02-21T15:07:25Z. By default, this parameter is left empty.
type: string
examples:
- '2026-09-10T00:12:00Z'
custom_attributes:
description: "Specifies custom attributes for cart 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\nAttribute types include:\n - string\n - boolean\n - integer\n - float\n\nMultiple custom attributes may be submitted together. A cart can have a maximum of 20 custom attributes.\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\nUpdating an existing cart with new custom attributes clears previously-saved attributes. In order to maintain existing custom attributes on a cart, please include them in the update request along with any new attributes.\n"
$ref: '#/components/schemas/CustomAttributes'
payment_intent_id:
description: To remove the Stripe payment intent from a cart, pass the empty value in the `payment_intent_id` field. You must use an empty value for this field. You cannot use this endpoint to directly update the cart to use an existing Payment Intent.
type: string
examples:
- ''
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:
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-cart-management-api-openapi.yml