openapi: 3.1.0 info: version: 25.1126.6886238 x-version-timestamp: 2025-11-26 19:10:23+00:00 title: Addresses Introduction Account Addresses Cart Items API description: 'The Addresses API allows you to organize account addresses. Addresses are a sub-resource of `account` resources, an account can have multiple addresses, such as home, work, and neighbour. You can use an account address with either [client_credentials access token](/docs/api/authentication/create-an-access-token) or a combination of [implicit access token](/docs/api/authentication/create-an-access-token) and [Account Management authentication](/docs/api/accounts/post-v-2-account-members-tokens) token. ' contact: name: Elastic Path url: https://www.elasticpath.com email: support@elasticpath.com license: url: https://elasticpath.dev name: MIT servers: - url: https://useast.api.elasticpath.com description: US East - url: https://euwest.api.elasticpath.com description: EU West security: - BearerToken: [] tags: - name: Cart Items description: Products added to a cart are referred to as a `cart_item`. paths: /v2/carts/{cartID}/items: parameters: [] get: tags: - Cart Items summary: Get Cart Items description: "\nUse this endpoint to retrieve cart items. If the cart is associated with shipping groups, calling this endpoint displays the associated shipping group IDs.\n\nYou 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.\n\n```json\n\"data\": [\n{\n \"id\": \"98de010d-dd10-4fa5-a070-0b9bcdc72974\",\n \"type\": \"cart_item\",\n \"product_id\": \"5a4662d2-9a2b-4f6e-a215-2970db914b0c\",\n \"name\": \"sku1\",\n \"description\": \"sku1\",\n \"sku\": \"sku1\",\n \"slug\": \"sku1\",\n \"image\": {\n \"mime_type\": \"\",\n \"file_name\": \"\",\n \"href\": \"\"\n },\n \"quantity\": 1,\n \"manage_stock\": false,\n \"unit_price\": {\n \"amount\": 10000,\n \"currency\": \"USD\",\n \"includes_tax\": false\n },\n \"value\": {\n \"amount\": 10000,\n \"currency\": \"USD\",\n \"includes_tax\": false\n },\n \"discounts\": [\n {\n \"amount\": {\n \"amount\": -2000,\n \"currency\": \"USD\",\n \"includes_tax\": false\n },\n \"code\": \"sale2024\",\n \"id\": \"e4d929d5-f471-4317-9a86-a84a6c572b44\",\n \"promotion_source\": \"rule-promotion\",\n \"is_cart_discount\": true\n },\n {\n \"amount\": {\n \"amount\": -1000,\n \"currency\": \"USD\",\n \"includes_tax\": false\n },\n \"code\": \"sale2024\",\n \"id\": \"de19a043-a6da-4bde-b896-d17e16b77e25\",\n \"promotion_source\": \"rule-promotion\"\n },\n {\n \"amount\": {\n \"amount\": -1000,\n \"currency\": \"USD\",\n \"includes_tax\": false\n },\n \"code\": \"sale2024\",\n \"id\": \"509295ee-2971-45b6-801e-95df09756989\"\n },\n {\n \"amount\": {\n \"amount\": -1000,\n \"currency\": \"USD\",\n \"includes_tax\": false\n },\n \"code\": \"sale2024\",\n \"id\": \"ca79e606-7ecd-41ac-9478-af4c8c28c546\",\n \"promotion_source\": \"rule-promotion\",\n \"is_cart_discount\": true\n }\n ],\n \"links\": {\n \"product\": \"https://useast.api.elasticpath.com/v2/products/5a4662d2-9a2b-4f6e-a215-2970db914b0c\"\n },\n \"meta\": {\n \"display_price\": {\n \"with_tax\": {\n \"unit\": {\n \"amount\": 5000,\n \"currency\": \"USD\",\n \"formatted\": \"$50.00\"\n },\n \"value\": {\n \"amount\": 5000,\n \"currency\": \"USD\",\n \"formatted\": \"$50.00\"\n }\n },\n \"without_tax\": {\n \"unit\": {\n \"amount\": 5000,\n \"currency\": \"USD\",\n \"formatted\": \"$50.00\"\n },\n \"value\": {\n \"amount\": 5000,\n \"currency\": \"USD\",\n \"formatted\": \"$50.00\"\n }\n },\n \"tax\": {\n \"unit\": {\n \"amount\": 0,\n \"currency\": \"USD\",\n \"formatted\": \"$0.00\"\n },\n \"value\": {\n \"amount\": 0,\n \"currency\": \"USD\",\n \"formatted\": \"$0.00\"\n }\n },\n \"discount\": {\n \"unit\": {\n \"amount\": -5000,\n \"currency\": \"USD\",\n \"formatted\": \"-$50.00\"\n },\n \"value\": {\n \"amount\": -5000,\n \"currency\": \"USD\",\n \"formatted\": \"-$50.00\"\n }\n },\n \"without_discount\": {\n \"unit\": {\n \"amount\": 10000,\n \"currency\": \"USD\",\n \"formatted\": \"$100.00\"\n },\n \"value\": {\n \"amount\": 10000,\n \"currency\": \"USD\",\n \"formatted\": \"$100.00\"\n }\n },\n \"discounts\": {\n \"sale2024\": {\n \"amount\": -5000,\n \"currency\": \"USD\",\n \"formatted\": \"-$50.00\",\n \"constituents\": {\n \"509295ee-2971-45b6-801e-95df09756989\": {\n \"amount\": -1000,\n \"currency\": \"USD\",\n \"formatted\": \"-$10.00\"\n },\n \"ca79e606-7ecd-41ac-9478-af4c8c28c546\": {\n \"amount\": -1000,\n \"currency\": \"USD\",\n \"formatted\": \"-$10.00\"\n },\n \"de19a043-a6da-4bde-b896-d17e16b77e25\": {\n \"amount\": -1000,\n \"currency\": \"USD\",\n \"formatted\": \"-$10.00\"\n },\n \"e4d929d5-f471-4317-9a86-a84a6c572b44\": {\n \"amount\": -2000,\n \"currency\": \"USD\",\n \"formatted\": \"-$20.00\"\n }\n }\n }\n }\n },\n \"timestamps\": {\n \"created_at\": \"2024-05-24T18:00:58Z\",\n \"updated_at\": \"2024-05-24T18:00:58Z\"\n }\n },\n \"catalog_id\": \"09b9359f-897f-407f-89a2-702e167fe781\",\n \"catalog_source\": \"pim\"\n}\n```\n" 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: "\n### Add Product to Cart\n\nAdding 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.\n\n#### Dynamic Bundles\n\nA 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).\n\nYour dynamic bundles are displayed in your published catalogs.\n\n1. Use the configure a shopper endpoint to allow shoppers to make their selections from a bundle.\n2. In the response of the configure a shopper, the `bundle_configuration` object contains the bundle selections a shopper has made.\n3. In the add a product to cart request, use the `bundle_configuration` object to add the customers selections to a cart.\n\n```json\n \"bundle_configuration\": {\n \"selected_options\": {\n \"games\": {\n \"d7b79eb8-19d8-45ea-86ed-2324a604dd9c\": 1\n },\n \"toys\": {\n \"0192ccdd-6d33-4898-87d7-c4d87f2bf8ea\": 1,\n \"1aea6f97-f0d9-452c-b3c1-7fb5629ead82\": 1\n }\n }\n}\n```\n\nWhen a cart is checked out, the options a shopper selected are added to the order. See [order items](/docs/api/carts/get-order-items).\n\n#### Personalized Products\n\nYou 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.\n\nFirst, 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.\n\nFor example, you may sell T-shirts that can have personalized text on the front and back of the shirt.\n\n```json\n {\n \"data\": {\n \"type\": \"product\",\n \"attributes\": {\n \"custom_inputs\": {\n \"front\": {\n \"name\": \"T-Shirt Front\",\n \"validation_rules\": [\n {\n \"type\": \"string\",\n \"options\": {\n \"max_length\": 50\n }\n }\n ],\n \"required\": false\n },\n \"back\": {\n \"name\": \"T-Shirt Back\",\n \"validation_rules\": [\n {\n \"type\": \"string\",\n \"options\": {\n \"max_length\": 50\n }\n }\n ],\n \"required\": false\n }\n }\n }\n }\n}\n```\n\nIf the same product has different `custom_inputs` attributes, then these are added as separate items in a cart.\n\nThe `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.\n\n#### Limitations on Usage of `custom_inputs` with Specific Promotion Types\n\nWhen you add products to a cart with `custom_inputs`, there are certain limitations on usage of the `custom_inputs` with the following promotion types:\n\n - For [Free Gift Promotions](/docs/api/promotions/create-a-promotion), you can add `custom_inputs` to gift items.\n - 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`.\n - 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.\n\n#### Stock locations\n\nWhen 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.\n\nEach 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.\n\n:::note\n\n- Any requests to add a product to cart returns the collection of cart items.\n- [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.\n- The cart currency is set when the first item is added to the cart.\n- The product being added to the cart requires a price in the same currency as the other items in the cart. The API returns a 400 error if a price is not defined in the correct currency.\n- A cart can contain a maximum of 100 unique items. Items include products, custom items, tax items, and promotions.\n- 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.\n\n:::\n\n### Including Resources\n\nWhen 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.\n\nWhen a bundle with selected component products is added to a cart, the cart displays both the bundle pricing and component product IDs.\n\nThe 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.\n\n| Parameter | Required | Description |\n|:------------------------|:-------------|:-------------------|\n| `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. |\n| `main_image` | Optional | The main images associated with a product. |\n| `files` | Optional | Any files associated with a product. |\n\n```json\n\"bundle_configuration\": {\n \"selected_options\": {\n \"mixed-shirts\": {\n \"16a6cc14-6ebb-4156-9973-e6a0f92f5731\": 3,\n \"55037cc5-f382-4039-95c6-1e04ac0351d3\": 2,\n \"standard-shirts\"\n \"70f1c9d2-c580-4839-bd6c-a0a9b91d5159\": 5\n }\n },\n \"component_products\": [\n {\n \"id\": \"16a6cc14-6ebb-4156-9973-e6a0f92f5731\",\n \"type\": \"product\",\n \"attributes\": {\n \"name\": \"Red T-shirt\",\n \"description\": \"Standard red t-shirt.\",\n \"slug\": \"red-t-shirt-slug\",\n \"sku\": \"red-t-shirt-sku\",\n \"status\": \"live\",\n \"commodity_type\": \"physical\"\n },\n \"meta\": {\n \"display_price\": {\n \"without_tax\": {\n \"amount\": 500,\n \"currency\": \"USD\",\n \"formatted\": \"$5.00\"\n }\n }\n }\n },\n {\n \"id\": \"55037cc5-f382-4039-95c6-1e04ac0351d3\",\n \"type\": \"product\",\n \"attributes\": {\n \"name\": \"Blue T-shirt\",\n \"description\": \"Standard blue t-shirt.\",\n \"slug\": \"blue-t-shirt-slug\",\n \"sku\": \"blue-t-shirt-sku\",\n \"status\": \"live\",\n \"commodity_type\": \"physical\"\n },\n \"meta\": {\n \"display_price\": {\n \"without_tax\": {\n \"amount\": 500,\n \"currency\": \"USD\",\n \"formatted\": \"$5.00\"\n }\n }\n }\n },\n {\n \"id\": \"70f1c9d2-c580-4839-bd6c-a0a9b91d5159\",\n \"type\": \"product\",\n \"attributes\": {\n \"name\": \"White T-shirt\",\n \"description\": \"Standard white t-shirt.\",\n \"slug\": \"white-t-shirt-slug\",\n \"sku\": \"white-t-shirt-sku\",\n \"status\": \"live\",\n \"commodity_type\": \"physical\"\n },\n \"meta\": {\n \"display_price\": {\n \"without_tax\": {\n \"amount\": 500,\n \"currency\": \"USD\",\n \"formatted\": \"$5.00\"\n }\n }\n }\n }\n ]\n}\n```\n\nSee [Including Resources](https://elasticpath.dev/guides/Getting-Started/includes).\n\n### Add Subscription to Cart\n\nTo 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.\n\n```json\n {\n {\n \"data\": {\n \"id\": \"5b9be99f-1c94-4ddd-9718-81adab0cc3e0\",\n \"type\": \"subscription_item\",\n \"quantity\": 1,\n \"subscription_configuration\": {\n \"plan\": \"dfa31307-748c-4369-8571-709f924a0807\",\n \"pricing_option\": \"40010dde-2f38-489b-8b3f-14a13cbfb431\"\n }\n }\n }\n```\n\nThe 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.\n\n### Add Custom Item to Cart\n\nYou can add a custom item to the cart when you don't manage things like shipping, taxes and inventory in Commerce.\n\nFor [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.\n\n:::note\n\n- 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.\n\n:::\n\n### Add Promotion to Cart\n\nYou 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.\n\n 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).\n\nTo remove promotion from the cart via the promotion code, see [Delete Promotion Code from Cart](/docs/api/carts/delete-a-promotion-via-promotion-code).\n\n### Re-order\n\nFrom 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).\n\n:::note\n - Any requests to add an item to cart return a collection of [cart items](/docs/api/carts/cart-items).\n - A cart can contain a maximum of 100 unique items. Items include products, custom items, and promotions.\n - 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.\n - Custom items do not exist in catalogs, and therefore cannot be reordered.\n:::\n\n### Merging Carts\n\nA 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`.\n\nIf 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.\n\n:::note\n\nWhen 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.\n\n:::\n\n### Best Practices\n\nWe 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.\n\nFor example, if a cart consists of the following items:\n\n- `product-1` with quantity 1 and sku code as `sku-1`\n- `product-2` with quantity 1 and sku code as `sku-1`\n- `product-3` with quantity 1 and sku code as `sku-2`.\n\nThe 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:\n\n```json\n{\n \"data\": [\n {\n \"id\": \"c58760f4-8889-4719-b34d-be1f1d11ae59\",\n \"type\": \"custom_item\",\n \"name\": \"product-1\",\n \"description\": \"My first custom item!\",\n \"sku\": \"sku-1\",\n \"slug\": \"\",\n \"image\": {\n \"mime_type\": \"\",\n \"file_name\": \"\",\n \"href\": \"\"\n },\n \"quantity\": 2,\n \"manage_stock\": false,\n \"unit_price\": {\n \"amount\": 20000,\n \"currency\": \"USD\",\n \"includes_tax\": true\n },\n \"value\": {\n \"amount\": 40000,\n \"currency\": \"USD\",\n \"includes_tax\": true\n },\n \"links\": {},\n \"meta\": {\n \"display_price\": {\n \"with_tax\": {\n \"unit\": {\n \"amount\": 20000,\n \"currency\": \"USD\",\n \"formatted\": \"$200.00\"\n },\n \"value\": {\n \"amount\": 40000,\n \"currency\": \"USD\",\n \"formatted\": \"$400.00\"\n }\n },\n \"without_tax\": {\n \"unit\": {\n \"amount\": 20000,\n \"currency\": \"USD\",\n \"formatted\": \"$200.00\"\n },\n \"value\": {\n \"amount\": 40000,\n \"currency\": \"USD\",\n \"formatted\": \"$400.00\"\n }\n },\n \"tax\": {\n \"unit\": {\n \"amount\": 0,\n \"currency\": \"USD\",\n \"formatted\": \"$0.00\"\n },\n \"value\": {\n \"amount\": 0,\n \"currency\": \"USD\",\n \"formatted\": \"$0.00\"\n }\n },\n \"discount\": {\n \"unit\": {\n \"amount\": 0,\n \"currency\": \"USD\",\n \"formatted\": \"$0.00\"\n },\n \"value\": {\n \"amount\": 0,\n \"currency\": \"USD\",\n \"formatted\": \"$0.00\"\n }\n },\n \"without_discount\": {\n \"unit\": {\n \"amount\": 20000,\n \"currency\": \"USD\",\n \"formatted\": \"$200.00\"\n },\n \"value\": {\n \"amount\": 40000,\n \"currency\": \"USD\",\n \"formatted\": \"$400.00\"\n }\n }\n },\n \"timestamps\": {\n \"created_at\": \"2023-05-02T16:28:11Z\",\n \"updated_at\": \"2023-05-02T16:28:18Z\"\n }\n }\n ]\n ```\n" 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 /v2/carts/{cartID}/items/{cartitemID}: parameters: [] 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 /v2/carts/{cartID}/discounts/{promoCode}: parameters: [] 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 components: schemas: 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 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 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 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 BulkUpdateCartsItemsWithQuantity: title: Update Cart Item Quantity allOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsCommon' - type: object required: - quantity - id properties: quantity: {} id: {} 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 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 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 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' 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 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 BulkUpdateCartsItemsWithShippingGroup: title: Update Cart Item Shipping Group allOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsCommon' - type: object required: - shipping_group_id - id properties: shipping_group_id: {} id: {} 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' 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 CartItemObjectRequest: title: Cart Item Object Request type: object properties: data: $ref: '#/components/schemas/CartItemObjectData' 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 ReOrderObjectRequest: title: Re-Order Object Request type: object properties: data: allOf: - $ref: '#/components/schemas/ReOrderObject' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' 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' BulkUpdateCartsItemsWithCustomInputs: title: Update Cart Item Custom Inputs allOf: - $ref: '#/components/schemas/BulkUpdateCartsItemsCommon' - type: object required: - custom_inputs - id properties: custom_inputs: {} id: {} 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 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 Response.ErrorResponse: type: object required: - errors properties: errors: type: array items: $ref: '#/components/schemas/Response.ErrorItem' SubscriptionItemObject: title: Subscription Item Object type: object properties: data: allOf: - $ref: '#/components/schemas/SubscriptionItemObjectData' - $ref: '#/components/schemas/CartItemResponse' 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 CustomItemObject: title: Custom Item Object type: object properties: data: allOf: - $ref: '#/components/schemas/CustomItemObjectData' description: '' 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' 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). 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' CartMergeObjectRequest: title: Cart Merge Object Request type: object properties: data: allOf: - $ref: '#/components/schemas/CartMergeObject' description: '' options: $ref: '#/components/schemas/AddAllOrNothingOptionsObject' 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 CustomAttributes: title: CustomAttributes type: object description: "Specifies custom attributes for cart or order objects. Each attribute includes a top-level key, as well as corresponding type and value entries. Attribute values must correspond to the assigned types.\n\nExample:\n```\n\"custom_attributes\": {\n \"is_member\": {\n \"type\": \"boolean\",\n \"value\": true\n },\n \"membership_level\": {\n \"type\": \"string\",\n \"value\": \"premium\"\n }\n}\n```\n" additionalProperties: type: object required: - type - value properties: type: type: string description: The type of the custom attribute value. enum: - string - integer - boolean - float value: description: The value of the custom attribute. type: - string - boolean - number 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 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 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 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' PromotionItemObject: title: Promotion Item Object type: object properties: data: allOf: - $ref: '#/components/schemas/PromotionItemObjectData' 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 securitySchemes: BearerToken: type: http scheme: bearer