Skip to main content

Manage Carts

POST 
/v2/carts/:cartID/items

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.

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.
  "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.

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.

    {
      "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:

note
  • Any requests to add a product to cart returns the collection of cart items.
  • Tax items may optionally be added with the product. Only administrators with client credentials 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 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.

ParameterRequiredDescription
component_productsOptionalThe component product data and key attribute data, such as SKU or slug, to return for component products in a product bundle.
main_imageOptionalThe main images associated with a product.
filesOptionalAny files associated with a product.
"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.

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 plan within that offering that you want to subscribe to.

  {
    {
      "data": {
        "id": "5b9be99f-1c94-4ddd-9718-81adab0cc3e0",
        "type": "subscription_item",
        "quantity": 1,
        "subscription_configuration": {
          "plan": "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, once you have created a 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 through implicit authentication. 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.

To remove promotion from the cart via the promotion code, see Delete Promotion Code from Cart.

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.

note
  • Any requests to add an item to cart return a collection of 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:

{
  "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"
        }
    }
  }

Request​

Path Parameters

    cartID stringrequired

    The unique identifier of the cart that you created.

Body

    oneOf
    data object[]
    options object
    add_all_or_nothing boolean

    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.

Responses​

Response Headers
    Schema
      data object[]
    • Array [
      • anyOf
      data object
      type stringrequired

      Possible values: [cart_item]

      The type of object being returned.

      quantity numberrequired

      The number of items added to the cart.

      id uuid

      Specifies the ID of the product you want to add to cart. (use this OR sku)

      sku string

      Specifies the item SKU that you want to add to cart. (use this OR id)

      custom_inputs object

      The custom text to be added to a product.

      bundle_configuration object

      Object used to describe the bundle options selected.

      selected_options object

      Specifies selected options.

      component_products array

      Array of component products for the selected options.

      shipping_group_id string

      Identifier for a created Cart Shipping Group

      product_id uuid

      The unique ID of the product.

      subscription_offering_id uuid

      The unique ID of the subscription offering for subscription items.

      name string

      The name of this item

      description string

      A description of the cart item.

      catalog_id uuid

      The unique identifier of the catalog associated with the product is shown if catalog_source=pim is set.

      catalog_source string

      The catalog source. Always pim or legacy.

      image object
      mime_type string

      The MIME type for the uploaded file.

      file_name string

      The name of the image file that was uploaded.

      href string

      The link to the image.

      manage_stock boolean
      unit_price object
      amount number

      The amount for this item as an integer.

      currency string

      The currency this item was added to the cart as.

      includes_tax boolean

      Whether or not this price is tax inclusive.

      value object
      amount number

      The amount for this item as an integer.

      currency string

      The currency this item was added to the cart as.

      includes_tax boolean

      Whether or not this price is tax inclusive.

      links object
      product string

      A URL related to the resource.

      meta object
      display_price object
      with_tax object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      without_tax object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      tax object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      discount object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      without_discount object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      timestamps object
      created_at string

      The date this was created.

      updated_at

      The date this was last updated.

    • ]
      • meta object
      display_price object
      with_tax object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      without_tax object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      tax object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      discount object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      without_discount object
      amount number

      The raw total of this cart.

      currency string

      The currency set for this cart.

      formatted string

      The tax inclusive formatted total based on the currency.

      discounts object
      property name* object
      amount number
      currency string
      formatted string
      timestamps object
      created_at string
      updated_at
      expires_at
    Loading...