Create Cart

Start a shopping cart and obtain the cart token that identifies it. A guest client calls this once at the beginning of a session and reuses the returned token for every subsequent cart and checkout call.

Endpoint

POST /api/shop/cart-tokens

The path is /cart-tokens, not /cart — /api/shop/cart is the read endpoint documented on Get Cart.

Request Headers

Header	Required	Description
Content-Type	Yes	application/json
Accept	Yes	application/json
X-STOREFRONT-KEY	Yes	Your storefront API key
Authorization	No	A signed-in customer's Bearer token, to tie the cart to their account

Request Body

Send an empty object. The endpoint takes no fields — items are added afterwards with Add to Cart.

{}

Response Fields

The response is the newly created cart, returned as a bare object with no wrapper.

Field	Type	Description
id	integer	Cart ID.
cartToken	string	Send this as Authorization: Bearer <cartToken> on every later cart call.
customerId	integer	Owning customer, or null for a guest cart.
channelId	integer	Channel the cart belongs to.
itemsCount	integer	Number of line items. 0 on a new cart.
itemsQty	integer	Total units across those lines.
items	array	Line items — empty on a new cart.
subtotal / baseSubtotal	decimal	Items subtotal, in cart and base currency.
discountAmount / baseDiscountAmount	decimal	Discount applied.
taxAmount / baseTaxAmount	decimal	Tax calculated.
shippingAmount / baseShippingAmount	decimal	Shipping cost.
grandTotal / baseGrandTotal	decimal	Grand total.
formattedSubtotal, formattedDiscountAmount, formattedTaxAmount, formattedShippingAmount, formattedGrandTotal	string	The same amounts, currency-formatted for display.
couponCode	string	Applied coupon, or null.
isGuest	boolean	Whether the cart belongs to a guest.

Use Cases

• Start a guest session — call once, store cartToken, and send it on every cart and checkout request.
• Start a signed-in session — send the customer's Bearer token as well, so the cart is tied to their account and survives across devices.

Best Practices

1. Store the cartToken, not the cart id — the token is what authenticates later calls; the numeric ID is informational
2. Create the cart once per session — calling again issues a new empty cart and orphans the previous one
3. Merge after login — a guest who signs in mid-session should call Merge Cart so their items survive
4. Expect an empty cart, not an error — a newly created cart has itemsCount: 0 and zeroed totals

Related Resources

• Get Cart — read the current items and recalculated totals
• Add to Cart — add a product of any type to the cart
• Merge Cart — fold a guest cart into the customer's cart after login