Skip to main content

Create a Cart

POST 
/v2/carts

Creates a cart. Call this endpoint each time a customer creates a cart.

Each shopper can have multiple carts. Use the carts API to create a cart. The carts are distinct from one another. Shoppers can add different items to their carts. They can check out one of the carts without affecting the content or status of their other carts.

After the shopper checks out the cart, the cart remains available to the shopper. The cart is persistent and stays with the shopper after it is used.

You can also create a cart to specify custom discounts. You can enable custom discounts when the discount_settings.custom_discounts_enabled field is set to true. Default is set from cart discount settings for the store. See Update Cart Settings.

Preview Cart​

You can set a future date for your shopping cart and view the promotions that will be available during that time period. This feature enables you to validate your promotion settings and observe how they will be applied in the cart.

caution
  • Once the cart is in preview mode, you cannot revert it to a regular cart.
  • Carts with snapshot_date are same as preview carts.
  • You cannot checkout a cart that includes a snapshot_date.
  • To delete a promotion preview cart, use Delete a cart endpoint.
  • The promotion preview cart has the same expiration time as a regular cart based on the store's cart settings.
  • Preview cart interactions skip inventory checks and events, allowing users to preview future carts without impacting related external systems.

Custom Attributes​

You can create custom attributes for the cart object to include additional information, enabling promotions that target specific cart attributes. For example:

"custom_attributes":{
  "membership": {
    "type": "string",
    "value": "VIP"
  }
}

See adding cart custom attributes in promotions builder

Cart custom attributes remain with the corresponding cart for the extent of its lifecycle. These custom attributes carry over to the resulting order objects on checkout and those on carts are deleted with their carts upon cart deletions. Custom attributes can be updated or removed using a PUT request. To delete specific custom attributes, simply exclude the unwanted attribute objects from the PUT request body.

Contact Email​

You can attach an email to carts via the contact.email field. These values help identify guest shopper carts and, in the case of promotions with maximum usage settings for guest and registered shopper, track per-shopper promotion usages. See Create Max Uses Per Shopper Promotion Codes

For example:

"contact": {
  "email": "tester@email.com"
}

Please note, this value is not supported for registered shopper carts (that is, carts with accounts or customers associated), as these carts already have email values associated via the shopper details. Accordingly, requests to add contact email information to registered shopper carts (and vice versa) result in error messages.

Errors​

  • 400 Bad Request : This is returned when the submitted request does not adhere to the expected API contract for the endpoint.

    • For example, in the case of string fields, this error might indicate issues in the length or format of submitted strings. For more information about valid string fields, refer to Safe Characters section.
    • In the case of preview carts (those with snapshot_date), an error is returned for invalid actions, such as removing the preview date, setting a preview date in the past, or attempting to checkout a cart with a snapshot_date.

Request​

Responses​

Response Headers