Create a Cart

POST 
https://useast.api.elasticpath.com/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.

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.

application/json

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

MOD1

string

MOD2

number

MOD3

boolean

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

200

Response Headers

application/json

Schema

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

Example (from schema)

{
  "data": {
    "id": "string",
    "type": "string",
    "name": "string",
    "description": "string",
    "discount_settings": {
      "custom_discounts_enabled": true,
      "use_rule_promotions": true
    },
    "payment_intent_id": "string",
    "links": {
      "self": "string"
    },
    "meta": {
      "display_price": {
        "with_tax": {
          "amount": 0,
          "currency": "string",
          "formatted": "string"
        },
        "without_tax": {
          "amount": 0,
          "currency": "string",
          "formatted": "string"
        },
        "tax": {
          "amount": 0,
          "currency": "string",
          "formatted": "string"
        },
        "discount": {
          "amount": 0,
          "currency": "string",
          "formatted": "string"
        },
        "without_discount": {
          "amount": 0,
          "currency": "string",
          "formatted": "string"
        },
        "shipping": {
          "amount": 0,
          "currency": "string",
          "formatted": "string"
        }
      },
      "timestamps": {
        "created_at": "string"
      }
    },
    "relationships": {
      "customers": {
        "data": {
          "type": "string",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      },
      "items": {
        "data": {
          "type": "string",
          "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
        }
      }
    }
  }
}

401

Unauthorized

application/json

Schema

Schema

detail string
status string
title string

Example (from schema)

[
  null
]

Example

{
  "errors": {
    "status": 401,
    "title": "Unauthorized"
  }
}

Authorization: http

name: bearerAuthtype: httpscheme: bearer

• curl
• python
• go
• nodejs
• ruby
• csharp
• php
• java
• powershell

• CURL

curl -L -X POST 'https://useast.api.elasticpath.com/v2/carts' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>' \
--data-raw '{
  "description": "string",
  "discount_settings": {
    "custom_discounts_enabled": true,
    "use_rule_promotions": true
  },
  "name": "string",
  "snapshot_date": "string",
  "custom_attributes": {
    "custom_attributes": {
      "attribute": {
        "type": "string",
        "value": "string"
      }
    }
  },
  "payment_intent_id": "string"
}'

Request Collapse all

Base URL

https://useast.api.elasticpath.com

Auth

Bearer Token

Parameters

x-moltin-customer-token — header

Body

• Example (from schema)
• Create Cart
• Create Preview Cart
• Create a Cart with Custom Attributes

{
  "description": "string",
  "discount_settings": {
    "custom_discounts_enabled": true,
    "use_rule_promotions": true
  },
  "name": "string",
  "snapshot_date": "string",
  "custom_attributes": {
    "custom_attributes": {
      "attribute": {
        "type": "string",
        "value": "string"
      }
    }
  },
  "payment_intent_id": "string"
}

ResponseClear

Click the Send API Request button above and see the response here!