openapi: 3.1.0
info:
version: 25.1126.6886238
x-version-timestamp: 2025-11-26 19:10:23+00:00
title: Addresses Introduction Account Addresses Cart Management API
description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour.
You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token.
'
contact:
name: Elastic Path
url: https://www.elasticpath.com
email: support@elasticpath.com
license:
url: https://elasticpath.dev
name: MIT
servers:
- url: https://useast.api.elasticpath.com
description: US East
- url: https://euwest.api.elasticpath.com
description: EU West
security:
- BearerToken: []
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:
CartCollectionResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/CartResponse'
links:
$ref: '#/components/schemas/Response.PageLinks'
meta:
$ref: '#/components/schemas/Response.Meta.Carts'
required:
- data
CustomDiscountResponse:
title: CustomDiscountResponse
type: object
properties:
type:
description: Specifies the type of the resource. Always `custom_discount`.
type: string
const: custom_discount
id:
description: Specifies the UUID of the custom discount.
type: string
format: uuid
examples:
- 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9
external_id:
description: Specifies an external id for the custom discount.
type: string
examples:
- custom-discount-external-id
discount_engine:
description: 'Specifies from where the custom discount is applied.
'
type: string
examples:
- Custom Discount Engine
amount:
description: The amount of the custom discount.
$ref: '#/components/schemas/FormattedPriceData'
description:
description: Specifies a description for the custom discount.
type: string
examples:
- Custom discount description
discount_code:
description: Specifies the discount code used for the custom discount.
type: string
examples:
- cart-custom-promo-code
relationships:
description: Relationships to other resources like cart items
type: object
properties:
item:
type: object
properties:
data:
type: object
properties:
id:
type: string
format: uuid
description: The cart item ID this discount is related to
type:
type: string
enum:
- cart_item
- custom_item
CartResponse:
title: CartResponse
allOf:
- $ref: '#/components/schemas/BaseCartResponse'
- type: object
properties:
type:
description: The type of object being returned.
type: string
const: cart
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:
- ''
FormattedPriceData:
title: FormattedPriceData
type: object
properties:
amount:
description: The raw total.
type: number
examples:
- 10000
currency:
description: The currency set for this amount.
type: string
examples:
- USD
formatted:
description: The formatted total based on the amount and currency.
type: string
examples:
- $10.00
Response.ErrorItem:
type: object
required:
- status
- title
properties:
title:
type: string
description: A brief summary of the error.
examples:
- Bad Request
status:
type:
- string
- integer
description: The HTTP response code of the error.
examples:
- '400'
detail:
type: string
description: Optional additional detail about the error.
examples:
- The field 'name' is required
source:
type: string
description: The field or location that caused the validation error. For JSON schema validation errors, this contains the JSON path to the invalid field (e.g., 'data.name', 'request', 'data.items[0].quantity').
meta:
type: object
description: Additional metadata associated with the error. May include arbitrary keys.
properties:
id:
type: string
description: The resource id associated with the error
ids:
type: array
items:
type: string
description: The resource ids associated with the error
item_ids:
type: array
items:
type: string
description: The cart_item ids associated with the error
shipping_group_id:
type: string
description: The shipping group id associated with the error
shipping_group_ids:
type: array
items:
type: string
description: The shipping group ids associated with the error
cart_id:
type: string
description: The cart id associated with the error
code:
type: string
description: The code associated with the error.
order_id:
type: string
description: The order id associated with the error.
sku:
type: string
description: The SKU associated with the error.
email:
type: string
format: email
description: The email address associated with the error.
component_product_id:
type: string
format: uuid
description: The component product ID associated with the error.
error-meta-key:
type: string
description: Custom error metadata key used for additional error context (e.g., in payment rejections).
value:
description: The value associated with the error.
oneOf:
- type: string
- type: integer
- type: boolean
- type: object
additionalProperties: true
- type: array
CondensedPromotionResponse:
title: CondensedPromotionResponse
type: object
properties:
type:
description: Specifies the type of the resource. Always `promotion`.
type: string
const: promotion
examples:
- promotion
id:
description: Specifies the UUID of the promotion.
type: string
format: uuid
readOnly: true
examples:
- 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9
name:
description: The name of the promotion.
type: string
examples:
- Summer Sale
description:
description: The description of the promotion.
type: string
examples:
- Get 20% off all summer items
automatic:
description: Whether the promotion is applied automatically.
type: boolean
examples:
- true
promotion_type:
description: The type of promotion (for v1 promotions).
type: string
examples:
- discount
promotion_source:
description: The source of the promotion (for rule promotions).
type: string
examples:
- rule-promotion
start:
description: The start date and time of the promotion.
type: string
format: date-time
examples:
- '2024-06-01T00:00:00Z'
end:
description: The end date and time of the promotion.
type: string
format: date-time
examples:
- '2024-08-31T23:59:59Z'
CartContact:
title: CartContact
type: object
properties:
email:
description: The email address attached to a cart.
type: string
format: email
examples:
- tester@email.com
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
# --- truncated at 32 KB (41 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elastic-path/refs/heads/main/openapi/elastic-path-cart-management-api-openapi.yml