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.

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​

Header Parameters

    x-moltin-customer-token string

    A customer token to be associated with the cart.

Body

    description string

    The cart description.

    discount_settings object
    custom_discounts_enabled boolean

    This parameter enables custom discounts for a cart. When set to true, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See Cart Settings.

    use_rule_promotions boolean

    When set to true, this parameter allows the cart to use rule promotions.

    name string

    The cart name provided by the shopper. A cart name must contain 1 to 255 characters. You cannot use whitespace characters, but special characters are permitted. For more information, see the Safe Characters section.

    snapshot_date string

    This optional parameter sets a reference date for the cart. If this parameter is set, it allows the cart to act as one that might occur on that specified date. For example, such future carts might acquire future-enabled discounts, allowing users to test and validate future interactions with carts. The snapshot_date must be in the format 2026-02-21T15:07:25Z. By default, this parameter is left empty.

    custom_attributes object
    custom_attributes object

    Specifies the custom attributes for the cart object. The attribute can be any string, numerical, and underscore. A cart can have maximum of 20 custom attributes.

    attribute object

    Specifies the attribute type and value.

    type string

    Specifies the type of the attribute such as string, integer, boolean, and float.

    value object

    Specifies the value of the attribute.

    oneOf

    string

    payment_intent_id string

    To remove the Stripe payment intent from a cart, pass the empty value in the payment_intent_id field. You must use an empty value for this field. You cannot use this endpoint to directly update the cart to use an existing Payment Intent.

Responses​

Response Headers
    Schema
      data object
      id string

      The unique identifier for the cart. Use SDK or create it yourself.

      type string

      The type of object being returned.

      name string

      The name of this cart.

      description string

      A description of the cart.

      discount_settings object
      custom_discounts_enabled boolean

      This parameter enables custom discounts for a cart. When set to true, Elastic Path promotions will not be applied to the new carts. Default is set from cart discount settings for the store. See Cart Settings.

      use_rule_promotions boolean

      When set to true, this parameter allows the cart to use rule promotions.

      payment_intent_id string

      Stripe-assigned unique identifier for the linked Payment Intent

      links object
      self string

      A link to that specific 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.

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

      relationships object
      customers object
      data object
      type string

      The type of related object.

      id uuid

      The ID of the customer.

      items object
      data object
      type string

      The type of related object.

      id uuid

      The unique identifier for the cart item

    Loading...