openapi: 3.1.0 info: title: Carts, Checkout, Orders Introduction 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: ![Shows a cart workflow, starting from adding the first item to a cart, through cart creation and checkout](/assets/cart-workflow.png) ### 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-13T21:22:42Z 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. ::: - name: Account Cart Associations description: | You can create associations between an account and one or more carts. After cart associations exist for an account, those carts are accessible across any device. You can delete associations as required. There are two ways to access the cart: with an [Account Management Authentication Tokens](/docs/api/accounts/post-v-2-account-members-tokens) and without one. ### With an `Account Management Authentication` token These endpoints are for users who authenticated implicitly and require an Account Management Authentication token in the header to access the account cart associations APIs. For more information, see the [Account Token](/docs/api/accounts/post-v-2-account-members-tokens) documentation. #### Cart creation Shoppers create carts and can use any of the carts that they created to check out an order. :::note You can create a cart id, name, and description for the cart. The cart requires a name. Ensure that the string length is greater than or equal to one. Use any symbol in the name and description. For cart id, ensure that you follow the guidelines for safe characters. For more information about cart id naming requirements, see [Safe Characters](/guides/Getting-Started/safe-characters). ::: ### Without an `Account Management Authentication` token These endpoints are for users who use the Client Credentials Token and do not require an account management authentication token in the header to access the account cart associations APIs. For more information, see the [Authentication](/docs/authentication/security) documentation. This user acts as a system administrator and can call any account cart association operations for any account and cart. ### Error Codes You might encounter the following response codes, depending on the scenario: * `400` - `The type does not exist or is not listed as account` - Ensure that the type is `account` and is present. * `403` - `Cannot associate more than one account`. * `403` - `Account does not have the required permissions to fulfill this request`. * `403` - `Invalid json payload` - Check JSON input. The request body must be an array `[]`. If the request body is an object, the error is generated. - name: Customer Cart Associations description: | You can create associations between a customer and one or more carts. After cart associations exist for a customer, those carts are accessible across any device. You can delete associations as required. There are two ways to access the cart: with a customer token and without one. ### With a `customer` token These endpoints are for users who authenticated implicitly and require a customer token in the header to access the customer cart associations APIs. For more information, see the [Customer Token](/docs/customer-management/customer-management-api/customer-tokens) documentation. #### Cart creation Shoppers create carts and can use any of the carts that they created to check out an order. :::note You can create a cart id, name, and description for the cart. The cart requires a name. Ensure that the string length is greater than or equal to one. Use any symbol in the name and description. For cart id, ensure that you follow the guidelines for safe characters. For more information about cart id naming requirements, see [Safe Characters](/guides/Getting-Started/safe-characters). ::: ### Without a `customer` token These endpoints are for users who use the Client Credentials Token and do not require a Customer token in the header to access the customer cart associations APIs. For more information, see the [Authentication](/docs/authentication/security) documentation. This user acts as a system administrator and can call any customer cart association operations for any customer and cart. ### Error Codes You might encounter the following response codes, depending on the scenario: * `400` - `The type does not exist or is not listed as customer` - Ensure that the type is `customer` and is present. * `403` - `Cannot associate more than one customer`. * `403` - `Customer does not have the required permissions to fulfill this request`. * `403` - `Invalid json payload` - Check JSON input. The request body must be an array `[]`. If the request body is an object, the error is generated. - name: Cart Items description: Products added to a cart are referred to as a `cart_item`. - name: Checkout description: | 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. ![Checkout workflow](/assets/checkout-flow.png) ### 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. - 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). - name: Payments description: | When you [checkout](/docs/api/carts/checkout) a [cart](/docs/api/carts/cart-management), an unpaid [order](/docs/api/carts/orders) is returned. You can process the payment for the order though a payment gateway. :::note - You need to configure and enable a payment gateway before you can accept payments for orders. - Configure your store to use [Manual Gateway](/docs/api/payments/update-manual-gateway) to process payments if the order total is zero or the payment is through non-supported payment providers. - There are a number of actions that happen to your inventory when checking out and paying for an order. For more information, see [Inventory](/docs/api/pxm/inventory/inventories-introduction). - We recommend to wait until the payment confirmation process is fully completed before proceeding with any additional updates to the order. Making simultaneous updates to the same entity immediately after payment confirmation can lead to a race condition. To learn more information on handling parallel calls to API objects, see [Parallel Calls to API Objects](/guides/Getting-Started/api-contract#parallel-calls-to-api-objects). ::: ### Payment Methods Depending on the chosen gateway, you may or may not have access to capture funds immediately or authorize for later payment. To make a partial payment in Postman through any payment gateway, specify the desired payment amount in the amount field within the request body. To learn about Split Payments, see the [Split Payments](/docs/api/payments/payment-gateways-introduction#split-payments) section. #### Purchase The simplest method is purchase. The gateway attempts to charge the customer immediately, and the result of the attempt is returned. You can partially pay funds using purchase method. The gateway attempts to charge the customer immediately, and the payment status for an order shows `partially_paid`. When you Get an order, you can see the following fields in the `meta` object: - `balance_owing`: Specifies the outstanding funds required to complete an order. It considers all complete or pending transactions, including authorized, paid, and captured transactions. (`balance_owing` = order total - `authorized` amount - `paid` amount). - `paid`: Specifies the total amount of purchased or captured transactions. - `authorized`: Specifies the total amount of completed or pending authorized transactions for an order. #### Authorize You can `authorize` a payment so funds can later be captured when an item is dispatched or restocked. You can partially pay for an order using `authorize` payment method so that the order is `partially_authorized`. The transaction must be complete for the order status to be `partially_authorized`. For more information about order and payment statuses for split payments, see [Split Payments](/docs/api/payments/payment-gateways-introduction#split-payments). #### Capture After authorizing a transaction, you have to capture the authorized funds. :::note We recommend capturing payments several hours to days after the authorization to mitigate risks of fraud and chargebacks. When you sell digital goods that are delivered immediately, we recommend using a single purchase call instead of separate authorize and capture calls. ::: After the payment is `partially_authorized`, you must `capture` the authorized transaction later. Once you capture the authorized transactions, the order payment status will change to `partially_paid`. #### Refunds You can use either the Refund through Composable Commerce or use the Mark as Refunded capability, or a combination of both capabilities. For more information about refund for split payments, see [Refund a Payment](/docs/api/carts/refund-a-transaction). #### Refund through Composable Commerce You can start a full or partial refund to a supported payment provider directly from Commerce Manager or the API. When you start the refund process, the refund request is sent to the payment gateway. You no longer have to log on to your payment gateway's console to process the refund. When you process a refund, use the refund endpoint to pass the refund amount. If you don't pass an amount, the refund is processed as Mark as refunded. For more information, see the Mark as Refunded section. Each time a partial refund is triggered, the transaction.updated event is generated and updated with refunded.amount. The `order.updated` event is also triggered. The `order.refunded` event generates when the full amount is refunded. #### Mark as Refunded You can use your payment gateway's console to process a refund. Process the refund first in the payment gateway and then use the **Mark as Refunded** capability in Composable Commerce to complete the process. When an order is **Marked as refunded**, the payment status `order.payment.status` is set to `refunded`. In this case, the `order.updated`, `transaction.updated` and `order.refunded` events are generated. - name: Custom Discounts description: | With custom discounts, you can allow your shoppers to apply discounts from external services to their purchases. To apply custom discounts to carts and cart items, you need to set `custom_discounts_enabled` field to `true` in your [Cart Settings](/docs/api/carts/put-v-2-settings-cart). You cannot add custom discounts to an empty cart. :::caution - You can apply up to five custom discounts to cart and cart item. - The stores that use [simple calculation method](/guides/How-To/Carts/calculate-totals) do not support custom discounts. ::: - name: Cart Settings description: | Use Cart Settings to configure cart behavior for your store, including cart expiry, custom discounts, rule promotions, deferred inventory checks, and cart visibility for admins. - name: Tax Items description: | Taxes differ by country and can differ within the country by region, state, or province. Each jurisdiction has a unique tax code and rate. If your store serves many jurisdictions, integrate a third-party tax generator to manage taxes. If your store serves a few jurisdictions, you can use the API to define the tax codes and rates in Composable Commerce. Taxes are calculated after all promotional discounts have been applied. When calculating taxes on a cart or order, you can choose from the following methods for calculating taxes: - Simple calculation method: Taxes are calculated at the unit level and are rounded to the nearest penny for the unit. - Line calculation method: Default. Taxes are calculated at the line level and are rounded to the nearest penny for the line. For more information about calculation methods, see [Calculate cart and order totals](/guides/How-To/Carts/calculate-totals). Tax values can be either `rate` or `amount`. - `rate` - Represents the tax as a percentage in decimal form. - `amount` - Represents a tax amount. :::note Tax items can be added and removed using [client_credentials access tokens](/docs/api/authentication/create-an-access-token). Only administrators with `client-credentials` access tokens are able to manage tax items. ::: paths: /v2/carts: 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 ` | 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: | Creates a cart. Call this endpoint each time a customer creates a cart. Each 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. After 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. You 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). 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). ### Preview Cart You 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. :::caution - Once the cart is in preview mode, you cannot revert it to a regular cart. - Carts with `snapshot_date` are same as preview carts. - You cannot checkout a cart that includes a `snapshot_date`. - To delete a promotion preview cart, use [Delete a cart](/docs/api/carts/delete-a-cart) endpoint. - 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). - Preview cart interactions skip inventory checks and events, allowing users to preview future carts without impacting related external systems. ::: ### Custom Attributes You can create custom attributes for the cart object to include additional information, enabling promotions that target specific cart attributes. For example: ``` "custom_attributes":{ "membership": { "type": "string", "value": "VIP" } } ``` See [adding cart custom attributes in promotions builder](/docs/commerce-manager/promotions-builder/creating-a-promotion-in-promotions-builder#adding-cart-custom-attributes) Cart 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. Custom 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. ### Contact Email You 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. See [Create Max Uses Per Shopper Promotion Codes](/docs/promotions-builder/promotions-builder-codes/create-max-use-limit-promotion-codes) For example: ``` "contact": { "email": "tester@email.com" } ``` Please 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. ### Errors - `400 Bad Request` : This is returned when the submitted request does not adhere to the expected API contract for the endpoint. - 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. - 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`. 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 parameters: [] /v2/carts/{cartID}: 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. ### Errors The 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. ```json message: { errors: [ { status: 400, title: 'Last cart', detail: 'This is the last cart associated with a customer and it cannot be deleted, try disassociating instead' } ] } ```` 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 parameters: [] /v2/carts/{cartID}/items: get: tags: - Cart Items summary: Get Cart Items description: | Use this endpoint to retrieve cart items. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs. You can use this endpoint to retrieve the breakdown of cart items by promotion ID. For example, if you have Promotions Standard item discount with code *sale2024*, Rule Promotions item discount with code *sale2024*, and Rule Promotions cart discount with code *sale2024*, the `discounts.constituents` field in the response example will show the breakdown of the same promotion code used in both Promotions Standard and Rule Promotions. ```json "data": [ { "id": "98de010d-dd10-4fa5-a070-0b9bcdc72974", "type": "cart_item", "product_id": "5a4662d2-9a2b-4f6e-a215-2970db914b0c", "name": "sku1", "description": "sku1", "sku": "sku1", "slug": "sku1", "image": { "mime_type": "", "file_name": "", "href": "" }, "quantity": 1, "manage_stock": false, "unit_price": { "amount": 10000, "currency": "USD", "includes_tax": false }, "value": { "amount": 10000, "currency": "USD", "includes_tax": false }, "discounts": [ { "amount": { "amount": -2000, "currency": "USD", "includes_tax": false }, "code": "sale2024", "id": "e4d929d5-f471-4317-9a86-a84a6c572b44", "promotion_source": "rule-promotion", "is_cart_discount": true }, { "amount": { "amount": -1000, "currency": "USD", "includes_tax": false }, "code": "sale2024", "id": "de19a043-a6da-4bde-b896-d17e16b77e25", "promotion_source": "rule-promotion" }, { "amount": { "amount": -1000, "currency": "USD", "includes_tax": false }, "code": "sale2024", "id": "509295ee-2971-45b6-801e-95df09756989" }, { "amount": { "amount": -1000, "currency": "USD", "includes_tax": false }, "code": "sale2024", "id": "ca79e606-7ecd-41ac-9478-af4c8c28c546", "promotion_source": "rule-promotion", "is_cart_discount": true } ], "links": { "product": "https://useast.api.elasticpath.com/v2/products/5a4662d2-9a2b-4f6e-a215-2970db914b0c" }, "meta": { "display_price": { "with_tax": { "unit": { "amount": 5000, "currency": "USD", "formatted": "$50.00" }, "value": { "amount": 5000, "currency": "USD", "formatted": "$50.00" } }, "without_tax": { "unit": { "amount": 5000, "currency": "USD", "formatted": "$50.00" }, "value": { "amount": 5000, "currency": "USD", "formatted": "$50.00" } }, "tax": { "unit": { "amount": 0, "currency": "USD", "formatted": "$0.00" }, "value": { "amount": 0, "currency": "USD", "formatted": "$0.00" } }, "discount": { "unit": { "amount": -5000, "currency": "USD", "formatted": "-$50.00" }, "value": { "amount": -5000, "currency": "USD", "formatted": "-$50.00" } }, "without_discount": { "unit": { "amount": 10000, "currency": "USD", "formatted": "$100.00" }, "value": { "amount": 10000, "currency": "USD", "formatted": "$100.00" } }, "discounts": { "sale2024": { "amount": -5000, "currency": "USD", "formatted": "-$50.00", "constituents": { "509295ee-2971-45b6-801e-95df09756989": { "amount": -1000, "currency": "USD", "formatted": "-$10.00" }, "ca79e606-7ecd-41ac-9478-af4c8c28c546": { "amount": -1000, "currency": "USD", "formatted": "-$10.00" }, "de19a043-a6da-4bde-b896-d17e16b77e25": { "amount": -1000, "currency": "USD", "formatted": "-$10.00" }, "e4d929d5-f471-4317-9a86-a84a6c572b44": { "amount": -2000, "currency": "USD", "formatted": "-$20.00" } } } } }, "timestamps": { "created_at": "2024-05-24T18:00:58Z", "updated_at": "2024-05-24T18:00:58Z" } }, "catalog_id": "09b9359f-897f-407f-89a2-702e167fe781", "catalog_source": "pim" } ``` operationId: getCartItems parameters: - name: cartID in: path description: The unique identifier of the cart that you created. required: true style: simple schema: type: string - name: include in: query description: A comma-separated list of related resources to include in the response. required: false style: form explode: false schema: type: array items: type: string enum: - tax_items - custom_discounts - promotions responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemCollectionResponse' deprecated: false put: tags: - Cart Items summary: Bulk Update Items in Cart description: | The bulk update feature allows shoppers to update an array of items to their cart in one action, rather than updating each item one at a time. Shoppers can update quantity and shipping group details in bulk requests. This minimizes the time for shoppers while updating items to their cart. Shoppers can even update multiple items with the same or different shipping groups to their cart. When you update multiple items that qualify for free gifts in the cart, the corresponding free gifts for all eligible products are also automatically updated in the cart. operationId: bulkUpdateItemsInCart parameters: - name: cartID in: path description: The unique identifier of the cart that you created. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/BulkUpdateCartsItems' required: false responses: '200': description: Successfully updated cart items headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemCollectionResponse' '400': description: Insufficient Stock content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Insufficient Stock value: errors: - detail: There is not enough stock to add Fry Pan to your cart meta: id: 0e5bae32-cc71-4ede-8d7d-cb662e90c542 status: 400 title: Insufficient stock '403': description: Unauthorized call content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: No permissions to use custom attributes value: errors: - detail: No permissions to fulfill this request with cart item custom_attributes meta: id: 0e5bae32-cc71-4ede-8d7d-cb662e90c542 status: 403 title: Unauthorised call '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Not Found value: errors: - detail: Item was not found in the cart meta: id: 0e5bae32-cc71-4ede-8d7d-cb662e90c542 ids: - 0e5bae32-cc71-4ede-8d7d-cb662e90c542 status: 404 title: Not Found '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Could not apply EP promotion with the given code value: errors: - detail: The cart is configured to use custom discounts meta: code: 10_OFF ids: - 0e5bae32-cc71-4ede-8d7d-cb662e90c542 status: 422 title: Could not apply EP promotion with the given code deprecated: false post: tags: - Cart Items summary: Add Items to Cart description: | ### Add Product to Cart Adding a Product to Cart is the most common Cart action. If you want to add any custom products or promotions, you need to do that as a separate action. #### Dynamic Bundles A bundle is a purchasable product that is composed of a combination of two or more products that you want to sell together. You can create multiple components within a bundle. Each component can have one or more options. Each option is a product and a quantity. You can configure minimum and/or maximum values for the number of product options in a component that your shoppers can select. For example, you can enable a shopper to select 1 or more product options from a list of 10. These are called [dynamic bundles](/docs/api/pxm/products/products#dynamic-bundles). Your dynamic bundles are displayed in your published catalogs. 1. Use the configure a shopper endpoint to allow shoppers to make their selections from a bundle. 2. In the response of the configure a shopper, the `bundle_configuration` object contains the bundle selections a shopper has made. 3. In the add a product to cart request, use the `bundle_configuration` object to add the customers selections to a cart. ```json "bundle_configuration": { "selected_options": { "games": { "d7b79eb8-19d8-45ea-86ed-2324a604dd9c": 1 }, "toys": { "0192ccdd-6d33-4898-87d7-c4d87f2bf8ea": 1, "1aea6f97-f0d9-452c-b3c1-7fb5629ead82": 1 } } } ``` When a cart is checked out, the options a shopper selected are added to the order. See [order items](/docs/api/carts/get-order-items). #### Personalized Products You can allow shoppers to personalize their goods by adding custom text inputs to products directly. This feature is particularly useful for customizable items, such as personalized T-shirts or greeting cards. You can use this functionality by leveraging the `custom_inputs` attribute, and defining the details and validation rules for the custom text. First, you must configure a `custom_inputs` attribute when creating a new product or updating an existing product. Once you have defined your custom inputs on a product, you must configure the custom inputs in your orders. For example, you may sell T-shirts that can have personalized text on the front and back of the shirt. ```json { "data": { "type": "product", "attributes": { "custom_inputs": { "front": { "name": "T-Shirt Front", "validation_rules": [ { "type": "string", "options": { "max_length": 50 } } ], "required": false }, "back": { "name": "T-Shirt Back", "validation_rules": [ { "type": "string", "options": { "max_length": 50 } } ], "required": false } } } } } ``` If the same product has different `custom_inputs` attributes, then these are added as separate items in a cart. The `custom_inputs` attribute is stored in the cart item and the text for `custom_input` must not exceed 255 characters in length. When a cart is checked out, the `custom_inputs` attribute becomes part of the order. #### Limitations on Usage of `custom_inputs` with Specific Promotion Types When you add products to a cart with `custom_inputs`, there are certain limitations on usage of the `custom_inputs` with the following promotion types: - For [Free Gift Promotions](/docs/api/promotions/create-a-promotion), you can add `custom_inputs` to gift items. - For [Fixed Bundle Discount Promotions](/docs/api/promotions/create-a-promotion), the promotion applies as long as the cart contains the bundle SKUs even when there are different `custom_inputs`. - For [X for Y Discount Promotion and X for amount discount promotion](/docs/api/promotions/create-a-promotion), the promotion applies when there are two SKUs with the same `custom_inputs`. The promotion does not apply when there are different `custom_inputs` and the SKUs are in different line items. #### Stock locations When adding to a cart it is possible to specify which [stock location](/docs/api/pxm/inventory_mli/inventories-introduction?#multi-location-inventories) should be used for tracking inventory for that product by specifying its slug in `location`. This might represent the warehouse a product is shipped from or the store holding the stock in a Buy Online Pick Up In Store scenario. Each line item is restricted to a single stock location. If the same product is added with a different location then the most recently-specified location will be used for the total quantity of that line item. :::note - Any requests to add a product to cart returns the collection of cart items. - [Tax items](/docs/api/carts/tax-items) may optionally be added with the product. Only administrators with [client_credentials access tokens](/docs/api/authentication/create-an-access-token) are able to do this. If included, they replace any existing taxes on the product. - The cart currency is set when the first item is added to the cart. - 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. - A cart can contain a maximum of 100 unique items. Items include products, custom items, tax items, and promotions. - There are a number of actions that happen to your inventory when checking out and paying for an order. For more information, see the [Inventory](/docs/api/pxm/inventory/inventories-introduction) documentation. ::: ### Including Resources When you make an `Add Product to Cart` request to the catalog-view service, you can obtain details of the component products. If you include the optional parameter `include=component_products` in the request, the response will include details for each component product. When a bundle with selected component products is added to a cart, the cart displays both the bundle pricing and component product IDs. The response example is returned with a new field called `component_products` under `bundle_configuration`, which is a list of component products that the user has selected for dynamic bundles. | Parameter | Required | Description | |:------------------------|:-------------|:-------------------| | `component_products` | Optional | The component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle. | | `main_image` | Optional | The main images associated with a product. | | `files` | Optional | Any files associated with a product. | ```json "bundle_configuration": { "selected_options": { "mixed-shirts": { "16a6cc14-6ebb-4156-9973-e6a0f92f5731": 3, "55037cc5-f382-4039-95c6-1e04ac0351d3": 2, "standard-shirts" "70f1c9d2-c580-4839-bd6c-a0a9b91d5159": 5 } }, "component_products": [ { "id": "16a6cc14-6ebb-4156-9973-e6a0f92f5731", "type": "product", "attributes": { "name": "Red T-shirt", "description": "Standard red t-shirt.", "slug": "red-t-shirt-slug", "sku": "red-t-shirt-sku", "status": "live", "commodity_type": "physical" }, "meta": { "display_price": { "without_tax": { "amount": 500, "currency": "USD", "formatted": "$5.00" } } } }, { "id": "55037cc5-f382-4039-95c6-1e04ac0351d3", "type": "product", "attributes": { "name": "Blue T-shirt", "description": "Standard blue t-shirt.", "slug": "blue-t-shirt-slug", "sku": "blue-t-shirt-sku", "status": "live", "commodity_type": "physical" }, "meta": { "display_price": { "without_tax": { "amount": 500, "currency": "USD", "formatted": "$5.00" } } } }, { "id": "70f1c9d2-c580-4839-bd6c-a0a9b91d5159", "type": "product", "attributes": { "name": "White T-shirt", "description": "Standard white t-shirt.", "slug": "white-t-shirt-slug", "sku": "white-t-shirt-sku", "status": "live", "commodity_type": "physical" }, "meta": { "display_price": { "without_tax": { "amount": 500, "currency": "USD", "formatted": "$5.00" } } } } ] } ``` See [Including Resources](https://elasticpath.dev/guides/Getting-Started/includes). ### Add Subscription to Cart To add a subscription to your cart, you need to provide the ID of the subscription offering, and the ID of the pricing option and plan within that offering that you want to subscribe to. ```json { { "data": { "id": "5b9be99f-1c94-4ddd-9718-81adab0cc3e0", "type": "subscription_item", "quantity": 1, "subscription_configuration": { "plan": "dfa31307-748c-4369-8571-709f924a0807", "pricing_option": "40010dde-2f38-489b-8b3f-14a13cbfb431" } } } ``` The price of the subscription item in the cart reflects the cost of the subscription's initial billing period. Once the cart has been checked out and the order paid for, the subscription will be automatically created in the subscriptions service. ### Add Custom Item to Cart You can add a custom item to the cart when you don't manage things like shipping, taxes and inventory in Commerce. For [Shipping Groups](/docs/ship-groups/shipping-groups/index), once you have created a [cart shipping group](/docs/ship-groups/shipping-groups/shipping-groups-api/create-cart-shipping-group), you need to link it to the cart items. This is important, because it is necessary to associate items with shipping groups in order to include shipping groups in the corresponding cart, order, and totals. :::note - Custom Cart Items are available when using [implicit access tokens](/docs/api/authentication/create-an-access-token). Ensure that you always check each order has the correct details for each item, most importantly, price. ::: ### Add Promotion to Cart You can use the Promotions API to apply discounts to your cart as a special cart item type. Any requests to add a product to cart will return a collection of cart items. There are certain limitations on usage of the `custom_inputs` attribute with some promotion types. See [Limitations on Usage of `custom_inputs` with Specific Promotion Types](/docs/api/carts/manage-carts#limitations-on-usage-of-custom_inputs-with-specific-promotion-types). To remove promotion from the cart via the promotion code, see [Delete Promotion Code from Cart](/docs/api/carts/delete-a-promotion-via-promotion-code). ### Re-order From a shopper's order history, they can add the items from a previous order into their carts. Shoppers can add items regardless of past order status, such as incomplete or not paid. For more information, see [Orders](/docs/api/carts/orders). :::note - Any requests to add an item to cart return a collection of [cart items](/docs/api/carts/cart-items). - A cart can contain a maximum of 100 unique items. Items include products, custom items, and promotions. - When a shopper creates a cart and re-orders items from an order with properties such as custom attributes, custom discounts, and payment intent ID, these properties will remain unchanged in the original cart. - Custom items do not exist in catalogs, and therefore cannot be reordered. ::: ### Merging Carts A shopper can have multiple carts, and the system may automatically merge items from an anonymous cart into the shopper's registered cart when they sign in. For example, if a shopper has an existing cart with items `A`, `B` and `C`, and later adds items `D` and `E` while not signed in, the system can merge these carts when the shopper signs in. After the carts merge, the cart contains items `A`, `B`, `C`, `D` and `E`. If any items are duplicated from the anonymous cart to the registered cart, their quantities are incremented accordingly. For example, if a shopper's existing cart with items `A`, `B` and `C`, and they later add two more `A` items and one `B` item while not signed in, the system will merge the carts when the shopper signs in. The existing cart will now contain three `A` items, two `B` items, and one `C` item. :::note When the system merges items from one cart into another cart, properties such as custom attributes, custom discounts, and payment intent ID will remain unchanged in the original cart. ::: ### Best Practices We recommend to include a unique `sku` code within the request body while adding custom items to carts. If the same `sku` is used for multiple products, they are merged into a single line item. For example, if a cart consists of the following items: - `product-1` with quantity 1 and sku code as `sku-1` - `product-2` with quantity 1 and sku code as `sku-1` - `product-3` with quantity 1 and sku code as `sku-2`. The following response is returned where it combines all products with the same sku codes into a single line item, while products with a unique sku codes are represented as separate items: ```json { "data": [ { "id": "c58760f4-8889-4719-b34d-be1f1d11ae59", "type": "custom_item", "name": "product-1", "description": "My first custom item!", "sku": "sku-1", "slug": "", "image": { "mime_type": "", "file_name": "", "href": "" }, "quantity": 2, "manage_stock": false, "unit_price": { "amount": 20000, "currency": "USD", "includes_tax": true }, "value": { "amount": 40000, "currency": "USD", "includes_tax": true }, "links": {}, "meta": { "display_price": { "with_tax": { "unit": { "amount": 20000, "currency": "USD", "formatted": "$200.00" }, "value": { "amount": 40000, "currency": "USD", "formatted": "$400.00" } }, "without_tax": { "unit": { "amount": 20000, "currency": "USD", "formatted": "$200.00" }, "value": { "amount": 40000, "currency": "USD", "formatted": "$400.00" } }, "tax": { "unit": { "amount": 0, "currency": "USD", "formatted": "$0.00" }, "value": { "amount": 0, "currency": "USD", "formatted": "$0.00" } }, "discount": { "unit": { "amount": 0, "currency": "USD", "formatted": "$0.00" }, "value": { "amount": 0, "currency": "USD", "formatted": "$0.00" } }, "without_discount": { "unit": { "amount": 20000, "currency": "USD", "formatted": "$200.00" }, "value": { "amount": 40000, "currency": "USD", "formatted": "$400.00" } } }, "timestamps": { "created_at": "2023-05-02T16:28:11Z", "updated_at": "2023-05-02T16:28:18Z" } } ] ``` operationId: manageCarts parameters: - name: cartID in: path description: The unique identifier of the cart that you created. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: oneOf: - $ref: '#/components/schemas/CartItemObjectRequest' - $ref: '#/components/schemas/SubscriptionItemObject' - $ref: '#/components/schemas/CartMergeObjectRequest' - $ref: '#/components/schemas/CustomItemObject' - $ref: '#/components/schemas/ReOrderObjectRequest' - $ref: '#/components/schemas/PromotionItemObject' - $ref: '#/components/schemas/BulkAddItemsRequest' examples: Add Cart Item: value: data: type: cart_item id: df32387b-6ce6-4802-9b90-1126a5c5a54f quantity: 1 custom_inputs: name: tshirt_front: Jane tshirt_back: Jane Doe's Dance Academy Add Subscription Item: value: data: type: subscription_item id: 1f49c20c-54b9-453b-a57c-ef8303a6415f quantity: 1 subscription_configuration: plan: dfa31307-748c-4369-8571-709f924a0807 pricing_option: a2cd9dae-3a28-4185-93b7-1b02a8ce0c2e Add Custom Item: value: data: type: custom_item name: My Custom Item sku: my-custom-item description: My first custom item! quantity: 1 price: amount: 10000 Add Promotion to Cart: value: data: type: promotion_item code: PROMO_CODE Reorder Items: value: data: type: order_items order_id: da0b0a12-8232-4be1-a354-a1a64b11de91 options: add_all_or_nothing: false Merge Carts: value: data: - type: cart_items cart_id: da0b0a12-8232-4be1-a354-a1a64b11de91 options: add_all_or_nothing: false Bulk Add Items to Cart: value: data: - type: cart_item id: df32387b-6ce6-4802-9b90-1126a5c5a54f quantity: 1 - type: custom_item name: My Custom Item sku: my-custom-item description: My first custom item! quantity: 1 price: amount: 10000 - type: promotion_item code: PROMO_CODE options: add_all_or_nothing: true Add Bundle to Cart: value: data: id: 5ab67bb3-b2c3-4348-af33-e370bd39b0c9 type: cart_item quantity: 1 bundle_configuration: selected_options: tshirt: 23759a57-13c1-4887-9ec2-fb47444751bd: 1 comics: c7bcf7fd-1fab-4635-8ae0-7f187a9dbbce: 1 d9768b40-cf28-406e-bafc-a6d130627eca: 1 Add Item with Shipping Group ID: value: data: type: custom_item name: My Custom Item sku: my-custom-item description: My first custom item! quantity: 1 price: amount: 10000 includes_tax: true shipping_group_id: eb063818-939a-458f-97a4-2601c0c2b445 responses: '201': description: Successfully added item(s) to cart. When promotions are added, the response includes informational messages in the `meta.messages` field describing the promotion and discount effects. headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemCollectionResponse' examples: promotion-added-with-messages: summary: Successful promotion addition with messages (cart discount with promotion_item) value: data: - id: 1359223e-5de0-4d42-a2ec-14350a84c173 type: custom_item name: My Custom Item description: My first custom item! sku: Sample-sku slug: '' image: mime_type: '' file_name: '' href: '' quantity: 1 manage_stock: false unit_price: amount: 10000 currency: USD includes_tax: true value: amount: 10000 currency: USD includes_tax: true discounts: - amount: amount: -1000 currency: USD includes_tax: false code: auto_4c8cc302-b1e8-4d1e-a1d5-fb74fda83705 id: 4c8cc302-b1e8-4d1e-a1d5-fb74fda83705 promotion_source: rule-promotion is_cart_discount: true ordinal: 1 links: {} meta: display_price: with_tax: unit: amount: 9000 currency: USD formatted: $90.00 value: amount: 9000 currency: USD formatted: $90.00 without_tax: unit: amount: 9000 currency: USD formatted: $90.00 value: amount: 9000 currency: USD formatted: $90.00 tax: unit: amount: 0 currency: USD formatted: $0.00 value: amount: 0 currency: USD formatted: $0.00 discount: unit: amount: -1000 currency: USD formatted: '-$10.00' value: amount: -1000 currency: USD formatted: '-$10.00' without_discount: unit: amount: 10000 currency: USD formatted: $100.00 value: amount: 10000 currency: USD formatted: $100.00 discounts: auto_4c8cc302-b1e8-4d1e-a1d5-fb74fda83705: amount: -1000 currency: USD formatted: '-$10.00' constituents: 4c8cc302-b1e8-4d1e-a1d5-fb74fda83705: amount: -1000 currency: USD formatted: '-$10.00' timestamps: created_at: '2025-09-10T22:28:29Z' updated_at: '2025-09-10T22:28:29Z' - id: 7a7fb70a-561a-4caf-a112-c3e5a74145f4 type: promotion_item promotion_id: 4c8cc302-b1e8-4d1e-a1d5-fb74fda83705 name: cart auto description: Promotion sku: auto_4c8cc302-b1e8-4d1e-a1d5-fb74fda83705 slug: '' image: mime_type: '' file_name: '' href: '' quantity: 1 manage_stock: false unit_price: amount: -1000 currency: USD includes_tax: false value: amount: -1000 currency: USD includes_tax: false links: {} meta: display_price: with_tax: unit: amount: -1000 currency: USD formatted: '-$10.00' value: amount: -1000 currency: USD formatted: '-$10.00' without_tax: unit: amount: -1000 currency: USD formatted: '-$10.00' value: amount: -1000 currency: USD formatted: '-$10.00' tax: unit: amount: 0 currency: USD formatted: $0.00 value: amount: 0 currency: USD formatted: $0.00 discount: unit: amount: 0 currency: USD formatted: $0.00 value: amount: 0 currency: USD formatted: $0.00 without_discount: unit: amount: 0 currency: '' formatted: '0' value: amount: 0 currency: '' formatted: '0' timestamps: created_at: '2025-09-10T22:28:29Z' updated_at: '2025-09-10T22:28:29Z' promotion_source: rule-promotion meta: display_price: with_tax: amount: 9000 currency: USD formatted: $90.00 without_tax: amount: 9000 currency: USD formatted: $90.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: -1000 currency: USD formatted: '-$10.00' without_discount: amount: 10000 currency: USD formatted: $100.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T22:28:29Z' expires_at: '2025-09-17T22:28:29Z' messages: - source: type: promotion_item id: 7a7fb70a-561a-4caf-a112-c3e5a74145f4 title: Promotion Added description: Promotion has been added to cart. - source: type: custom_item id: 1359223e-5de0-4d42-a2ec-14350a84c173 title: Discount Added description: Item discount has been added. item-discount-only: summary: Successful promotion with item discount only value: data: - id: 5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34 type: custom_item name: Sample Product sku: sample-sku quantity: 1 unit_price: amount: 10000 currency: USD includes_tax: false value: amount: 9000 currency: USD includes_tax: false discounts: - amount: amount: -1000 currency: USD includes_tax: false code: DISCOUNT10 id: 9993387e-93ab-468f-bba9-cf13882dc52d promotion_source: rule-promotion meta: display_price: with_tax: amount: 9000 currency: USD formatted: $90.00 without_tax: amount: 9000 currency: USD formatted: $90.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: -1000 currency: USD formatted: '-$10.00' without_discount: amount: 10000 currency: USD formatted: $100.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T13:45:54Z' expires_at: '2025-09-17T13:45:54Z' messages: - source: type: custom_item id: 5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34 title: Discount Added description: Item discount has been added. non-stackable-promotion-replacement: summary: Higher priority promotion replaces lower priority non-stackable promotion value: data: - id: 5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34 type: custom_item name: Sample Product sku: sample-sku quantity: 1 unit_price: amount: 10000 currency: USD includes_tax: false value: amount: 8000 currency: USD includes_tax: false discounts: - amount: amount: -2000 currency: USD includes_tax: false code: HIGHER-PRIORITY-CODE id: a8f4b123-5678-4abc-9def-123456789abc promotion_source: rule-promotion meta: display_price: with_tax: amount: 8000 currency: USD formatted: $80.00 without_tax: amount: 8000 currency: USD formatted: $80.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: -2000 currency: USD formatted: '-$20.00' without_discount: amount: 10000 currency: USD formatted: $100.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T13:45:54Z' expires_at: '2025-09-17T13:45:54Z' messages: - source: type: promotion id: 5fe6a1f5-d0ec-4fdc-a115-49f271a6694d code: lower-priority-code title: Couldn't Stack Promotion description: Cannot apply promotion because non-stackable promotion applied first. - source: type: custom_item id: 5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34 title: Discount Added description: Item discount has been added. - source: type: custom_item id: 5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34 title: Discount Deleted description: Item discount has been removed. lower-priority-promotion-rejected: summary: Lower priority promotion rejected when higher priority promotion already applied value: data: - id: 5b1113bb-2a4b-4a5a-b7aa-4b8bbc568d34 type: custom_item name: Sample Product sku: sample-sku quantity: 1 unit_price: amount: 10000 currency: USD includes_tax: false value: amount: 7500 currency: USD includes_tax: false discounts: - amount: amount: -2500 currency: USD includes_tax: false code: HIGHER-PRIORITY-CODE id: a8f4b123-5678-4abc-9def-123456789abc promotion_source: rule-promotion meta: display_price: with_tax: amount: 7500 currency: USD formatted: $75.00 without_tax: amount: 7500 currency: USD formatted: $75.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: -2500 currency: USD formatted: '-$25.00' without_discount: amount: 10000 currency: USD formatted: $100.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T13:45:54Z' expires_at: '2025-09-17T13:45:54Z' messages: - source: type: promotion id: 5fe6a1f5-d0ec-4fdc-a115-49f271a6694d code: lower-priority-code title: Couldn't Stack Promotion description: Cannot apply promotion because non-stackable promotion applied first. bulk-non-stackable-promotions: summary: Bulk request with two non-stackable promotions - higher priority wins value: data: - id: 1e64d793-0ee4-4c06-9875-a3c4ea3320b2 type: custom_item name: Sample Product sku: sample-sku quantity: 1 unit_price: amount: 10000 currency: USD includes_tax: false value: amount: 7000 currency: USD includes_tax: false discounts: - amount: amount: -3000 currency: USD includes_tax: false code: HIGHER-PRIORITY-CODE id: a8f4b123-5678-4abc-9def-123456789abc promotion_source: rule-promotion meta: display_price: with_tax: amount: 7000 currency: USD formatted: $70.00 without_tax: amount: 7000 currency: USD formatted: $70.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: -3000 currency: USD formatted: '-$30.00' without_discount: amount: 10000 currency: USD formatted: $100.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T13:45:54Z' expires_at: '2025-09-17T13:45:54Z' messages: - source: type: promotion id: 5fe6a1f5-d0ec-4fdc-a115-49f271a6694d code: lower-priority-code title: Couldn't Stack Promotion description: Cannot apply promotion because non-stackable promotion applied first. - source: type: custom_item id: f958fe86-7f85-4212-8782-ecda6a52987a title: Discount Added description: Item discount has been added. bulk-partial-success: summary: Bulk operation partial success - valid promotion applied, invalid promotion in errors value: data: - id: 74ab3008-a663-49a1-832b-6d3925b8a94d type: custom_item name: My Custom Item description: My first custom item! sku: dog-bed quantity: 1 unit_price: amount: 10000 currency: USD includes_tax: true value: amount: 10000 currency: USD includes_tax: true discounts: - amount: amount: -500 currency: USD includes_tax: false code: valid-code id: 5fe6a1f5-d0ec-4fdc-a115-49f271a6694d promotion_source: rule-promotion ordinal: 1 meta: display_price: with_tax: unit: amount: 9500 currency: USD formatted: $95.00 value: amount: 9500 currency: USD formatted: $95.00 without_tax: unit: amount: 9500 currency: USD formatted: $95.00 value: amount: 9500 currency: USD formatted: $95.00 discount: unit: amount: -500 currency: USD formatted: '-$5.00' value: amount: -500 currency: USD formatted: '-$5.00' without_discount: unit: amount: 10000 currency: USD formatted: $100.00 value: amount: 10000 currency: USD formatted: $100.00 discounts: valid-code: amount: -500 currency: USD formatted: '-$5.00' constituents: 5fe6a1f5-d0ec-4fdc-a115-49f271a6694d: amount: -500 currency: USD formatted: '-$5.00' timestamps: created_at: '2025-09-10T14:18:34Z' updated_at: '2025-09-10T14:18:34Z' errors: - status: 404 title: Not Found detail: No promotion could be found with the given code. meta: code: invalid-code meta: display_price: with_tax: amount: 9500 currency: USD formatted: $95.00 without_tax: amount: 9500 currency: USD formatted: $95.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: -500 currency: USD formatted: '-$5.00' without_discount: amount: 10000 currency: USD formatted: $100.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T14:18:57Z' expires_at: '2025-09-17T14:18:57Z' messages: - source: type: custom_item id: 74ab3008-a663-49a1-832b-6d3925b8a94d title: Discount Added description: Item discount has been added. bulk-product-partial-success: summary: Bulk product addition - one product added successfully, one product not found value: data: - id: 6585a5bb-fce7-4fb3-8693-2c930d53746c type: cart_item product_id: 25c98289-6303-4d09-a2a2-b27cc90fc3f8 name: Dairy Milk description: '' sku: dairy-milk slug: dairy-milk quantity: 1 unit_price: amount: 400 currency: USD includes_tax: false value: amount: 400 currency: USD includes_tax: false links: product: https://epcc-integration.global.ssl.fastly.net/v2/products/25c98289-6303-4d09-a2a2-b27cc90fc3f8 meta: display_price: with_tax: unit: amount: 400 currency: USD formatted: $4.00 value: amount: 400 currency: USD formatted: $4.00 without_tax: unit: amount: 400 currency: USD formatted: $4.00 value: amount: 400 currency: USD formatted: $4.00 tax: unit: amount: 0 currency: USD formatted: $0.00 value: amount: 0 currency: USD formatted: $0.00 discount: unit: amount: 0 currency: USD formatted: $0.00 value: amount: 0 currency: USD formatted: $0.00 without_discount: unit: amount: 400 currency: USD formatted: $4.00 value: amount: 400 currency: USD formatted: $4.00 timestamps: created_at: '2025-09-10T14:22:54Z' updated_at: '2025-09-10T14:22:54Z' catalog_id: f8606b9b-2a6f-4037-b47f-3254246d9ad2 catalog_source: pim errors: - status: 404 title: Product not found detail: 'product SKU ''invalid-sku'' not found in catalog release ''latestPublished'' in store ID ''42527cca-7c30-4658-827f-734c36d4aca1'': not found' meta: sku: invalid-sku meta: display_price: with_tax: amount: 400 currency: USD formatted: $4.00 without_tax: amount: 400 currency: USD formatted: $4.00 tax: amount: 0 currency: USD formatted: $0.00 discount: amount: 0 currency: USD formatted: $0.00 without_discount: amount: 400 currency: USD formatted: $4.00 shipping: amount: 0 currency: USD formatted: $0.00 shipping_discount: amount: 0 currency: USD formatted: $0.00 timestamps: created_at: '2025-09-08T13:17:42Z' updated_at: '2025-09-10T14:22:54Z' expires_at: '2025-09-17T14:22:54Z' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Invalid Price value: errors: - detail: Must be greater than or equal to 0 meta: value: -100000 status: 400 title: number_gte '403': description: Unauthorized call content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: No permissions to use custom attributes value: errors: - detail: No permissions to fulfill this request with cart item custom_attributes status: 403 title: Unauthorised call '404': description: Not Found - occurs when a referenced product or promotion cannot be found. For bulk operations with add_all_or_nothing=true, the entire operation fails if any item is invalid. content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: A referenced product could not be found value: errors: - detail: The requested product could not be found meta: id: 1c73326e-07e0-4043-81fc-54b8f13daeb4 status: 404 title: Product not found invalid-promotion-code: summary: Invalid or ineligible promotion code value: errors: - detail: No promotion could be found with the given code. meta: code: invalid-code status: 404 title: Not Found bulk-add-all-or-nothing-failure: summary: Bulk add items fails when add_all_or_nothing is true and one item is invalid value: errors: - detail: No promotion could be found with the given code. meta: code: invalid-code status: 404 title: Not Found '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Could not apply EP promotion with the given code value: errors: - detail: The cart is configured to use custom discounts meta: code: 10_OFF ids: - 0e5bae32-cc71-4ede-8d7d-cb662e90c542 status: 422 title: Could not apply EP promotion with the given code '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false delete: tags: - Cart Items summary: Delete all Cart Items description: | A shopper can clean up their cart, deleting custom items, promotions, and so on, while the empty cart remains available. The cart id, name, description, and any account or customer associations persist. The shopper can continue to add items to the cart. operationId: deleteAllCartItems parameters: - name: cartID in: path description: The unique identifier of the cart created by you. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Could not apply EP promotion with the given code value: errors: - detail: The cart is configured to use custom discounts meta: code: 10_OFF status: 422 title: Could not apply EP promotion with the given code deprecated: false parameters: [] /v2/carts/{cartID}/items/{cartitemID}: put: tags: - Cart Items summary: Update a Cart Item description: You can easily update a cart item. A successful update returns the cart items. operationId: updateACartItem parameters: - name: cartID in: path description: A unique identifier of the cart that you created. required: true style: simple schema: type: string - name: cartitemID in: path description: A unique identifier of the cart item. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/UpdateCartsItems' examples: Update Cart Item: value: data: type: cart_item id: 76746981-f63a-45f4-ba9e-59773d89dc2e custom_inputs: personalization: My personal message quantity: 2 Add Item with Shipping Group ID: value: data: type: cart_item id: 76746981-f63a-45f4-ba9e-59773d89dc2e shipping_group_id: eb063818-939a-458f-97a4-2601c0c2b445 required: false responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemCollectionResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Cart Currency Mismatch value: errors: - detail: The existing shipping group uses USD, cannot add this shipping group to a cart item with currency GBP meta: item_ids: - 51197fc0-e217-4f69-a769-b3887f58cfff shipping_group_id: fcb87ec9-a7fb-48c2-bcd9-2151b64e1abc status: 404 title: Cart Currency Mismatch '403': description: Unauthorized call content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: No permissions to use custom attributes value: errors: - detail: No permissions to fulfill this request with cart item custom_attributes meta: id: 76746981-f63a-45f4-ba9e-59773d89dc2e status: 403 title: Unauthorised call '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Not Found value: errors: - detail: Shipping groups not found for this cart. Please verify the shipping groups exists for this cart and are not already associated with orders. meta: cart_id: a-cart-id shipping_group_ids: - fcb87ec9-a7fb-48c2-bcd9-2151b64e1abc status: 404 title: Shipping groups not found deprecated: false delete: tags: - Cart Items summary: Delete a Cart Item description: Use this endpoint to delete a cart item. operationId: deleteACartItem parameters: - name: cartID in: path description: The unique identifier of the cart created by you. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart that you want to delete. required: true style: simple schema: type: string responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemCollectionResponse' deprecated: false parameters: [] /v2/carts/{cartID}/relationships/accounts: post: tags: - Account Cart Associations summary: Create an Account Cart Association description: You can create associations between an account and one or more carts. After cart associations exist for an account, the account can access those carts across any device. operationId: createAccountCartAssociation parameters: - name: cartID in: path description: The ID for the cart created by the account. Ensure that you follow the guidelines for [Safe Characters](/guides/Getting-Started/safe-characters). required: true style: simple schema: type: string - 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}}' requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsRelationshipsAccountsData' required: false responses: '200': description: OK headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsRelationshipsAccountsData' '204': description: No Content is sent back in case the account has already been associated to the cart. headers: {} content: {} '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Invalid Association value: errors: - detail: Unable to associate accounts to carts with contact emails attached. status: 400 title: Cannot associate accounts to carts with contact emails deprecated: false delete: tags: - Account Cart Associations summary: Delete Account Cart Association description: You can delete an association between an account and a cart. operationId: deleteAccountCartAssociation parameters: - name: cartID in: path description: The ID for the cart created by the account. required: true style: simple schema: type: string - 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}}' requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsRelationshipsAccountsData' required: false responses: '204': description: No Content headers: {} content: {} '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false parameters: [] /v2/carts/{cartID}/relationships/customers: post: tags: - Customer Cart Associations summary: Create a Customer Cart Association description: You can create associations between a customer and one or more carts. After cart associations exist for a customer, the customer can access those carts across any device. operationId: createCustomerCartAssociation parameters: - name: cartID in: path description: The ID for the cart created by the customer. Ensure that you follow the guidelines for [Safe Characters](/guides/Getting-Started/safe-characters). required: true style: simple schema: type: string - 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}}' requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsRelationshipsCustomersData' required: false responses: '200': description: OK headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsRelationshipsCustomersData' '204': description: No Content headers: {} content: {} '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '422': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Invalid Association value: errors: - detail: Unable to associate customers to carts with contact emails attached. status: 400 title: Cannot associate customers to carts with contact emails deprecated: false delete: tags: - Customer Cart Associations summary: Delete Customer Cart Association description: You can delete an association between a customer and a cart. operationId: deleteCustomerCartAssociation parameters: - name: cartID in: path description: The ID for the cart created by the customer. required: true style: simple schema: type: string - 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}}' requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsRelationshipsCustomersData' required: false responses: '204': description: No Content headers: {} content: {} '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false parameters: [] /v2/carts/{cartID}/discounts/{promoCode}: delete: tags: - Cart Items summary: Delete a Promotion via Promotion Code description: You can remove promotion code from a cart if it was applied manually. This endpoint does not work if the promotion is applied automatically. operationId: deleteAPromotionViaPromotionCode parameters: - name: cartID in: path description: Specifies the unique identifier of a cart created by you. required: true style: simple schema: type: string - name: promoCode in: path description: Specifies the promotion code to be deleted. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} deprecated: false parameters: [] /v2/carts/{cartID}/items/{cartitemID}/taxes: post: tags: - Tax Items summary: Add Tax Item to Cart description: | Use this endpoint to add a tax item to a cart. :::note There is a soft limit of 5 unique tax items per cart item at any one time. ::: operationId: addTaxItemToCart parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart item. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: rateTaxItem: summary: Add a rate-based tax item value: data: type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.2 amountTaxItem: summary: Add an amount-based tax item value: data: type: tax_item code: GST jurisdiction: AU name: Goods and Services Tax amount: 1000 required: true responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: rateTaxItem: summary: Rate-based tax item value: data: id: 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9 type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.2 '201': description: Created headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: amountTaxItem: summary: Amount-based tax item value: data: id: 3f3b5e26-7e7e-4d2d-a3a7-5e9b1f72fabc type: tax_item code: GST jurisdiction: AU name: Goods and Services Tax amount: 1000 '422': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false parameters: [] /v2/carts/{cartID}/items/{cartitemID}/components/{productID}/taxes: post: tags: - Tax Items summary: Add Tax Item to Bundle Component description: | Use this endpoint to add a tax item to a specific bundle component (component product) within a cart item. :::note There is a soft limit of 5 unique tax items per component product at any one time. ::: operationId: addTaxItemToCartItemComponent parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart item. required: true style: simple schema: type: string - name: productID in: path description: The unique identifier of the component product within the bundle. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: rateTaxItemComponent: summary: Add a rate-based tax item to a bundle component value: data: type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.2 amountTaxItemComponent: summary: Add an amount-based tax item to a bundle component value: data: type: tax_item code: PST jurisdiction: CA-BC name: Provincial Sales Tax amount: 250 required: true responses: '201': description: Created headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: componentRateTaxItem: summary: Rate-based tax item on bundle component value: data: id: 4f4e6d37-8c8c-4a1a-b8a3-6cd2efab12de type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.2 '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '422': description: Unprocessable Entity 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 parameters: [] /v2/carts/{cartID}/items/{cartitemID}/components/{productID}/taxes/{taxitemID}: put: tags: - Tax Items summary: Update Tax Item on Bundle Component description: Use this endpoint to update a tax item on a specific bundle component (component product) within a cart item. To change tax value from `rate` to `amount`, set `rate` to `null`, then set `amount` value and vice versa. operationId: updateTaxItemFromCartItemComponent parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart item. required: true style: simple schema: type: string - name: productID in: path description: The unique identifier of the component product within the bundle. required: true style: simple schema: type: string - name: taxitemID in: path description: The unique identifier of the tax item on the component product. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: updateRateTaxItemComponent: summary: Update a bundle component tax item using rate value: data: type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.18 updateAmountTaxItemComponent: summary: Update a bundle component tax item using amount value: data: type: tax_item code: GST jurisdiction: AU name: Goods and Services Tax amount: 1200 required: false responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: componentUpdatedAmountTaxItem: summary: Updated bundle component tax item (amount) value: data: id: 7aa2ddad-2c5b-4d9b-9ce9-3e8cff778a10 type: tax_item code: GST jurisdiction: AU name: Goods and Services Tax amount: 1200 deprecated: false delete: tags: - Tax Items summary: Delete Tax Item from Bundle Component description: | Use this endpoint to delete a tax item from a specific bundle component (component product) within a cart item. operationId: deleteTaxItemFromCartItemComponent parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart item. required: true style: simple schema: type: string - name: productID in: path description: The unique identifier of the component product within the bundle. required: true style: simple schema: type: string - name: taxitemID in: path description: The unique identifier of the tax item on the component product. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} '404': description: Not Found 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 parameters: [] /v2/carts/{cartID}/taxes: post: tags: - Tax Items summary: Bulk Add Tax Items to Cart description: | Use this endpoint to bulk add tax items to cart items and bundle component products. :::note A cart item can only have a maximum of five tax items. A bundle component product can only have a maximum of five tax items. ::: ### Bundle Component Taxes To add tax items to bundle component products, include a `meta` object with `component_product_id` in each tax item: ```json { "data": [ { "type": "tax_item", "code": "GST", "name": "Goods and Services Tax", "rate": 0.1, "meta": { "component_product_id": "12345678-1234-5678-9012-123456789012" }, "relationships": { "item": { "data": { "type": "cart_item", "id": "cart-item-id" } } } } ] } ``` ### Errors `422 Unprocessable Entity` In this example, when `options.add_all_or_nothing` is set to `true` and if one of cart items is not found or has reached its maximum tax item limit, the following error response is returned: ```json { "status": 422, "title": "Add all or nothing.", "detail": "Add all or nothing set to (true). Could not bulk add tax items to cart." } ``` In this example, if you add more than five tax items to the same cart item, the following error response is returned: ```json { "status": 422, "title": "Tax item not added to cart item.", "detail": "Cannot exceed tax item limit of (5) on cart item.", "meta": { "id": "f88e6370-cb35-40b2-a998-c759f31dec0a" } } ``` `404` In this example, if there is a mismatch between `cart_item`/`custom_item` and the `relationships.item.data.type` specified in the bulk add tax item, the following error response is returned: ```json { "data": [], "errors": [ { "status": 404, "title": "Tax item not added to cart item.", "detail": "Mismatch between bulk tax item type(cart_item) and cart item type(custom_item).", "meta": { "id": "56aab5d1-1dd4-45ed-88ed-4d0cc396b62d" } }, { "status": 404, "title": "Tax item not added to cart item.", "detail": "Mismatch between bulk tax item type(cart_item) and cart item type(custom_item).", "meta": { "id": "56aab5d1-1dd4-45ed-88ed-4d0cc396b62d" } } ] } ``` operationId: bulkAddTaxItemsToCart parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsBulkTaxes' examples: bulkRateTaxItems: summary: Bulk add rate-based tax items to cart items value: data: - type: tax_item code: VAT name: Value Added Tax jurisdiction: UK rate: 0.2 relationships: item: data: type: cart_item id: 5601a4b1-9d13-42d3-8fb7-03b35169d1b6 options: add_all_or_nothing: false bulkAmountTaxItems: summary: Bulk add amount-based tax items to cart and custom items value: data: - type: tax_item code: GST name: Goods and Services Tax jurisdiction: AU amount: 1000 relationships: item: data: type: cart_item id: 1a2b3c4d-5e6f-7a8b-9c0d-abcdefabcdef - type: tax_item code: PST name: Provincial Sales Tax jurisdiction: CA-BC amount: 250 relationships: item: data: type: custom_item id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210 options: add_all_or_nothing: true bulkBundleComponentTaxItems: summary: Bulk add tax items to bundle component products using meta value: data: - type: tax_item code: GST name: Goods and Services Tax jurisdiction: AU rate: 0.1 meta: component_product_id: 12345678-1234-5678-9012-123456789012 relationships: item: data: type: cart_item id: 22223333-4444-5555-6666-777788889999 options: add_all_or_nothing: false required: false responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsBulkTaxes' examples: bulkAddedRateItems: summary: Bulk add response with generated IDs (rate) value: data: - id: 98c2b4de-7f33-4b3a-8f2e-8c1b2a3d4e5f type: tax_item code: VAT name: Value Added Tax jurisdiction: UK rate: 0.2 relationships: item: data: type: cart_item id: 5601a4b1-9d13-42d3-8fb7-03b35169d1b6 '201': description: Created content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsBulkTaxes' examples: bulkAddedAmountAndComponentItems: summary: Bulk add response with amount and component taxes value: data: - id: 2b3c4d5e-6f70-4a8b-9c0d-1e2f3a4b5c6d type: tax_item code: GST name: Goods and Services Tax jurisdiction: AU amount: 1000 relationships: item: data: type: cart_item id: 1a2b3c4d-5e6f-7a8b-9c0d-abcdefabcdef - id: 5e4d3c2b-1a0f-4b8a-9c0d-7f6e5d4c3b2a type: tax_item code: PST name: Provincial Sales Tax jurisdiction: CA-BC amount: 250 relationships: item: data: type: custom_item id: 9f8e7d6c-5b4a-3210-fedc-ba9876543210 '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false delete: tags: - Tax Items summary: Bulk Delete Tax Items from Cart description: | Use this endpoint to bulk delete all tax items from all cart items and bundle component products in the cart. :::warning This operation will remove ALL tax items from: - All cart items in the cart - All bundle component products within bundle cart items ::: ### Behavior - Removes all tax items from every cart item - Removes all tax items from every component product in bundle cart items - If no tax items exist anywhere in the cart, returns a 404 error ### Errors `404 Not Found` If no tax items exist in the cart (on cart items or component products): ```json { "status": 404, "title": "Resource Not Found", "detail": "No tax items exist in the cart" } ``` operationId: bulkDeleteTaxItemsFromCart parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} '404': description: Not Found - No tax items exist in the cart content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false parameters: [] /v2/carts/{cartID}/items/{cartitemID}/taxes/{taxitemID}: put: tags: - Tax Items summary: Update a Tax Item description: Use this endpoint to update a tax item. To change tax value from `rate` to `amount`, set `rate` to `null`, then set `amount` value and vice versa. operationId: updateATaxItem parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart item. required: true style: simple schema: type: string - name: taxitemID in: path description: The unique identifier of the tax item. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: updateRateTaxItem: summary: Update a tax item using rate value: data: type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.15 updateAmountTaxItem: summary: Update a tax item using amount value: data: type: tax_item code: GST jurisdiction: AU name: Goods and Services Tax amount: 1500 required: false responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartItemTaxesEntityResponse' examples: updatedRateTaxItem: summary: Updated tax item (rate) value: data: id: 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9 type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.15 deprecated: false delete: tags: - Tax Items summary: Delete a Tax Item description: Use this endpoint to delete a tax item. operationId: deleteATaxItem parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: The unique identifier of the cart item. required: true style: simple schema: type: string - name: taxitemID in: path description: The unique identifier of the tax item. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} deprecated: false parameters: [] /v2/carts/{cartID}/custom-discounts: post: tags: - Custom Discounts summary: Bulk Add Custom Discounts to Cart description: | The default value for custom discounts on both the cart and cart items is set to 5 if this parameter is not configured in the store. To verify the custom discount limit value, call [Get all settings](/docs/api/settings/get-v-2-settings) endpoint. To increase the custom discount value, contact [Elastic Path Support team](https://support.elasticpath.com/hc/en-us). operationId: bulkAddCustomDiscountsToCart parameters: - name: cartID in: path description: Specifies the system generated ID for the cart that the shopper created. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartsBulkCustomDiscounts' required: false responses: '201': description: '' headers: {} content: application/json: schema: oneOf: - $ref: '#/components/schemas/CartsBulkCustomDiscountsResponse' - $ref: '#/components/schemas/CartsBulkCustomDiscountsCollectionResponse' '400': description: Could not apply custom discount content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: summary: Custom discounts not enabled for this cart value: errors: - detail: Custom discounts not enabled for this cart status: 400 title: Bad Request '422': description: Could not apply custom discount content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: summary: Exceeded custom discount limit value: errors: - detail: Cannot exceed custom discount limit of (1) at the cart level. status: 422 title: Custom discount not added to cart deprecated: false delete: tags: - Custom Discounts summary: Bulk Delete Custom Discounts From Cart description: Use this endpoint to bulk delete custom discounts from cart. operationId: bulkDeleteCustomDiscountsFromCart parameters: - name: cartID in: path description: Specifies the unique ID for the cart. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} deprecated: false parameters: [] /v2/carts/{cartID}/custom-discounts/{customdiscountID}: put: tags: - Custom Discounts summary: Update Custom Discount For Cart description: Use this endpoint to update a custom discount in your cart. operationId: updateCustomDiscountForCart parameters: - name: cartID in: path description: Specifies the unique ID for the cart. required: true style: simple schema: type: string - name: customdiscountID in: path description: Specifies the ID for the custom discount to be updated. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartsCustomDiscountsEntityRequest' required: false responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartsCustomDiscountsEntityResponse' deprecated: false delete: tags: - Custom Discounts summary: Delete Custom Discount From Cart description: Use this endpoint to delete custom discount from cart. operationId: deleteCustomDiscountFromCart parameters: - name: cartID in: path description: Specifies the unique ID for the cart. required: true style: simple schema: type: string - name: customdiscountID in: path description: Specifies the ID for the custom discount to be deleted. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} deprecated: false parameters: [] /v2/carts/{cartID}/items/{cartitemID}/custom-discounts: post: tags: - Custom Discounts summary: Add Custom Discount To Cart Item description: Use this endpoint to add a custom discount to cart item. operationId: addCustomDiscountToCartItem parameters: - name: cartID in: path description: Specifies the ID for the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: Specifies the unique identifier for the cart item. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/CartsCustomDiscountsObject' responses: '201': description: Successful request headers: {} content: application/json: schema: oneOf: - $ref: '#/components/schemas/CartsCustomDiscountsCollectionResponse' - $ref: '#/components/schemas/CartsCustomDiscountsEntityResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Required field missing value: errors: - detail: Custom discounts not enabled for this cart status: 400 title: Bad Request '422': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Discount Limit Reached value: errors: - detail: Custom discount limit reached for this cart item status: 422 title: Limit Reached deprecated: false parameters: [] /v2/carts/{cartID}/items/{cartitemID}/custom-discounts/{customdiscountID}: put: tags: - Custom Discounts summary: Update Custom Discount For Cart Item description: Use this endpoint to update a custom discount in your cart item. operationId: updateCustomDiscountForCartItem parameters: - name: cartID in: path description: Specifies the ID for the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: Specifies the ID for the cart item. required: true style: simple schema: type: string - name: customdiscountID in: path description: Specifies the ID for the custom discount to be updated. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/CartsCustomDiscountsEntityRequest' responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/CartsCustomDiscountsEntityResponse' deprecated: false delete: tags: - Custom Discounts summary: Delete Custom Discount From Cart Item description: Use this endpoint to delete custom discount from cart item. operationId: deleteCustomDiscountFromCartItem parameters: - name: cartID in: path description: Specifies the ID for the cart. required: true style: simple schema: type: string - name: cartitemID in: path description: Specifies the ID for the cart item. required: true style: simple schema: type: string - name: customdiscountID in: path description: Specifies the ID for the custom discount to be deleted. required: true style: simple schema: type: string responses: '204': description: No Content headers: {} content: {} deprecated: false parameters: [] /v2/carts/{cartID}/shipping-groups: get: tags: - Cart Shipping Groups summary: Retrieve all shipping groups for a cart operationId: getShippingGroups description: Retrieve all shipping groups for a cart parameters: - name: cartID in: path required: true description: The ID of the cart schema: type: string responses: '200': description: A list of shipping groups content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ShippingGroupResponse' examples: Retrieve Shipping Groups for a Cart: value: data: - id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 type: shipping_group relation: cart cart_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 shipping_type: standard tracking_reference: TRACK123 meta: shipping_display_price: total: amount: 1000 currency: USD formatted: $10.00 base: amount: 800 currency: USD formatted: $8.00 tax: amount: 200 currency: USD formatted: $2.00 fees: amount: 0 currency: USD formatted: $0.00 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door delivery_estimate: start: '2024-01-15T00:00:00Z' end: '2024-01-20T00:00:00Z' '404': description: Cart not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' post: tags: - Cart Shipping Groups summary: Create a new shipping group for a cart operationId: createShippingGroup description: Create a new shipping group for a cart parameters: - name: cartID in: path required: true description: The ID of the cart schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateShippingGroupRequest' responses: '201': description: Shipping group created successfully content: application/json: schema: $ref: '#/components/schemas/ShippingGroupEntityResponse' example: data: id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 type: shipping_group relation: cart cart_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 shipping_type: standard tracking_reference: TRACK123 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door delivery_estimate: start: '2024-01-15T00:00:00Z' end: '2024-01-20T00:00:00Z' created_at: '2024-01-10T12:00:00Z' updated_at: '2024-01-10T12:00:00Z' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: currency_mismatch: value: errors: - status: 400 title: Cart Currency Mismatch detail: This cart uses USD, cannot add shipping group with currency EUR invalid_dates: value: errors: - status: 400 title: Date Logic Discrepancy detail: The start date cannot occur after the end date '404': description: Cart not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 404 title: Not Found detail: Cart not found /v2/carts/{cartId}/shipping-groups/{shippingGroupId}: get: tags: - Cart Shipping Groups summary: Retrieve a specific shipping group for a cart operationId: getShippingGroupById description: Retrieve a specific shipping group for a cart parameters: - name: cartId in: path required: true description: The ID of the cart schema: type: string - name: shippingGroupId in: path required: true description: The ID of the shipping group schema: type: string responses: '200': description: Shipping group details content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShippingGroupResponse' example: data: id: 7cfa5b07-092e-4dbe-bbad-55a771a34117 type: shipping_group relation: cart cart_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 shipping_type: standard tracking_reference: TRACK123 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door delivery_estimate: start: '2024-01-15T00:00:00Z' end: '2024-01-20T00:00:00Z' meta: shipping_display_price: total: amount: 1000 currency: USD formatted: $10.00 base: amount: 800 currency: USD formatted: $8.00 tax: amount: 200 currency: USD formatted: $2.00 fees: amount: 0 currency: USD formatted: $0.00 '404': description: Shipping group or cart not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: cart_not_found: value: errors: - status: 404 title: Not Found detail: Cart not found shipping_group_not_found: value: errors: - status: 404 title: Cart shipping group not found detail: Cart shipping group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for cart [abc123] put: tags: - Cart Shipping Groups summary: Update a shipping group for a cart description: Update a specific shipping group for a cart operationId: updateShippingGroup parameters: - name: cartId in: path required: true description: The ID of the cart schema: type: string - name: shippingGroupId in: path required: true description: The ID of the shipping group schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateCartShippingGroupRequest' example: data: type: shipping_group shipping_type: express tracking_reference: TRACK456 shipping_price: base: 1500 tax: 300 fees: 200 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door responses: '200': description: Shipping group updated successfully content: application/json: schema: $ref: '#/components/schemas/ShippingGroupEntityResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: currency_mismatch: value: errors: - status: 400 title: Cart Currency Mismatch detail: The existing shipping group uses USD, cannot update shipping group with currency EUR invalid_dates: value: errors: - status: 404 title: Date Logic Discrepancy detail: The start date cannot occur after the end date '404': description: Shipping group or cart not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 404 title: Cart shipping group not found detail: Cart shipping group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for cart [abc123] delete: tags: - Cart Shipping Groups summary: Delete Cart Shipping Group description: | Deletes a shipping group from a cart. You cannot delete a shipping group that is attached to cart items. You must first remove the shipping group from all cart items before deleting the shipping group. operationId: deleteCartShippingGroup parameters: - name: cartId in: path required: true description: The ID of the cart schema: type: string - name: shippingGroupId in: path required: true description: The ID of the shipping group to delete schema: type: string responses: '204': description: Successfully deleted the shipping group '400': description: Cannot delete shipping group that is attached to cart items content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 400 title: Cannot delete shipping group detail: Cannot delete shipping groups attached to cart items. Please remove the shipping group from its cart items and try again. '404': description: Cart or shipping group not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' /v2/carts/{cartID}/payments: post: tags: - Payments summary: Create Stripe Payment Intent for a Cart description: | The Cart Payment Intent feature enables the creation of a Stripe Payment Intent specifically tied to a shopping cart and its subsequent order. This allows Payment Intent users to track payment details from the cart stage and seamlessly maintain consistency in payment information throughout the order stage. Using these features, you can create Payment Intents for their carts, update Payment Intents with final cart details, and synchronize Payment Intents from Stripe to Commerce. :::note - Typically, in Commerce, inventory is allocated at the time of payment initiation after an order is created. However, in the case of Cart Payment Intent, information about the payment is received only upon synchronizing the order from Stripe to Commerce. This may happen after the payment is completed. Therefore, there might be a delay between the payment made and allocation, increasing the chance of paying for items that are not in stock. - There are certain fields you can choose to set up when [creating a payment intent](https://stripe.com/docs/api/payment_intents/create). However, if you decide to update a payment intent, the available options may not be the same as those allowed while creating a payment intent. See [updating a payment intent](https://stripe.com/docs/api/payment_intents/update). ::: The following steps outline the workflow associated with the Payment Intent: 1. [Add items to cart](/docs/api/carts/manage-carts#add-custom-item-to-cart). 1. [Create a Payment Intent for the cart](/docs/api/carts/create-cart-payment-intent). The Payment Intent is created in Stripe, reflecting the cart and transaction details, including currency, amounts, payment type, and any optional Stripe details. The Payment Intent ID is generated and linked to the cart. 1. [Update a Payment Intent](/docs/carts-orders/update-cart-payment-intent). This step is optional but becomes necessary when there are changes in the cart details at the time of payment. It ensures the Payment Intent accurately reflects the current cart details when processing the payments on the front end. 1. [Checkout the cart](/docs/api/carts/checkout). An unpaid order is created, and the Payment Intent ID is linked to the order. 1. [Confirm the order](/docs/carts-orders/confirm-an-order). This is important because after checkout, it is essential to confirm the Payment Intent and synchronize it with Commerce. This results in a corresponding transaction and change in order statuses in Commerce. Additionally, the Payment Intent ID is removed from the order once it is linked via the transaction. ### Best Practices We recommend you follow these practices to maintain consistency and accuracy when using Cart Payment Intent. - After checkout, we recommend clearing the shopping cart. You can achieve this using a [Delete a cart](/docs/api/carts/delete-a-cart) endpoint or [Update a cart](/docs/api/carts/update-a-cart) to remove the Payment Intent ID. This helps to avoid potential issues where subsequent checkouts for the same cart might unintentionally use the previous Stripe Payment Intent ID. - If it is not reasonable to clear the cart immediately after checkout due to several subsequent, duplicate checkouts to the same cart, ensure that you only synchronize the Payment Intent when finalizing the order. Each order confirmation is unaware of the others, and syncing Payment Intent IDs for each confirmation can lead to duplicate transactions in Commerce. In other words, if you synchronize Payment Intents for earlier versions of a repeated checkout, you'll end up with multiple orders from the same cart, each having transactions linked to the same Payment Intent. - To pay the entire amount at once, use the [Update Cart Payment Intent](/docs/carts-orders/update-cart-payment-intent) endpoint to update the Stripe Payment Intent with the final cart details when preparing to take the payment. Doing so, ensures that the Payment Intent accurately reflects the current cart details when processing payments on the front end. We do not recommend calling the [Update Cart Payment Intent](/docs/carts-orders/update-cart-payment-intent) for each individual change in the cart, as this can lead to more requests and may slow down the front-end performance. operationId: createCartPaymentIntent parameters: - name: cartID in: path required: true style: simple schema: type: string description: The universally unique identifier of the cart for which you want to create a payment intent. requestBody: required: false content: application/json: schema: $ref: '#/components/schemas/ElasticPathPaymentsPoweredByStripePayment' examples: Create Stripe Payment Intent for a Cart: value: data: gateway: elastic_path_payments_stripe method: purchase options: automatic_payment_methods: enabled: true receipt_email: john@example.com Create Stripe Payment Intent for a Cart Using Specific Payment Methods: value: data: gateway: elastic_path_payments_stripe method: purchase payment_method_types: - affirm - card - link options: receipt_email: john@example.com responses: '201': description: Payment Intent created successfully. content: application/json: schema: $ref: '#/components/schemas/CartEntityResponse' deprecated: false parameters: [] /v2/carts/{cartID}/payments/{paymentIntentID}: put: tags: - Cart Payments summary: Update a Payment Intent on a Cart description: Updates the payment information for a specific payment intent on a cart. operationId: updateCartPaymentIntent parameters: - name: cartID in: path description: The unique identifier of the cart. required: true style: simple schema: type: string - name: paymentIntentID in: path description: The unique identifier of the payment intent. required: true style: simple schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CartPaymentUpdate' responses: '200': description: Payment updated successfully content: application/json: schema: $ref: '#/components/schemas/CartEntityResponse' deprecated: false /v2/carts/{cartID}/checkout: 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. A cart can be checked out with a customer ID, customer object, or with an account by authenticating with the `Client Credentials Token`. After 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. You can checkout using one of the following methods: - **Customer ID**: You can checkout a cart with an existing customer ID. - **Guest Checkout** (Checkout with Customer Object): You can checkout a cart with an associated customer name and email. - **Checkout with Account**: The shopper authenticates with the `Client Credentials` Token. - **Checkout with Account Management Authentication Token**: The shopper authenticates with the `Implicit Token` and the `EP-Account-Management-Authentication-Token`. :::note - The cart currency is set when the first item is added to the cart. - 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. - 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. ::: :::caution - 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). - 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. ::: 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. ### Next Steps After 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). ### Errors The following error response is returned during checkout when an eligible item is added to the cart, and the free gift is out of stock. ```json { "errors": [ { "status": 400, "title": "Insufficient stock", "detail": "There is not enough stock to add gift2 to your cart", "meta": { "id": "f2b68648-9621-45a3-aed6-1b526b0f5beb", "sku": "gift2" } } ] } ``` 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 parameters: [] /v2/quotes: parameters: [] /v2/quotes/{quoteID}: parameters: [] /v2/quotes/{quoteID}/items: parameters: [] /v2/quotes/{quoteID}/taxes: parameters: [] /v2/quotes/{quoteID}/items/{itemID}/taxes: parameters: [] /v2/quotes/{quoteID}/items/{itemID}/taxes/{taxitemID}: parameters: [] /v2/quotes/{quoteID}/items/{itemID}/components/{productID}/taxes: parameters: [] /v2/quotes/{quoteID}/items/{itemID}/components/{productID}/taxes/{taxitemID}: parameters: [] /v2/orders: 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 parameters: [] /v2/orders/{orderID}: 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: | { "errors": [ { "detail": "Order not found", "status": "404", "title": "Not Found" } ] } 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. This endpoint allows you to: - **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. - **Cancel an order**: You can cancel an order only if it has not been fulfilled. - **Fulfill an order**: You can fulfill a paid order only. :::caution You 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. ::: :::note - This request is only accessible to client credentials token users with Seller Admin role. - Non client credentials token users cannot access this endpoint. See [Permissions](/docs/authentication/tokens/permissions). - The `order_number` will appear as the invoice number in Authorize.net transactions. ::: 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: | { "errors": [ { "detail": "Request could not be processed", "status": "400", "title": "Bad Request" } ] } '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Validation error value: | { "errors": [ { "detail": "Order cannot be updated in its current state", "status": "422", "title": "Unprocessable Entity" } ] } deprecated: false parameters: [] /v2/orders/{orderID}/items: 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 parameters: [] /v2/orders/anonymize: 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 parameters: [] /v2/orders/{orderID}/confirm: 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: | { "errors": [ { "detail": "Request could not be processed", "status": "400", "title": "Bad Request" } ] } '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Order not found value: | { "errors": [ { "detail": "Order not found", "status": "404", "title": "Not Found" } ] } '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Validation error value: | { "errors": [ { "detail": "Order cannot be confirmed in its current state", "status": "422", "title": "Unprocessable Entity" } ] } parameters: [] /v2/orders/{orderID}/payments: post: tags: - Payments summary: Payments description: | Depending on the payment gateway, you may have access to different transaction types such as capturing funds immediately or authorizing them for later. For more information, see [Payments](/docs/api/carts/payments). The following types of payment methods are available depending on the payment gateway: - `purchase`: This is the simplest method. The gateway attempts to charge the customer immediately. - `authorize`: This method authorizes a payment so that funds can be captured later, for example, when an item is dispatched or restocked. - `purchase_setup`: This method prepares the system for a purchase by verifying payment details without actually charging the customer. For example, a customer adds items to their cart and proceeds to checkout. Before finalizing the purchase, the system runs `purchase_setup` to confirm all payment details, but no funds are transferred until the customer confirms the order. - `authorize_setup`: This method prepares the system for an authorization-only transaction. This process holds the necessary funds but does not transfer them, ensuring that the customer has sufficient balance for the transaction. It sets up the conditions for a future capture of the authorized funds. For example, a customer places a pre-order for a product that will ship in two weeks. The merchant uses `authorize_setup` to prepare for the payment authorization. This holds the customer's funds to ensure they can cover the purchase but waits to capture the payment until the product ships. This ensures that payment is secured but not collected prematurely. :::note Split payments can be performed using any methods for any gateway. - You can partially pay funds using `purchase` method. The gateway attempts to charge the customer immediately, and the payment status for an order will show `partially_paid` - You can partially pay for an order using `authorize` method where the order will be marked as `partially_authorized`. The transaction must be completed for the order status to be `partially_authorized`. - A `purchase_setup` method allows verification of payment details for partial payments without transferring funds until the customer confirms the full order. - An `authorize_setup` method can be used to hold a partial amount of the total funds, ensuring the customer has enough balance for a future capture. Until a payment is made neither `purchase_setup` nor `authorize_setup` affects the payment statuses, and the order remains unpaid. For more information about order and payment statuses for split payments, see [Split payments](/docs/api/payments/payment-gateways-introduction#split-payments). ::: operationId: paymentSetup parameters: - name: orderID in: path description: The Universally Unique Identifier (UUID) of the order you want to pay for. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentsRequest' required: false responses: '200': description: OK 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: errors: - detail: Request could not be processed status: '400' title: Bad Request '409': description: Conflict content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false parameters: [] /v2/orders/{orderID}/transactions/{transactionID}/confirm: post: tags: - Payments summary: Confirm Payment description: | Confirm Payment serves as a mechanism to synchronize transaction information from the third-party payment provider back to our system. This ensures that Composable Commerce accurately reflects the values from the payment provider. ### Handling 3D Secure Validations for Stripe Payments For Stripe Payments requiring 3D Secure validation, the transaction response will include the `client_parameters` object, which provides credentials to support validation of these payment requests on the payment provider's side. We recommend using the Stripe's client libraries to manage these 3D Secure validations. Once the validation succeeds, proceed with a confirmation request to sync the validated transaction into Composable Commerce and continue with the payment process. operationId: confirmPayment parameters: - name: orderID in: path description: The unique identifier of the order. required: true style: simple schema: type: string - name: transactionID in: path description: The unique identifier of the transaction. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/OrdersTransactionsConfirmRequest' responses: '200': description: '' headers: {} 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: errors: - detail: Request could not be processed status: '400' title: Bad Request deprecated: false parameters: [] /v2/orders/{orderID}/transactions/{transactionID}/capture: post: tags: - Payments summary: Capture a Transaction description: Use this endpoint to capture a previously authorized payment. In this step, you can also pass in a custom reference, such as the payment reference from your chosen gateway. operationId: captureATransaction parameters: - name: orderID in: path description: The UUID of the order. required: true style: simple schema: type: string - name: transactionID in: path description: The UUID of the transaction to capture. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/OrdersTransactionsCaptureRequest' required: false responses: '200': description: '' headers: {} 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: errors: - detail: Request could not be processed status: '400' title: Bad Request deprecated: false parameters: [] /v2/orders/{orderID}/transactions/{transactionID}/refund: post: tags: - Payments summary: Refund a Transaction description: | There are two ways to refund; through your payment gateway and mark it refunded in Commerce Manager, or directly through Commerce Manager or API. * Mark as Refunded: You can manually mark a transaction as refunded. Before you can mark the order as refunded, you need to handle the actual refund on your side with your payment provider. Mark as Refunded is a full refund made to the transaction. * Refund through Composable Commerce: You can process a full or partial refund to a supported payment provider directly from Commerce Manager or API by providing the refund amount. When you start the refund process, the request is directly sent to the payment gateway. :::caution If you use manual gateway for partial or full refund, you need to handle the actual refund on your side with your payment provider. ::: operationId: refundATransaction parameters: - name: orderID in: path description: The UUID of the order. required: true style: simple schema: type: string - name: transactionID in: path description: The UUID of the transaction you want to refund. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/OrdersTransactionsRefundRequest' required: false responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/TransactionEntityResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Validation error value: | { "errors": [ { "detail": "Transaction cannot be refunded in its current state", "status": "422", "title": "Unprocessable Entity" } ] } deprecated: false parameters: [] /v2/orders/{orderID}/transactions: get: tags: - Payments summary: Get Order Transactions description: Get order transactions operationId: getOrderTransactions parameters: - name: orderID in: path description: The unique identifier of the order. required: true style: simple schema: type: string responses: '200': description: '' headers: {} content: application/json: schema: $ref: '#/components/schemas/TransactionListResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: default: summary: Required field missing value: | { "errors": [ { "detail": "Request could not be processed", "status": "400", "title": "Bad Request" } ] } deprecated: false parameters: [] /v2/orders/{orderID}/transactions/{transactionID}: get: tags: - Payments summary: Get a Transaction description: Retrieves a transaction operationId: getATransaction parameters: - name: orderID in: path description: The unique identifier of the order that you require transactions for. required: true style: simple schema: type: string - name: transactionID in: path description: The unique identifier of the transaction. required: true style: simple schema: type: string responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/Response.Data' - type: object properties: data: $ref: '#/components/schemas/TransactionResponse' deprecated: false parameters: [] /v2/orders/{orderID}/transactions/{transactionID}/cancel: post: tags: - Payments summary: Cancel a Transaction description: | Use this endpoint to cancel or void a pending or authorized transaction. The transaction can be canceled or voided when it is in `pending` and `completed` statuses. :::caution This endpoint works only for Stripe and PayPal and does not work for manual gateway. ::: operationId: cancelATransaction parameters: - name: orderID in: path description: The unique identifier of the order. required: true style: simple schema: type: string - name: transactionID in: path description: The unique identifier of the transaction to be canceled or voided. required: true style: simple schema: type: string requestBody: description: '' content: application/json: schema: allOf: - $ref: '#/components/schemas/OrdersTransactionsCancelRequest' required: false responses: '200': description: '' headers: {} content: application/json: schema: allOf: - $ref: '#/components/schemas/TransactionEntityResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false parameters: [] /v2/orders/{orderID}/shipping-groups: get: operationId: getOrderShippingGroups tags: - Order Shipping Groups summary: Retrieve all shipping groups for an order description: Retrieve all shipping groups for an order parameters: - name: orderID in: path required: true description: The ID of the order schema: type: string responses: '200': description: A list of shipping groups content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/ShippingGroupResponse' example: data: - id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 type: shipping_group relation: order order_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 shipping_type: standard tracking_reference: TRACK123 meta: shipping_display_price: total: amount: 1000 currency: USD formatted: $10.00 base: amount: 800 currency: USD formatted: $8.00 tax: amount: 200 currency: USD formatted: $2.00 fees: amount: 0 currency: USD formatted: $0.00 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door delivery_estimate: start: '2024-01-15T00:00:00Z' end: '2024-01-20T00:00:00Z' '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 404 title: Not Found detail: Order not found post: operationId: createOrderShippingGroup tags: - Order Shipping Groups summary: Create a shipping group for an order description: Create a new shipping group for an order parameters: - name: orderID in: path required: true description: The ID of the order schema: type: string requestBody: description: Shipping group details content: application/json: schema: type: object properties: data: type: object required: - type properties: type: type: string const: shipping_group shipping_type: type: string description: The shipping type for this group tracking_reference: type: string description: Tracking reference for the shipment address: type: object properties: first_name: type: string last_name: type: string phone_number: type: string company_name: type: string line_1: type: string line_2: type: string city: type: string postcode: type: string county: type: string country: type: string region: type: string instructions: type: string delivery_estimate: type: object properties: start: type: string format: date-time end: type: string format: date-time responses: '201': description: Shipping group created content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/ShippingGroupResponse' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 400 title: Bad Request detail: Invalid request format '404': description: Order not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 404 title: Not Found detail: Order not found '422': description: Unprocessable Entity content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 422 title: Unprocessable Entity detail: Cannot create shipping group for this order /v2/orders/{orderID}/shipping-groups/{shippingGroupID}: get: operationId: getShippingGroupsById tags: - Order Shipping Groups summary: Retrieve a specific shipping group for an order description: Retrieve a specific shipping group for an order parameters: - name: orderID in: path required: true description: The ID of the order schema: type: string - name: shippingGroupID in: path required: true description: The ID of the shipping group schema: type: string - name: include in: query description: A comma-separated list of related resources to include in the response. required: false style: form explode: false schema: type: string const: items responses: '200': description: Shipping group details content: application/json: schema: $ref: '#/components/schemas/ShippingGroupEntityResponse' example: data: id: 7cfa5b07-092e-4dbe-bbad-55a771a34117 type: shipping_group relation: order order_id: 96b1d104-0d2e-41fd-9543-6c3c5a698959 shipping_type: standard tracking_reference: TRACK123 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door delivery_estimate: start: '2024-01-15T00:00:00Z' end: '2024-01-20T00:00:00Z' meta: shipping_display_price: total: amount: 1000 currency: USD formatted: $10.00 base: amount: 800 currency: USD formatted: $8.00 tax: amount: 200 currency: USD formatted: $2.00 fees: amount: 0 currency: USD formatted: $0.00 '404': description: Shipping group or order not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: order_not_found: value: errors: - status: 404 title: Not Found detail: Order not found shipping_group_not_found: value: errors: - status: 404 title: Group not found detail: Group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for order [abc123] put: tags: - Order Shipping Groups summary: Update a shipping group for an order description: Update a shipping group for an order operationId: putShippingGroupById parameters: - name: orderID in: path required: true description: The ID of the order schema: type: string - name: shippingGroupID in: path required: true description: The ID of the shipping group schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateOrderShippingGroupRequest' example: data: type: shipping_group shipping_type: express tracking_reference: TRACK456 address: first_name: John last_name: Doe phone_number: (555) 555-1234 company_name: ACME Corp line_1: 123 Main St line_2: Suite 100 city: Portland postcode: '97201' county: Multnomah country: US region: Oregon instructions: Leave at front door responses: '200': description: Shipping group updated successfully content: application/json: schema: $ref: '#/components/schemas/ShippingGroupEntityResponse' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' examples: invalid_dates: value: errors: - status: 400 title: Date Logic Discrepancy detail: The start date cannot occur after the end date fulfilled_order: value: errors: - status: 400 title: Bad Request detail: Cannot update order shipping address because shipping status is fulfilled '404': description: Shipping group or order not found content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' example: errors: - status: 404 title: Group not found detail: Group with ID [7cfa5b07-092e-4dbe-bbad-55a771a34117] not found for order [abc123] /v2/settings/cart: get: tags: - Cart Settings summary: Get Cart Settings description: Retrieves cart settings. operationId: get-v2-settings-cart responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SettingsCart' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false put: tags: - Cart Settings summary: Update Cart Settings description: |- You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings). With update cart settings endpoint, you can: - Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store. - Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint. - Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout. - Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`. - Enable or disable location-based item separation by setting `separate_items_by_location` to `true`. When enabled, cart items with the same SKU but different locations are kept as separate line items instead of being merged. :::note You cannot use both custom discounts and rule promotions at the same time. ::: ### Errors The following error is received if you enable a cart to use both custom discounts and rule promotions: ```json { "status": 422, "title": "Cannot use both discounts together", "detail": "Only one discount setting can be set to true at a time." } ``` operationId: put-v2-settings-cart requestBody: content: application/json: schema: $ref: '#/components/schemas/SettingsCart' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SettingsCart' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false /v2/settings/cart/{storeID}: parameters: - name: storeID in: path description: The store ID. required: true schema: type: string get: tags: - Cart Settings summary: Get Cart Settings by Store ID description: Retrieves cart settings for the specified store. operationId: get-v2-settings-cart-storeID responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SettingsCart' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false put: tags: - Cart Settings summary: Update Cart Settings by Store ID description: |- You can modify the cart expiry settings to set it to any number of days up to 365. Any existing carts default to the expiry of 7 days. To update cart settings in Commerce Manager, see [Updating Cart setting](/docs/commerce-manager/settings/general-settings#updating-cart-settings). With update cart settings endpoint, you can: - Enable or disable custom discounts by setting the `custom_discounts_enabled` field to `true`. This allows you to activate your custom discounts from external services. By default, this setting is determined by the cart settings configured for the store. - Enable or disable the use of rule promotions within the cart. You can apply this setting either at the store level using the update cart setting endpoint or individually to a specific cart using the [update a cart](/docs/api/carts/update-a-cart) endpoint. - Enable or disable deferred inventory checks by setting `defer_inventory_check` to `true`. When set, stock levels are not verified for products in a cart until checkout. - Control whether admins can see all carts or only shopper-associated carts by setting `show_all_carts` to `true` or `false`. - Enable or disable location-based item separation by setting `separate_items_by_location` to `true`. When enabled, cart items with the same SKU but different locations are kept as separate line items instead of being merged. :::note You cannot use both custom discounts and rule promotions at the same time. ::: ### Errors The following error is received if you enable a cart to use both custom discounts and rule promotions: ```json { "status": 422, "title": "Cannot use both discounts together", "detail": "Only one discount setting can be set to true at a time." } ``` operationId: put-v2-settings-cart-storeID requestBody: content: application/json: schema: $ref: '#/components/schemas/SettingsCart' responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/SettingsCart' '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/Response.ErrorResponse' deprecated: false components: securitySchemes: bearerAuth: type: http scheme: bearer schemas: CartContact: title: CartContact type: object properties: email: description: The email address attached to a cart. type: string format: email examples: - tester@email.com DiscountSettings: title: DiscountSettings type: object properties: custom_discounts_enabled: description: This parameter enables custom discounts for a cart. When set to true, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See [Cart Settings](/docs/api/carts/put-v-2-settings-cart). type: boolean examples: - false use_rule_promotions: description: When set to true, this parameter allows the cart to use rule promotions. type: boolean examples: - false InventorySettings: title: InventorySettings type: object properties: defer_inventory_check: description: This parameter enables deferring inventory checks on the cart. This allows items to be added to or updating in the cart without checking stock levels. Inventory checks are still performed as normal on checkout type: boolean examples: - false ItemSettings: title: ItemSettings type: object properties: separate_items_by_location: description: When set to true, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When false (default), items with the same SKU are merged and the location is updated to the most recent value. type: boolean examples: - false 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. Example: ``` "custom_attributes": { "is_member": { "type": "boolean", "value": true }, "membership_level": { "type": "string", "value": "premium" } } ``` 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 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 CartTimestamps: type: object properties: created_at: description: The date this was created. type: string updated_at: description: The date this was last updated. type: string expires_at: description: The date this expires. 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' 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' CartResponse: title: CartResponse allOf: - $ref: '#/components/schemas/BaseCartResponse' - type: object properties: type: description: The type of object being returned. type: string const: cart 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 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 Response.PaginationResults: type: object properties: total: description: The total page count. type: integer Response.Meta.Carts: type: object properties: page: $ref: '#/components/schemas/Response.PaginationPage' results: $ref: '#/components/schemas/Response.PaginationResults' 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 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 Response.ErrorResponse: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Response.ErrorItem' 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. Attribute types include: - string - boolean - integer - float Multiple custom attributes may be submitted together. A cart can have a maximum of 20 custom attributes. Example: ``` "custom_attributes": { "is_member": { "type": "boolean", "value": true }, "membership_level": { "type": "string", "value": "premium" } } ``` Updating 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. $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: - '' 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 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' CartEntityResponse: type: object properties: data: $ref: '#/components/schemas/CartResponse' included: type: object description: Related objects that are included in the response. properties: custom_discounts: type: array items: $ref: '#/components/schemas/CustomDiscountResponse' promotions: type: array items: $ref: '#/components/schemas/CondensedPromotionResponse' meta: type: object description: Additional metadata for the cart response. properties: payment_intent: type: object description: Payment intent details with nested structure including status and other Stripe payment intent fields additionalProperties: true errors: type: array description: Array of error objects, if any errors occurred. items: $ref: '#/components/schemas/Response.ErrorItem' ItemPriceData: title: Order Price Data type: object properties: amount: description: The amount for this item as an integer. type: number readOnly: true examples: - 10000 currency: description: The currency this item was added to the cart as. type: string readOnly: true examples: - USD includes_tax: description: Whether or not this price is tax inclusive. type: boolean readOnly: true examples: - false Money: type: object properties: amount: type: integer description: Amount in minor currency units (e.g., cents). currency: type: string description: ISO 4217 currency code (e.g., "USD"). includes_tax: type: boolean description: Whether the amount includes tax. required: - amount - currency - includes_tax Discount: type: object properties: amount: $ref: '#/components/schemas/Money' code: type: string description: The discount code used, if applicable. id: type: string description: Unique identifier for the discount. promotion_source: type: string description: The source or origin of the promotion, if applicable. is_cart_discount: type: boolean description: Indicates whether the discount applies to the entire cart. ordinal: type: integer description: Order in which the discount was applied. required: - amount - id CartItemFormattedPriceData: title: CartItemFormattedPriceData type: object properties: unit: type: object allOf: - $ref: '#/components/schemas/FormattedPriceData' description: The amount per each single unit. value: type: object allOf: - $ref: '#/components/schemas/FormattedPriceData' description: The total amount of the item (i.e., unit * quantity). Timestamps: type: object properties: created_at: description: The date this was created. type: string updated_at: description: The date this was last updated. type: string CartItemResponse: title: Cart Item Response type: object properties: id: description: The unique identifier for the cart item. type: string format: uuid readOnly: true examples: - 4649fbb3-b8ee-4883-82c9-49a3d5fbacf1 type: description: The type of cart item. type: string readOnly: true enum: - cart_item - custom_item - subscription_item - promotion_item examples: - cart_item product_id: description: The unique ID of the product (for cart_item type). type: string format: uuid readOnly: true examples: - 55cda543-f9d7-42a4-b40a-665f2e4ff7c5 promotion_id: description: The unique ID of the promotion (for promotion_item type). type: string format: uuid readOnly: true examples: - 9993387e-93ab-468f-bba9-cf13882dc52d subscription_offering_id: description: The unique ID of the subscription offering for subscription items. type: string format: uuid readOnly: true examples: - 9c13669e-29d7-42ea-bc95-1b32399adb9d name: description: The name of this item type: string readOnly: true examples: - shirt description: description: A description of the cart item. type: string readOnly: true examples: - T-shirt. sku: description: The SKU of the cart item. type: string readOnly: true examples: - sample-sku slug: description: The slug of the cart item. type: string readOnly: true examples: - sample-product catalog_id: description: The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set. type: string readOnly: true format: uuid examples: - 11d3f9d2-c99b-472c-96c3-51842333daea catalog_source: description: The catalog source. Always `pim` or `legacy`. type: string readOnly: true examples: - pim bundle_configuration: description: Configuration for bundle products. type: object readOnly: true properties: selected_options: type: object additionalProperties: type: object additionalProperties: type: number component_products: description: Array of component products for bundle configuration type: array items: type: object properties: id: description: Product ID type: string type: description: Product type type: string attributes: description: Product attributes as a generic object type: object additionalProperties: true meta: description: Product meta information as a generic object type: object additionalProperties: true price: description: Product price type: object additionalProperties: true relationships: description: Product relationships as a generic object type: object additionalProperties: true components: description: Components of the cart item for bundle products. type: object readOnly: true additionalProperties: type: object properties: name: type: string options: type: array items: type: object properties: id: type: string quantity: type: number type: type: string image: type: object readOnly: true properties: mime_type: description: The MIME type for the uploaded file. type: string readOnly: true examples: - image/png file_name: description: The name of the image file that was uploaded. type: string readOnly: true examples: - shirt-trans.png href: description: The link to the image. type: string readOnly: true examples: - https://files-eu.epusercontent.com/e8c53cb0-120d-4ea5-8941-ce74dec06038/7cc08cbb-256e-4271-9b01-d03a9fac9f0a.png quantity: description: The quantity of the cart item. type: integer readOnly: true examples: - 1 auto_add_quantity: description: The quantity automatically added (for gift items). type: integer readOnly: true manage_stock: description: Whether or not the quantity of the item will be checked against inventory. type: boolean readOnly: true examples: - true unit_price: description: The unit price of the item. readOnly: true $ref: '#/components/schemas/ItemPriceData' value: description: The total price of the item (i.e., unit * quantity). readOnly: true $ref: '#/components/schemas/ItemPriceData' discounts: description: Array of discounts applied to the cart item. type: array readOnly: true items: $ref: '#/components/schemas/Discount' custom_inputs: description: Custom inputs for personalized products. type: object readOnly: true additionalProperties: true examples: - tshirt_front: John Doe tshirt_back: My Custom Text subscription_configuration: description: Configuration for subscription items. type: object readOnly: true properties: plan: description: The subscription plan ID. type: string pricing_option: description: The subscription pricing option ID. type: string links: type: object readOnly: true properties: product: description: A URL related to the resource. type: string examples: - https://useast.api.elasticpath.com/products/9eda5ba0-4f4a-4074-8547-ccb05d1b5981 subscription_offering: description: A URL related to the subscription offering resource. type: string meta: type: object readOnly: true properties: display_price: type: object properties: with_tax: description: The amount of this item after discounts and taxes are applied. $ref: '#/components/schemas/CartItemFormattedPriceData' without_tax: description: The amount of this item after discounts are applied and before taxes. $ref: '#/components/schemas/CartItemFormattedPriceData' tax: description: The amount of taxes applied to this item. $ref: '#/components/schemas/CartItemFormattedPriceData' discount: description: The amount of the discount applied to this item. $ref: '#/components/schemas/CartItemFormattedPriceData' without_discount: $ref: '#/components/schemas/CartItemFormattedPriceData' 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/CartItemFormattedPriceData' discounts: description: Detailed discount information. type: object additionalProperties: type: object required: - amount - currency - formatted properties: amount: description: The discount amount. type: integer examples: - 100 currency: description: The currency code. type: string examples: - USD formatted: description: The formatted discount amount. type: string examples: - $1.00 constituents: description: The discount constituents. type: object additionalProperties: $ref: '#/components/schemas/FormattedPriceData' timestamps: $ref: '#/components/schemas/Timestamps' relationships: description: Relationships to other resources. readOnly: true type: object properties: taxes: description: Related tax items. type: object properties: data: oneOf: - type: 'null' - type: array items: $ref: '#/components/schemas/RelationshipItem' custom_discounts: description: Related custom discounts. 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' shipping_group_id: description: The shipping group ID for this item. type: string readOnly: true examples: - eb063818-939a-458f-97a4-2601c0c2b445 promotion_source: description: The source of the promotion (for promotion items). type: string readOnly: true enum: - rule-promotion examples: - rule-promotion location: description: The stock location for this item. type: string readOnly: true examples: - warehouse-1 custom_attributes: description: Custom attributes attached to the cart item. readOnly: true $ref: '#/components/schemas/CustomAttributes' TaxItemResponse: title: TaxItemResponse type: object properties: type: description: Specifies the type of the resource. Always `tax_item`. type: string const: tax_item id: description: Specifies the UUID of the tax item. type: string format: uuid readOnly: true examples: - 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9 jurisdiction: description: The jurisdiction for the tax item. type: string examples: - US-CA code: description: The tax code for the tax item. type: string examples: - CA_SALES_TAX name: description: The name of the tax item. type: string examples: - California Sales Tax rate: description: The tax rate as a decimal (e.g., 0.085 for 8.5%). type: number format: float examples: - 0.085 amount: description: The tax amount in the smallest currency unit. type: integer examples: - 850 CartItemCollectionResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/CartItemResponse' included: type: object description: Related objects that are included in the response. properties: custom_discounts: type: array items: $ref: '#/components/schemas/CustomDiscountResponse' promotions: type: array items: type: object properties: automatic: type: boolean description: type: string end: type: string format: date-time id: type: string format: uuid name: type: string promotion_type: type: string promotion_source: type: string description: The source of the promotion start: type: string format: date-time type: type: string const: promotion tax_items: description: Array of tax items included in the response. type: array items: $ref: '#/components/schemas/TaxItemResponse' meta: type: object description: Additional meta information about the cart items collection. 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' authorized: $ref: '#/components/schemas/FormattedPriceData' balance_owing: $ref: '#/components/schemas/FormattedPriceData' paid: $ref: '#/components/schemas/FormattedPriceData' timestamps: $ref: '#/components/schemas/CartTimestamps' messages: type: array description: | Optional array of informational messages that provide feedback about operations performed on the cart items, such as promotions added or discounts applied. This field is only present when there are relevant messages to display. items: type: object properties: source: type: object description: Identifies the cart item that triggered this message properties: type: type: string description: The type of the source item id: type: string description: The unique identifier of the source item code: type: string description: The promotion code (present when source type is promotion) required: - type - id title: type: string description: A short descriptive title for the message description: type: string description: A detailed description of the message required: - title - description 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 auto_add: type: boolean description: Whether this promotion should be automatically added targets: description: Array of promotion targets (alternative structure) type: array items: type: object properties: cart_item_id: type: string description: The cart item ID for this target quantity: type: integer description: The quantity for this target skus: type: array description: Array of SKU codes for this target items: type: string errors: type: array description: Array of error objects, if any errors occurred. items: $ref: '#/components/schemas/Response.ErrorItem' required: - data BulkUpdateCartsItemsCommon: title: Bulk Update Carts Items (Common Properties) type: object properties: id: description: Specifies the ID of the cart item that you want to update in cart. type: string format: uuid quantity: description: Specifies the amount of items to update in the cart. type: integer minimum: 0 type: description: The type of cart item being updated. type: string enum: - cart_item - custom_item custom_inputs: description: Specifies the custom text to be added to a product. See [custom inputs](https://elasticpath.dev/docs/pxm/products/ep-pxm-products-api/update-a-product#using-custom-inputs-attribute). type: object custom_attributes: description: Specifies custom attributes to be added to the cart item. $ref: '#/components/schemas/CustomAttributes' shipping_group_id: description: Specifies the shipping group ID for the cart item. type: string format: uuid BulkUpdateCartsItemsWithQuantity: title: Update Cart Item Quantity allOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsCommon' - type: object required: - quantity - id properties: quantity: {} id: {} BulkUpdateCartsItemsWithShippingGroup: title: Update Cart Item Shipping Group allOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsCommon' - type: object required: - shipping_group_id - id properties: shipping_group_id: {} id: {} BulkUpdateCartsItemsWithCustomInputs: title: Update Cart Item Custom Inputs allOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsCommon' - type: object required: - custom_inputs - id properties: custom_inputs: {} id: {} UpdateAllOrNothingOptionsObject: title: Update All Or Nothing Options Object type: object properties: update_all_or_nothing: description: When set to`true`, if an error occurs for any item, no items are updated in the cart. When set to `false`, valid items are updated in the cart and the items with errors are reported in the response. Default is `true`. type: boolean examples: - false BulkUpdateCartsItems: title: Bulk Update Carts Items type: object properties: data: type: array items: anyOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsWithQuantity' - $ref: '#/components/schemas/BulkUpdateCartsItemsWithShippingGroup' - $ref: '#/components/schemas/BulkUpdateCartsItemsWithCustomInputs' options: $ref: '#/components/schemas/UpdateAllOrNothingOptionsObject' BaseItemObjectData: title: Base Item Object Data type: object required: - quantity properties: quantity: description: The number of items to add. type: number examples: - 2 id: type: string format: uuid description: Specifies the ID of the product you want to add. (use this OR sku) examples: - 78d7b5c2-c852-40ad-87bb-beb161f61f37 sku: type: string description: Specifies the item SKU that you want to add. (use this OR id) examples: - my-item name: type: string description: Optional name for the product item. If not provided, the product name from catalog will be used. examples: - Custom Product Name custom_inputs: description: The custom text to be added to a product. type: object bundle_configuration: description: Object used to describe the bundle options selected. type: object properties: selected_options: description: Specifies selected options. type: object component_products: description: Array of component products for the selected options. type: array shipping_group_id: description: Identifier for a Shipping Group type: string location: description: The slug of a stock location. type: string custom_attributes: $ref: '#/components/schemas/CustomAttributes' CartItemObjectData: title: Cart Item Object Data allOf: - type: object required: - type properties: type: description: The type of object being returned. Must be `cart_item` for cart items. type: string const: cart_item - $ref: '#/components/schemas/BaseItemObjectData' CartItemObjectRequest: title: Cart Item Object Request type: object properties: data: $ref: '#/components/schemas/CartItemObjectData' SubscriptionItemObjectData: title: Subscription Item Object Data type: object required: - id - type - quantity - subscription_configuration properties: type: description: The type of object being returned. type: string const: subscription_item quantity: description: The number of items added to the cart. type: number examples: - 1 id: type: string format: uuid description: Specifies the ID of the subscription offering you want to add to cart. examples: - 4ca958bc-7d69-4e2d-b5d4-c74bd5a6cde6 subscription_configuration: type: object description: Specifies how the subscription offering should be configured. required: - pricing_option - plan properties: pricing_option: type: string format: uuid description: The ID of the pricing option within the offering to use for the subscription. plan: type: string format: uuid description: The ID of the plan within the offering to use for the subscription. deprecated: true SubscriptionItemObject: title: Subscription Item Object type: object properties: data: allOf: - $ref: '#/components/schemas/SubscriptionItemObjectData' - $ref: '#/components/schemas/CartItemResponse' CartMergeObject: title: Cart Merge Object type: object required: - type - cart_id properties: type: description: The type of object being returned. Must be `cart_items`. type: string const: cart_items cart_id: description: The original cart to be merged from. type: string format: uuid examples: - 78d7b5c2-c852-40ad-87bb-beb161f61f37 AddAllOrNothingOptionsObject: title: Add All Or Nothing Options Object type: object properties: add_all_or_nothing: description: When `true`, if an error occurs for any item, no items are added to the cart. When `false`, valid items are added to the cart and the items with errors are reported in the response. Default is `false`. type: boolean examples: - false CartMergeObjectRequest: title: Cart Merge Object Request type: object properties: data: allOf: - $ref: '#/components/schemas/CartMergeObject' description: '' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' CustomItemObjectData: title: Custom Item Object Data type: object required: - type - name - quantity - price properties: type: description: The type of object being returned. Must be `custom_item`. type: string const: custom_item quantity: description: The number of custom items to add to cart. type: number examples: - 2 price: type: object required: - amount properties: amount: description: The unit price of the custom item. type: number examples: - 10000 includes_tax: description: Set to`true` if relevant taxes have been included in the price, `false` if not. Defaults to `true`. type: boolean description: description: A description of the custom item. type: string examples: - My first custom item! sku: type: string description: The `SKU` code to use for the custom item. See [best practices](https://elasticpath.dev/docs/commerce-cloud/carts/cart-items/add-custom-item-to-cart#best-practices) to use the `SKU` code. examples: - my-custom-item name: type: string description: The name of the custom item. examples: - My Custom Item custom_inputs: description: The custom text to be added to a product. type: object shipping_group_id: description: Identifier for a created Cart Shipping Group type: string custom_attributes: $ref: '#/components/schemas/CustomAttributes' CustomItemObject: title: Custom Item Object type: object properties: data: allOf: - $ref: '#/components/schemas/CustomItemObjectData' description: '' ReOrderObject: title: Re Order Object type: object required: - type - order_id properties: type: description: The type of resource being returned. Use `order_items`. type: string const: order_items order_id: description: The unique identifier of the order. type: string format: uuid examples: - 78d7b5c2-c852-40ad-87bb-beb161f61f37 ReOrderObjectRequest: title: Re-Order Object Request type: object properties: data: allOf: - $ref: '#/components/schemas/ReOrderObject' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' PromotionItemObjectData: title: Promotion Item Object Data type: object required: - type - code properties: type: description: Specifies the type of resource, which is `promotion_item`. type: string const: promotion_item code: description: Specifies the promotion code. For more information about codes[].user[], see the [Create Promotion codes](/docs/api/promotions/create-promotion-codes) section. type: string examples: - PROMO_CODE PromotionItemObject: title: Promotion Item Object type: object properties: data: allOf: - $ref: '#/components/schemas/PromotionItemObjectData' BulkAddItemsRequest: title: Bulk Add Items Request type: object properties: data: type: array items: anyOf: - $ref: '#/components/schemas/CartItemObjectData' - $ref: '#/components/schemas/CartMergeObject' - $ref: '#/components/schemas/CustomItemObjectData' - $ref: '#/components/schemas/ReOrderObject' - $ref: '#/components/schemas/PromotionItemObjectData' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' UpdateCartsItems: title: Update Carts Items type: object properties: data: type: object properties: type: description: The type of the cart item. type: string const: cart_item id: description: The unique identifier of the cart item. type: string format: uuid examples: - '{{cartitemID}}' quantity: description: The amount of products to add to cart. type: number examples: - 2 custom_inputs: description: The custom text to be added to a product. type: object custom_attributes: description: Custom attributes to be added to the cart item. $ref: '#/components/schemas/CustomAttributes' shipping_group_id: description: The unique identifier of the shipping group to be added to the cart. type: string format: uuid examples: - 900ab9c1-4b39-43fe-b080-0dc2806065d9 CartsRelationshipsAccountsData: title: Carts Relationships Accounts Data type: object properties: data: type: array items: type: object properties: id: description: The ID of the account. type: string examples: - '{{accountID}}' type: description: The type of related object. Ensure that it is account. type: string examples: - account CartsRelationshipsCustomersData: title: Carts Relationships Customers Data type: object properties: data: type: array items: type: object properties: id: description: The ID of the customer. type: string examples: - '{{customerID}}' type: description: The type of related object. Ensure that it is customer. type: string examples: - customer CartsItemsTaxesCommon: type: object required: - type properties: code: description: A unique tax code in this jurisdiction. type: string jurisdiction: description: The relevant tax jurisdiction. type: string name: description: The name of the tax item. type: string rate: description: | The tax rate as a decimal (12.5% -> 0.125). You must specify either `rate` or `amount`, but not both. type: number amount: description: | The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). You must specify either `rate` or `amount`, but not both. type: number type: description: The type of object being returned. Use `tax_item`. type: string const: tax_item id: description: The unique identifier for this tax item. type: string format: uuid readOnly: true CartsItemsTaxesWithRate: title: Tax Object (With Rate) allOf: - $ref: '#/components/schemas/CartsItemsTaxesCommon' - type: object required: - rate properties: rate: description: | The tax rate as a decimal (12.5% -> 0.125). Required when using rate-based taxation. type: number examples: - 0.2 amount: description: | The tax as an absolute amount. Not allowed when rate is specified. type: number examples: - 1000 not: type: object required: - amount properties: amount: type: number CartsItemsTaxesWithAmount: title: Tax Object (With Amount) allOf: - $ref: '#/components/schemas/CartsItemsTaxesCommon' - type: object required: - amount properties: amount: description: | The tax as an absolute amount in the smallest currency unit (e.g., $10 -> 1000). Required when using amount-based taxation. type: number examples: - 1000 rate: description: | The tax rate as a decimal. Not allowed when amount is specified. type: number examples: - 0.2 not: type: object required: - rate properties: rate: type: number CartsItemsTaxesObject: title: Carts Items Taxes Object description: | A tax item that can be applied to cart items or bundle components. You must specify either a rate (percentage) or an amount (fixed value), but not both. oneOf: - $ref: '#/components/schemas/CartsItemsTaxesWithRate' - $ref: '#/components/schemas/CartsItemsTaxesWithAmount' examples: - type: tax_item code: VAT jurisdiction: UK name: Value Added Tax rate: 0.2 - type: tax_item code: EXCISE jurisdiction: US name: Excise Tax amount: 500 CartItemTaxesEntityResponse: type: object properties: data: type: object $ref: '#/components/schemas/CartsItemsTaxesObject' required: - data CartItemRelationship: title: CartItemRelationship type: object properties: relationships: type: object required: - item properties: item: type: object required: - data properties: data: type: object required: - type - id properties: type: description: Specifies the type of item. For example, `custom_item` or `cart_item`. type: string examples: - cart_item id: description: Specifies the unique identifier of the `cart_item` or `custom_item` in the cart. type: string format: uuid examples: - 5601a4b1-9d13-42d3-8fb7-03b35169d1b6 CartsBulkTaxes: title: CartsBulkTaxes type: object properties: data: type: array items: allOf: - $ref: '#/components/schemas/CartsItemsTaxesObject' - $ref: '#/components/schemas/CartItemRelationship' errors: type: array items: $ref: '#/components/schemas/Response.ErrorItem' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' CartsCustomDiscountsObject: title: CartsCustomDiscountsObject type: object required: - amount - description - discount_code - discount_engine - external_id - type properties: amount: type: object oneOf: - type: number examples: - -1000 - type: object properties: amount: type: number examples: - -1000 currency: type: string examples: - USD formatted: type: string examples: - '-$10.00' 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 discount_engine: description: Specifies from where the custom discount is applied. For example, Talon.one. type: string examples: - Custom Discount Engine external_id: description: Specifies an external id for the custom discount. type: string examples: - custom-discount-external-id 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 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 item ID this discount is related to type: type: string enum: - cart_item - custom_item CustomDiscountRelationshipsCartItemRequest: title: CustomDiscountRelationshipsCartItemRequest type: object properties: relationships: type: object properties: item: type: object properties: data: type: object required: - type - id properties: type: description: Specifies the type of item. For example, `custom_item` or `cart_item`. type: string examples: - cart_item id: description: Specifies the unique identifier of the `cart_item` or `custom_item` in the cart. type: string format: uuid examples: - 5601a4b1-9d13-42d3-8fb7-03b35169d1b6 CartItemBulkCustomDiscountObject: title: CartItemBulkCustomDiscountObject type: object allOf: - $ref: '#/components/schemas/CartsCustomDiscountsObject' - $ref: '#/components/schemas/CustomDiscountRelationshipsCartItemRequest' CartsBulkCustomDiscounts: title: CartsBulkCustomDiscounts type: object properties: data: type: array items: allOf: - $ref: '#/components/schemas/CartsCustomDiscountsObject' - $ref: '#/components/schemas/CartItemBulkCustomDiscountObject' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' CartsBulkCustomDiscountsResponse: title: CartsBulkCustomDiscountsResponse type: object properties: data: type: object $ref: '#/components/schemas/CartsCustomDiscountsObject' errors: type: array description: Array of validation or processing errors items: $ref: '#/components/schemas/Response.ErrorItem' CartsBulkCustomDiscountsCollectionResponse: title: CartsBulkCustomDiscountsCollectionResponse type: object properties: data: type: array items: type: object $ref: '#/components/schemas/CartsCustomDiscountsObject' errors: type: array description: Array of validation or processing errors items: $ref: '#/components/schemas/Response.ErrorItem' CartsCustomDiscountsResponseObject: title: CartsCustomDiscountsResponse type: object properties: amount: type: object properties: amount: description: Specifies an amount to be applied for the custom discount. It must be less than zero. type: number examples: - -1000 currency: description: The currency set for the custom discount. type: string examples: - USD formatted: description: The formatted value for the custom discount. type: string examples: - '-$10.00' 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 discount_engine: description: Specifies from where the custom discount is applied. For example, Talon.one. type: string examples: - Custom Discount Engine external_id: description: Specifies an external id for the custom discount. type: string examples: - custom-discount-external-id 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 readOnly: true examples: - 662461ad-ddcb-4dbd-8ed7-ade9aa63b5f9 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 item ID this discount is related to type: type: string enum: - cart_item - custom_item CartsCustomDiscountsEntityRequest: type: object properties: data: type: object $ref: '#/components/schemas/CartsCustomDiscountsResponseObject' CartsCustomDiscountsEntityResponse: type: object properties: data: type: object $ref: '#/components/schemas/CartsCustomDiscountsObject' CartsCustomDiscountsCollectionResponse: type: object properties: data: type: array items: type: object $ref: '#/components/schemas/CartsCustomDiscountsObject' 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 AddressWithRegion: title: Address with Region allOf: - $ref: '#/components/schemas/AddressCommon' - type: object required: - region properties: region: description: State, province, or region of the address. type: string AddressWithCounty: title: Address with County allOf: - $ref: '#/components/schemas/AddressCommon' - type: object required: - county properties: county: description: County of the address. type: string ShippingAddress: title: ShippingAddress description: | Shipping address information. You must specify at least one of region (state/province) or county. allOf: - anyOf: - $ref: '#/components/schemas/AddressWithRegion' - $ref: '#/components/schemas/AddressWithCounty' - type: object properties: phone_number: description: Phone number of the shipping recipient. type: string instructions: description: Delivery instructions. type: string examples: - first_name: John last_name: Doe line_1: 1 Sunny Street line_2: Apartment 123 city: Los Angeles postcode: '92802' region: CA country: US instructions: Please leave on porch - first_name: Jane last_name: Smith line_1: 123 Main Street city: London postcode: SW1A 1AA county: Greater London country: GB phone_number: +44 20 7946 0958 DeliveryEstimate: type: object properties: start: type: string format: date-time end: type: string format: date-time SingleRelationship: title: SingleRelationship description: Single relationship type: object properties: data: $ref: '#/components/schemas/RelationshipItem' Discounts: type: array items: $ref: '#/components/schemas/Discount' ShippingPriceResponse: type: object properties: total: $ref: '#/components/schemas/FormattedPriceData' base: $ref: '#/components/schemas/FormattedPriceData' tax: $ref: '#/components/schemas/FormattedPriceData' fees: $ref: '#/components/schemas/FormattedPriceData' discount: $ref: '#/components/schemas/FormattedPriceData' required: - total - base NonNegativeFormattedPriceData: title: NonNegativeFormattedPriceData type: object properties: amount: description: The raw total. Must be non-negative. type: number minimum: 0 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 DiscountFormattedPriceData: title: DiscountFormattedPriceData type: object properties: amount: description: The discount amount. Must be non-positive (zero or negative). type: number maximum: 0 examples: - -1000 - 0 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' - $0.00 OrderPriceWrapperMeta: description: Order pricing information. 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' required: - with_tax - without_tax - tax - discount - balance_owing - paid - authorized - without_discount - shipping - shipping_discount ShippingGroupMeta: type: object properties: shipping_display_price: $ref: '#/components/schemas/ShippingPriceResponse' total_display_price: $ref: '#/components/schemas/OrderPriceWrapperMeta' ShippingGroupResponse: title: Shipping Group Response type: object properties: type: type: string const: shipping_group id: type: string relation: type: string cart_id: type: string order_id: type: string shipping_type: type: string tracking_reference: type: string external_ref: description: An optional external ID reference for a shipping group. 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 maxLength: 64 examples: - SG-12345 address: $ref: '#/components/schemas/ShippingAddress' delivery_estimate: $ref: '#/components/schemas/DeliveryEstimate' created_at: type: string format: date-time updated_at: type: string format: date-time relationships: type: object properties: cart: $ref: '#/components/schemas/SingleRelationship' order: $ref: '#/components/schemas/SingleRelationship' discounts: $ref: '#/components/schemas/Discounts' meta: $ref: '#/components/schemas/ShippingGroupMeta' ShippingPriceRequest: type: object properties: total: type: number base: type: number tax: type: number fees: type: number discount: type: number CreateShippingGroupRequest: type: object properties: data: type: object properties: type: type: string const: shipping_group shipping_type: type: string tracking_reference: type: string external_ref: description: An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. type: string maxLength: 64 shipping_price: $ref: '#/components/schemas/ShippingPriceRequest' address: $ref: '#/components/schemas/ShippingAddress' includes_tax: type: boolean delivery_estimate: $ref: '#/components/schemas/DeliveryEstimate' 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 DiscountData: title: DiscountData type: object properties: amount: $ref: '#/components/schemas/OrderPriceData' code: type: string id: type: string format: uuid readOnly: true promotion_source: type: string description: The source or origin of the promotion, if applicable. is_cart_discount: type: boolean description: Indicates whether the discount applies to the entire cart. ordinal: type: integer description: Order in which the discount was applied. OrderItemFormattedUnitPriceData: title: OrderItemFormattedUnitPriceData type: object properties: unit: $ref: '#/components/schemas/FormattedPriceData' value: $ref: '#/components/schemas/FormattedPriceData' 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 products. type: object properties: selected_options: type: object additionalProperties: type: object additionalProperties: type: number component_products: description: Array of component products for bundle configuration type: array items: type: object properties: id: description: Component product ID type: string type: description: Component product type type: string attributes: description: Product attributes as a generic object type: object additionalProperties: true meta: description: Product metadata as a generic object type: object additionalProperties: true price: description: Product price information as a generic object type: object additionalProperties: true relationships: description: Product relationships as a generic object type: object additionalProperties: true components: description: Components of the bundle product. type: object additionalProperties: type: object properties: name: type: string options: type: array items: type: object properties: id: type: string quantity: type: number type: type: string custom_inputs: description: Custom inputs for the order item as a generic object type: object additionalProperties: true custom_attributes: description: Custom attributes attached to the order item. readOnly: true $ref: '#/components/schemas/CustomAttributes' shipping_group_id: description: The shipping group ID for the order item type: string promotion_source: description: The promotion source for the order item type: string subscription_configuration: description: Subscription configuration for the order item type: object properties: plan: description: Subscription plan details type: string pricing_option: description: Pricing option for the subscription type: string ShippingGroupEntityResponse: type: object properties: data: type: object $ref: '#/components/schemas/ShippingGroupResponse' included: type: object description: Related objects that are included in the response when using the include query parameter. properties: items: description: Array of order items associated with this shipping group. type: array items: $ref: '#/components/schemas/OrderItemResponse' additionalProperties: false errors: type: array description: Array of validation or processing errors items: $ref: '#/components/schemas/Response.ErrorItem' UpdateCartShippingGroupRequest: type: object properties: data: type: object properties: type: type: string const: shipping_group shipping_type: type: string tracking_reference: type: string external_ref: description: An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. type: string maxLength: 64 shipping_price: $ref: '#/components/schemas/ShippingPriceRequest' address: $ref: '#/components/schemas/ShippingAddress' includes_tax: type: boolean delivery_estimate: $ref: '#/components/schemas/DeliveryEstimate' Data.BasePayments: title: Data.BasePayments type: object required: - gateway - method properties: gateway: type: string enum: - adyen - authorize_net - braintree - card_connect - cyber_source - elastic_path_payments_stripe - manual - paypal_express_checkout - stripe - stripe_payment_intents method: description: Specifies the transaction method, such as `purchase` or `authorize`. type: string enum: - authorize - purchase - purchase_setup - authorize_setup amount: description: The amount to be paid for the transaction. type: number examples: - 10000 ElasticPathPaymentsPoweredByStripePayment: title: Elastic Path Payments Powered By Stripe type: object properties: data: allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `elastic_path_payments_stripe`. type: string const: elastic_path_payments_stripe options: type: object properties: receipt_email: description: Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode. type: string automatic_payment_methods: type: object description: Parent object determining whether to use Stripe's `automatic_payment_methods` setting. properties: enabled: type: boolean description: When set to true, it displays all enabled payment methods from the Stripe dashboard. When set to false, the Stripe default, which is card, is used. payment_method_types: type: array items: type: string description: Specifies the Stripe payment method types configured for the store. See [Stripe Documentation](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-payment_method_types). examples: - - card payment: description: Specifies the Stripe token or source. type: string CartPaymentUpdate: title: Cart Payment Update type: object required: - data properties: data: type: object required: - gateway - method - payment_method_types - amount properties: gateway: type: string method: type: string payment_method_types: type: array items: type: string amount: type: integer options: type: object BillingAddress: title: BillingAddress description: | Billing address information. You must specify at least one of region (state/province) or county. anyOf: - $ref: '#/components/schemas/AddressWithRegion' - $ref: '#/components/schemas/AddressWithCounty' examples: - first_name: John last_name: Doe company_name: John Doe Enterprises line_1: 1 Sunny Street line_2: Apartment 123 city: Los Angeles postcode: '92802' region: CA country: US - first_name: Jane last_name: Smith line_1: 123 Main Street city: London postcode: SW1A 1AA county: Greater London country: GB CustomerCheckout: title: Customer Checkout type: object properties: data: type: object properties: order_number: description: 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 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 customer: type: object properties: id: description: The ID of the customer. type: string email: description: The email of the customer. type: string name: description: The name of the customer. type: string billing_address: $ref: '#/components/schemas/BillingAddress' shipping_address: $ref: '#/components/schemas/ShippingAddress' AccountCheckout: title: Account Checkout type: object properties: data: type: object properties: order_number: description: 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 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 account: type: object properties: id: description: The account ID. type: string member_id: description: The account member ID. type: string contact: type: object properties: name: description: The name of the account member. type: string email: description: The email address of the account member. type: string format: email billing_address: $ref: '#/components/schemas/BillingAddress' shipping_address: $ref: '#/components/schemas/ShippingAddress' OrderTimestamps: type: object properties: created_at: description: The date this order was created. type: string updated_at: description: The date this order was last updated. type: string fully_paid_at: description: The date this order was fully paid. Only present for orders with payment status 'paid'. type: string 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 Contact: title: Contact type: object properties: email: description: The email address of the contact. type: string examples: - johndoe@email.com name: description: The name of the contact. type: string examples: - John Doe Customer: title: Customer type: object properties: name: description: The name of the customer. type: string examples: - John Doe email: description: The email address of the customer. type: string format: email examples: - john.doe@example.com id: description: The unique identifier of the customer. type: string format: uuid examples: - e5a0d684-a4af-4919-a348-f66b0b4955e0 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' 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' Response.Meta.Orders: type: object properties: page: $ref: '#/components/schemas/Response.PaginationPage' results: $ref: '#/components/schemas/Response.PaginationResults' OrderCollectionResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/OrderResponse' links: $ref: '#/components/schemas/Response.PageLinks' meta: $ref: '#/components/schemas/Response.Meta.Orders' OrdersAddressData: title: OrdersAddressData type: object required: - type - shipping_address properties: type: description: The type of the resource. You must use "order". type: string examples: - 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: Represents 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: - external_order_123 shipping_address: type: object properties: first_name: description: Specifies the first name of the address holder. type: string examples: - James last_name: description: Specifies the last name of the address holder. type: string examples: - Doe phone_number: description: Specifies the phone number of the address holder. type: string examples: - 5558679305 company_name: description: Specifies the company name. type: string examples: - company name line_1: description: Specifies the first line of the address. type: string examples: - 1234 Disney Drive line_2: description: Specifies the second line of the address. type: string examples: - Disney Resort city: description: Specifies the name of the city in the shipping address. type: string examples: - Anaheim county: description: Specifies the county of the shipping address. type: string examples: - Orange region: description: Specifies the state, province, or region of the shipping address. type: string examples: - CA postcode: description: Specifies the postcode or ZIP code of the address. type: string examples: - 92802 country: description: Specifies the country in the shipping address. type: string examples: - US instructions: description: Specifies any instructions provided with the shipping address. type: string examples: - Buzzer 10233 OrdersCancelData: title: OrdersCancelData type: object required: - type - status properties: status: description: The status of the order. You can only update the status to `cancelled`. type: string examples: - cancelled type: description: The type of the resource. You must use order. type: string examples: - order external_ref: description: Represents 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: - external_order_123 OrdersFulfilledData: title: OrdersFulfilledData type: object required: - type - shipping properties: shipping: description: The shipping status of the order. You can only update the shipping status to `fulfilled`. type: string examples: - fulfilled type: description: The type of the resource. You must use order. type: string examples: - order external_ref: description: Represents 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: - external_order_123 OrdersUpdateRequest: title: OrdersUpdateRequest type: object properties: data: oneOf: - $ref: '#/components/schemas/OrdersAddressData' - $ref: '#/components/schemas/OrdersCancelData' - $ref: '#/components/schemas/OrdersFulfilledData' OrderItemCollectionResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/OrderItemResponse' included: description: | Optional included data such as tax items, custom discounts, and promotions. type: object properties: 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' OrdersAnonymizeData: title: OrdersAnonymizeData type: object properties: order_ids: description: The unique identifiers of the orders to be anonymized. You can anonymize multiple orders at the same time. type: array items: type: string examples: - - '{{orderID}}' OrdersAnonymizeRequest: title: OrdersAnonymizeRequest type: object properties: data: $ref: '#/components/schemas/OrdersAnonymizeData' OrdersListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/OrderResponse' required: - data FailureDetails: title: FailureDetails description: Non-PII payment failure information from the payment gateway. Only present on failed transactions where the gateway provided structured failure details. type: object properties: code: description: Machine-readable failure or error code from the payment gateway. type: string examples: - '2' reason: description: Human-readable failure reason or error message from the payment gateway. type: string examples: - This transaction has been declined. TransactionResponse: title: TransactionResponse type: object properties: id: description: The ID of the transaction. type: string format: uuid readOnly: true reference: description: The payment gateway reference. type: string examples: - manual name: description: A custom name associated with the payment method. type: string examples: - payment method name custom_reference: description: A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend you not to include personal information in this field. type: string examples: - custom reference gateway: description: The name of the payment gateway used. type: string enum: - adyen - authorize_net - braintree - card_connect - cyber_source - elastic_path_payments_stripe - manual - paypal_express_checkout - stripe - stripe_payment_intents - stripe_platform_account amount: description: The amount for this transaction. type: number examples: - 10000 refunded_amount: description: The refunded amount. type: number examples: - 0 currency: description: The transaction currency. type: string examples: - USD transaction_type: description: The type of transaction, such as `purchase`, `capture`, `authorize` or `refund`. type: string enum: - purchase - authorize - capture - refund type: description: The type of object being returned. type: string status: description: The status provided by the gateway for this transaction, such as `complete` or `failed`. type: string examples: - complete payment_details: description: Payment gateway specific details. type: object properties: detailed_status: description: Detailed status from the payment gateway. type: string failure_details: description: Non-PII payment failure details from the gateway. Only present on failed transactions where the gateway provided structured failure information. $ref: '#/components/schemas/FailureDetails' payment_intent: description: Payment intent details. type: object additionalProperties: true capture_mechanism: description: The mechanism used for capturing the transaction. type: string enum: - automatic - manual refund_mechanism: description: The mechanism used for refunding the transaction. type: string enum: - automatic - manual client_parameters: description: Client-specific parameters for payment processing. type: object properties: redirect_url: description: URL to redirect the client after payment. type: string secret: description: Client secret for payment processing. type: string token: description: Client token for payment processing. type: string next_actions: description: Array of next actions for the transaction. type: array items: type: string relationships: type: object properties: order: type: object properties: data: type: object properties: type: description: Represents the type of the object being returned. It is always `order`. type: string examples: - order id: description: The ID of the order. type: string format: uuid examples: - 5601a4b1-9d13-42d3-8fb7-03b35169d1b6 meta: type: object properties: display_price: $ref: '#/components/schemas/FormattedPriceData' display_refunded_amount: type: object properties: total: $ref: '#/components/schemas/FormattedPriceData' timestamps: $ref: '#/components/schemas/Timestamps' TransactionEntityResponse: type: object properties: data: type: object $ref: '#/components/schemas/TransactionResponse' required: - data Data.AdyenPayment: title: Data.AdyenPayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `adyen`. type: string const: adyen options: type: object properties: shopper_reference: description: The shopper reference token associated with the saved payment method. type: string recurring_processing_model: description: Enter CardOnFile for a one-time purchase. type: string payment: description: The Adyen recurringDetailReference payment method identifier. type: string Data.AuthorizeNetPayment: title: Data.AuthorizeNetPayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `authorize_net`. type: string const: authorize_net options: type: object properties: customer_payment_profile_id: description: The Authorize.net customer payment profile ID. type: string payment: description: The Authorize.net customer profile ID. type: string Data.BraintreePayment: title: Data.BraintreePayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `braintree`. type: string const: braintree payment: description: The Braintree Customer ID that you want to bill. type: string Data.CardConnectPayment: title: Data.CardConnectPayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `card_connect`. type: string const: card_connect payment: description: Enter account_id, profile_id from CardPointe API. For example, 1|16178397535388255208. type: string Data.CyberSourcePayment: title: Data.CyberSourcePayment required: - payment - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the gateway. You must use `cyber_source`. type: string const: cyber_source payment: description: The CyberSource token. type: string Data.ManualPayment: title: Data.ManualPayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `manual`. type: string const: manual paymentmethod_meta: type: object properties: custom_reference: description: A reference associated with the payment method. This might include loyalty points or gift card identifiers. We recommend not to include personal information in this field. type: string name: description: A custom name associated with the payment method. type: string Data.PayPalExpressCheckoutPayment: title: Data.PayPalExpressCheckoutPayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `paypal_express_checkout`. type: string const: paypal_express_checkout options: type: object properties: description: description: The description for the payment. type: string soft_descriptor: description: The descriptor appended to PayPal generated descriptor that is visible on the card statement of the payer. type: string application_context: type: object properties: brand_name: description: The label that overrides the business name in the PayPal account on the PayPal site. type: string locale: description: The locale pages that appear based on language and country code. PayPal supports a five-character code. For example, ja-JP. type: string landing_page: description: The type of landing page to show on the PayPal site for customer checkout. Use values LOGIN, BILLING, or NO_PREFERENCE. type: string shipping_preference: description: The shipping preference. Use SET_PROVIDED_ADDRESS value. This parameter does allow the user to change their address on PayPal site. type: string user_action: description: If you set `useraction=commit` in the query string, the flow redirects the buyer to the PayPal payment page and displays a Pay Now button. When the shopper clicks **Pay Now**, call `DoExpressCheckoutPayment` to complete the payment without additional interaction from the shopper. Choose this flow when you know the final payment amount when you initiate the checkout flow. type: string return_url: description: The callback URL for PayPal to redirect the user in the case of approved payment. type: string cancel_url: description: The callback URL for PayPal to redirect user in the case a cancelled payment. type: string Data.StripePayment: title: Data.StripePayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `stripe`. type: string const: stripe options: type: object properties: receipt_email: description: The option to provide an email for Stripe receipts. Specify live mode to access this feature. type: string payment: description: The Stripe token or source. type: string Data.StripePaymentIntentsPayment: title: Data.StripePaymentIntentsPayment required: - gateway allOf: - $ref: '#/components/schemas/Data.BasePayments' - type: object properties: gateway: description: Specifies the type of payment gateway. You must use `stripe_payment_intents`. type: string const: stripe_payment_intents options: type: object properties: receipt_email: description: Provides the email address to which you want to send the Stripe receipts for the transactions within the store. This feature is available only in the live mode. type: string payment: description: Specifies the Stripe token or source. type: string Data.PaymentObject: oneOf: - $ref: '#/components/schemas/Data.AdyenPayment' - $ref: '#/components/schemas/Data.AuthorizeNetPayment' - $ref: '#/components/schemas/Data.BraintreePayment' - $ref: '#/components/schemas/Data.CardConnectPayment' - $ref: '#/components/schemas/Data.CyberSourcePayment' - $ref: '#/components/schemas/ElasticPathPaymentsPoweredByStripePayment' - $ref: '#/components/schemas/Data.ManualPayment' - $ref: '#/components/schemas/Data.PayPalExpressCheckoutPayment' - $ref: '#/components/schemas/Data.StripePayment' - $ref: '#/components/schemas/Data.StripePaymentIntentsPayment' PaymentsRequest: title: PaymentsRequest type: object properties: data: $ref: '#/components/schemas/Data.PaymentObject' OrdersTransactionsConfirmRequest: title: OrdersTransactionsConfirmRequest type: object properties: data: type: object OrdersTransactionsCaptureRequest: title: OrdersTransactionsCaptureRequest type: object properties: data: type: object properties: options: type: object properties: soft_descriptor: type: string note_to_payer: type: string OrdersTransactionsRefundRequest: title: OrdersTransactionsRefundRequest type: object properties: data: type: object properties: amount: description: The amount value to be refunded. If this field is not provided, it will be considered as manual refund (Mark as Refunded) and the refund process must be manually handled via payment provider. If the amount value is same as payment value, then it will be treated as a full refund and sent to the payment provider to process refund automatically. type: number examples: - 1000 options: type: object properties: note: description: Provides comments about the refund. It is used by PayPal Express. type: string TransactionListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/TransactionResponse' required: - data Response.Data: type: object properties: data: {} OrdersTransactionsCancelRequest: title: OrdersTransactionsCancelRequest type: object properties: data: type: object properties: options: type: object reason: description: Specifies the reason for canceling the transaction. The reason may include `duplicate`, `fraudulent`, `requested_by_customer`, or `abandoned`. type: string examples: - requested_by_customer UpdateOrderShippingGroupRequest: type: object properties: data: type: object properties: type: type: string const: shipping_group shipping_type: type: string tracking_reference: type: string external_ref: description: An optional external ID reference for a shipping group. It can contain alphanumeric characters, special characters, and spaces, and is not required to be unique. The maximum allowed length is 64 characters. type: string maxLength: 64 address: $ref: '#/components/schemas/ShippingAddress' delivery_estimate: $ref: '#/components/schemas/DeliveryEstimate' SettingsCart: type: object properties: data: type: object properties: type: type: string description: Describes the type of request payload you're sending. Set this value to `settings`. example: settings id: type: string description: The unique identifier for the cart settings. readOnly: true example: 15419118-44ce-5343-8ff6-574daf52bc6b cart_expiry_days: type: integer description: Indicates the number of days before a cart expires. example: 25 discounts: type: object properties: custom_discounts_enabled: description: When `true`, custom discounts are enabled. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected. type: boolean example: false use_rule_promotions: description: When set to `true`, this parameter allows the cart to use rule promotions. type: boolean example: false inventories: type: object properties: defer_inventory_check: description: When `true`, inventory checks are not performed when adding products to a cart but still occur on checkout as normal. Default is false. This setting only affects the new empty carts while the existing active carts will not be affected. type: boolean example: false items: type: object properties: separate_items_by_location: description: When `true`, cart items with the same SKU but different locations are kept as separate line items instead of being merged. When `false` (default), items with the same SKU are merged and the location is updated to the most recent value. type: boolean example: false show_all_carts: description: | When `true`, admins (users with admin scope) can retrieve all carts in the store via `GET /v2/carts`, regardless of customer or account associations. When `false`, admins can only see carts that are registered (associated with customers or accounts). For new stores, this defaults to `true`. For existing stores created before this feature was introduced, this defaults to `false` to maintain backward compatibility. type: boolean example: true required: - type