Skip to content

Cart

Create a cart, add products and variants, set addresses and promotion codes, and read the totals the Store API computes.

A storefront keeps the shopping basket of a visitor in a Shopper cart. The Store API creates the cart, prices every line from the catalog, checks stock, applies promotion codes, computes tax once a shipping address is known, and returns the totals with every response. The storefront never computes a price: it sends what the customer picked and renders the cart the API answers with.

Every amount in a cart response is an integer in cents: a line priced at €90.00 carries 9000. The Money page covers cents and formatting. The Checkout guide picks up where this page ends, with shipping, payment and the order.

Endpoints

The cart endpoints sit in the public route group: they work without a customer token, and with one. The ones that create or add things share the checkout rate limit of 30 requests per minute (shopper.http.rate_limiters), on top of the general limit described in Rate limits. On these public routes both limits count requests per IP address, for guests and logged-in customers alike.

Request bodies are flat JSON objects, such as {"quantity": 2}, sent with Content-Type: application/json. Responses are JSON:API documents, described in JSON:API Conventions. Every endpoint of this page answers with the whole cart, so the storefront re-renders from the response without a second call.

Creating a Cart

A storefront creates the cart the first time the visitor adds something, and keeps its ID for every later call. The cart takes its zone from the X-Shopper-Zone header of this request, or the default zone when the header is missing, as described in Request headers. The zone sets the prices, the shipping options and the payment methods the cart offers.

POST/store/carts
Auth
Customer bearer token, optional

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Body

  • currency_codestringoptional

    ISO code of an enabled currency of the shop, such as EUR. Upper-cased before validation. Defaults to the currency of the zone, then to the default currency of the shop.

  • emailstringoptional

    Contact email of the checkout, lower-cased. Up to 255 characters.

  • metadataobjectoptional

    Your own data, such as a gift note or a tracking source. Up to 50 keys and 4,096 characters once encoded as JSON.

Every parameter is optional, so an empty body creates a cart in the currency of the zone:

Request
curl -X POST http://localhost:8000/store/carts \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -H "X-Shopper-Zone: EU" \
  -d '{"email": "camille.martin@example.com"}'

The API answers 201 Created with the new cart. Its id is the cart ID the storefront stores:

Response 201
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "email": "camille.martin@example.com",
            "promotions": [],
            "completed_at": null,
            "metadata": null,
            "lines_count": 0,
            "lines_quantity": 0,
            "subtotal": 0,
            "discount_total": 0,
            "tax_total": 0,
            "shipping_total": 0,
            "total": 0,
            "tax_inclusive": false,
            "shipping_option_id": null,
            "created_at": "2026-11-19T10:15:00+00:00",
            "updated_at": "2026-11-19T10:15:00+00:00"
        }
    }
}

A currency_code that is unknown, disabled or not one of the shop currencies answers 422 with the code exists on /data/attributes/currency_code.

Errors
StatusCodeWhen
422existscurrency_code is unknown, disabled or not one of the shop currencies
422Rule name, such as emailAnother field fails validation
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

Guest and Customer Carts

Who can use a cart depends on the request that created it. A request without a customer token creates a guest cart. A request with the bearer token of a logged-in customer, described in Logging in, creates a cart that belongs to that customer. Send the same token on every later call for that cart.

A guest cart has no owner: any request that carries its ID can read and change it. The ID is a ULID, 26 characters with 80 random bits, so it cannot be guessed, but it works like a session token. Keep it where the visitor's session lives, such as an HttpOnly cookie or the secure storage of a mobile app, and keep it out of URLs, logs and analytics events.

A customer cart answers only to its owner. A request without the token, or with the token of another customer, gets 404 not_found, the same answer as an ID that does not exist, so the API never confirms that a cart exists. An expired or revoked token counts as no token, so the customer cart also answers 404 once the token expires: log the customer in again before creating a new cart. A valid token without the store ability answers 401 unauthenticated, even on these public routes.

When a guest logs in during checkout, transfer the guest cart to the customer with the cart transfer endpoint described in Customers. The cart then answers only to that customer.

A completed cart, one that became an order, stays readable with the same ID. Any change to it answers 409 cart_completed. Open carts that see no activity for 30 days are deleted by the scheduled shopper:prune-carts command, as the Cart page describes, so a storefront that gets 404 on a stored ID creates a new cart.

Adding a Line

A line is one product or one variant in the cart, with its quantity. The storefront sends the type and the public ID of what the customer picked; the API finds it in the catalog, prices it in the cart currency and checks stock. The client never sends a price.

POST/store/carts/{cartId}/lines
Auth
The ID, and the customer token when a customer owns it

Path parameters

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Body

  • purchasable_typestring

    variant for a product variant, product for a product without variants.

  • purchasable_idstring

    The public ID of the variant or the product, the id the Catalog endpoints return.

  • quantityintegeroptionalDefault: 1

    Quantity to add, from 1 to 1,000,000.

  • metadataobjectoptional

    Data of this line, such as an engraving text. Same limits as the cart metadata.

This request adds two pairs of Classic Leather Sneakers in size 42, black, and asks for the lines in the same response with include=lines:

Request
curl -X POST "http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/lines?include=lines" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{
    "purchasable_type": "variant",
    "purchasable_id": "01JD8YQ3H5K7M9P2R4T6V8X0Z1",
    "quantity": 2
  }'

The API answers 200 OK with the recalculated cart. The line carries the unit price frozen when it was added:

Response 200
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "email": "camille.martin@example.com",
            "promotions": [],
            "completed_at": null,
            "metadata": null,
            "lines_count": 1,
            "lines_quantity": 2,
            "subtotal": 18000,
            "discount_total": 0,
            "tax_total": 0,
            "shipping_total": 0,
            "total": 18000,
            "tax_inclusive": false,
            "shipping_option_id": null,
            "created_at": "2026-11-19T10:15:00+00:00",
            "updated_at": "2026-11-19T10:16:12+00:00"
        },
        "relationships": {
            "lines": {
                "data": [
                    { "id": "01JD8Z7C1E3G5J7K9N1Q3S5V7W", "type": "cart-lines" }
                ]
            }
        }
    },
    "included": [
        {
            "id": "01JD8Z7C1E3G5J7K9N1Q3S5V7W",
            "type": "cart-lines",
            "attributes": {
                "purchasable_type": "variant",
                "quantity": 2,
                "unit_price_amount": 9000,
                "is_custom_price": false,
                "subtotal": 18000,
                "discount_total": 0,
                "tax_total": 0,
                "adjustments": [],
                "tax_lines": [],
                "metadata": null,
                "created_at": "2026-11-19T10:16:12+00:00",
                "updated_at": "2026-11-19T10:16:12+00:00"
            }
        }
    ]
}

Adding the same variant again adds to the quantity of its existing line instead of creating a second line. When the new request carries metadata that differs from the metadata of that line, the API refuses with 422 cart_line_metadata_conflict: update that line or remove it first.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422purchasable_unavailableThe product or variant cannot be bought
422variant_requiredThe product is sold through its variants
422price_missingNo price in the cart currency
422stock_insufficientNot enough stock for the quantity
422quantity_rule_violatedThe quantity breaks a minimum, maximum or increment, details in meta
422cart_line_metadata_conflictThe line already exists with other metadata
422Rule name, such as requiredA field fails validation
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

Products and Variants

A product that has variants is sold through them. Adding such a product with purchasable_type: "product" answers 422 variant_required on /data/attributes/purchasable_id: the storefront asks the customer for a size or a color and adds the variant. The Catalog guide shows how to read the variants of a product, and Product Variants explains how they are built.

The API accepts a product when it is published and not an external product, and a variant when its product is published. Anything else answers 422 purchasable_unavailable on /data/attributes/purchasable_id. A purchasable that has prices, but none in the cart currency, answers 422 price_missing on /data/attributes/purchasable_id.

Stock and Quantity Rules

The API checks stock when a line is added or its quantity changes. A variant or product that tracks its inventory and does not allow backorders answers 422 stock_insufficient on /data/attributes/quantity when the stock cannot cover the quantity. The check runs again when the order is placed, as the Checkout guide explains.

A price can carry quantity rules (a minimum, a maximum, an increment), described in Pricing. A quantity that breaks one answers 422 quantity_rule_violated with a meta object, so the storefront can correct the quantity selector:

Response 422
{
    "errors": [
        {
            "status": "422",
            "code": "quantity_rule_violated",
            "title": "Unprocessable Content",
            "detail": "This item must be ordered in multiples of 2.",
            "source": { "pointer": "/data/attributes/quantity" },
            "meta": {
                "purchasable_id": "01JD8YQ3H5K7M9P2R4T6V8X0Z1",
                "quantity": 3,
                "minimum": 2,
                "maximum": null,
                "increment": 2
            }
        }
    ]
}

Reading a Cart

A storefront reads the cart to render the basket page or the mini cart. The totals come with the cart, so one request is enough: the API reuses the stored totals when they were calculated in the last 15 minutes (shopper.cart.totals_ttl_minutes) and recalculates them otherwise.

GET/store/carts/{cartId}
Auth
The ID, and the customer token when a customer owns it
Rate limit
shopper-api

Path parameters

Query parameters

  • includestringoptional

    Related resources to return with the cart, comma-separated, from the table below.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

The cart document carries only the cart attributes by default. The include query parameter adds related resources, as described in Includes. The cart accepts these paths, which CartResource declares in its includes() method:

IncludeAdds
linesThe cart lines
lines.purchasableThe lines and the variant or product of each line
lines.purchasable.productThe same, plus the parent product of each variant
addressesThe shipping and billing addresses
paymentMethodThe payment method chosen at checkout

Any other path answers 400 bad_request. A basket page asks for lines.purchasable to show the variant of each line, or lines.purchasable.product to add the parent product and its images:

Request
curl "http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C?include=lines.purchasable" \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK. In this trimmed response, the cart keeps its totals and the variant keeps three of its attributes; the Catalog guide lists them all:

Response 200
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "lines_count": 1,
            "lines_quantity": 2,
            "subtotal": 18000,
            "discount_total": 0,
            "tax_total": 0,
            "shipping_total": 0,
            "total": 18000,
            "tax_inclusive": false
        },
        "relationships": {
            "lines": {
                "data": [
                    { "id": "01JD8Z7C1E3G5J7K9N1Q3S5V7W", "type": "cart-lines" }
                ]
            }
        }
    },
    "included": [
        {
            "id": "01JD8Z7C1E3G5J7K9N1Q3S5V7W",
            "type": "cart-lines",
            "attributes": {
                "purchasable_type": "variant",
                "quantity": 2,
                "unit_price_amount": 9000,
                "subtotal": 18000
            },
            "relationships": {
                "purchasable": {
                    "data": { "id": "01JD8YQ3H5K7M9P2R4T6V8X0Z1", "type": "variants" }
                }
            }
        },
        {
            "id": "01JD8YQ3H5K7M9P2R4T6V8X0Z1",
            "type": "variants",
            "attributes": {
                "name": "42 / Black",
                "sku": "CLS-BLK-42",
                "prices": [
                    {
                        "public_id": "01JD8YR6A8C0E2G4J6K8N0Q2S4",
                        "amount": 9000,
                        "compare_amount": null,
                        "currency_code": "EUR"
                    },
                    {
                        "public_id": "01JD8YR6A8C0E2G4J6K8N0Q2S5",
                        "amount": 9900,
                        "compare_amount": null,
                        "currency_code": "USD"
                    }
                ]
            }
        }
    ]
}
Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

Render the price of a line from unit_price_amount and subtotal of the line, not from the prices of the variant: the line keeps the price it was added at, which can differ from the current catalog price until checkout checks it again.

Updating and Removing Lines

The quantity selector of the basket page changes a line through its ID, the id of the cart-lines resource. A quantity of zero is not accepted: removing a line has its own endpoint.

PATCH/store/carts/{cartId}/lines/{lineId}
Auth
The ID, and the customer token when a customer owns it
Rate limit
shopper-api

Path parameters

  • cartIdstring

    The cart ID.

  • lineIdstring

    The id of the cart-lines resource.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Body

  • quantityintegeroptional

    New quantity of the line, from 1 to 1,000,000. Checked against stock and quantity rules like an added line.

  • metadataobjectoptional

    New metadata of the line. null clears it.

This request brings the line of sneakers from two pairs down to one:

Request
curl -X PATCH http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/lines/01JD8Z7C1E3G5J7K9N1Q3S5V7W \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{"quantity": 1}'

The API answers 200 OK with the cart.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request, or no line with this ID in the cart
422stock_insufficientNot enough stock for the quantity
422quantity_rule_violatedThe quantity breaks a minimum, maximum or increment, details in meta
422Rule name, such as minA field fails validation
409cart_line_lockedThe line has a custom price
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

DELETE/store/carts/{cartId}/lines/{lineId}
Auth
The ID, and the customer token when a customer owns it
Rate limit
shopper-api

Path parameters

  • cartIdstring

    The cart ID.

  • lineIdstring

    The id of the cart-lines resource.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Removing the line works the same way and also answers 200 OK with the recalculated cart, not an empty 204:

Request
curl -X DELETE http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/lines/01JD8Z7C1E3G5J7K9N1Q3S5V7W \
  -H "Accept: application/vnd.api+json"
Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request, or no line with this ID in the cart
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

A line ID that does not belong to the cart answers 404 not_found. A line with is_custom_price: true holds a price negotiated in the back office: its quantity cannot change and the API answers 409 cart_line_locked. The storefront can still remove it.

Addresses

The cart needs a shipping address before checkout: taxes, live carrier rates and the order addresses come from it. One request sets the shipping address, the billing address, or both, and can set the contact email at the same time. Sending an address type again replaces the previous one.

POST/store/carts/{cartId}/addresses
Auth
The ID, and the customer token when a customer owns it
Rate limit
shopper-api

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Each address object takes the same fields, listed under each one:

Body

  • shipping_addressobjectoptional

    The delivery address. Required when billing_address is missing.

    Child fields (10)
    • last_namestring

      Last name, up to 255 characters.

    • address_1string

      Street and number.

    • citystring

      City.

    • postal_codestring

      Postal code.

    • country_codestring

      Two-letter ISO code of the country, such as FR. Upper-cased before validation.

    • first_namestringoptional

      First name, up to 255 characters.

    • companystringoptional

      Company name, up to 255 characters.

    • address_2stringoptional

      Apartment, floor or building.

    • statestringoptional

      State or province. Tax rules of a province match on this value.

    • phonestringoptional

      Phone number.

  • billing_addressobjectoptional

    The billing address. Required when shipping_address is missing.

    Child fields (10)
    • last_namestring

      Last name, up to 255 characters.

    • address_1string

      Street and number.

    • citystring

      City.

    • postal_codestring

      Postal code.

    • country_codestring

      Two-letter ISO code of the country, such as FR. Upper-cased before validation.

    • first_namestringoptional

      First name, up to 255 characters.

    • companystringoptional

      Company name, up to 255 characters.

    • address_2stringoptional

      Apartment, floor or building.

    • statestringoptional

      State or province. Tax rules of a province match on this value.

    • phonestringoptional

      Phone number.

  • emailstringoptional

    Contact email of the checkout, lower-cased. Replaces the email of the cart.

This request sets a shipping address in Paris, and asks for the addresses back with include=addresses:

Request
curl -X POST "http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/addresses?include=addresses" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{
    "shipping_address": {
      "first_name": "Camille",
      "last_name": "Martin",
      "address_1": "12 Rue de Rivoli",
      "city": "Paris",
      "postal_code": "75004",
      "phone": "+33612345678",
      "country_code": "FR"
    }
  }'

The API answers 200 OK with the cart. With a French address, the 20% VAT now shows in tax_total, and tax_inclusive is true because the tax zone of France is set up with prices that include tax. The response is trimmed to the totals and the address:

Response 200
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "subtotal": 18000,
            "discount_total": 0,
            "tax_total": 3000,
            "shipping_total": 0,
            "total": 18000,
            "tax_inclusive": true
        },
        "relationships": {
            "addresses": {
                "data": [
                    { "id": "01JD8ZA4B6D8F0H2K4M6P8R0T2", "type": "cart-addresses" }
                ]
            }
        }
    },
    "included": [
        {
            "id": "01JD8ZA4B6D8F0H2K4M6P8R0T2",
            "type": "cart-addresses",
            "attributes": {
                "type": "shipping",
                "first_name": "Camille",
                "last_name": "Martin",
                "full_name": "Camille Martin",
                "company": null,
                "address_1": "12 Rue de Rivoli",
                "address_2": null,
                "city": "Paris",
                "state": null,
                "postal_code": "75004",
                "country_code": "FR",
                "phone": "+33612345678"
            }
        }
    ]
}
Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422Rule name, such as required_withA field fails validation, the pointer names it, such as /data/attributes/shipping_address/city
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

The address does not change the zone of the cart. When the country is outside the zone, the shipping options endpoint returns no option and a warning, as the Checkout guide shows: switch the cart to the zone of that country with zone_code, described in Updating the cart. The Taxes page explains how the tax zone is picked from the country and the state.

Promotion Codes

A promotion code entered by the customer is checked against the whole cart before it is kept: its currency, zone, dates, eligible products, minimum amount or quantity, usage limits and campaign budget. A code that cannot apply is refused and leaves the cart as it was. Automatic promotions need no request: they appear in promotions as soon as the cart qualifies. The Discounts page describes how promotions are set up.

POST/store/carts/{cartId}/promotion
Auth
The ID, and the customer token when a customer owns it

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Body

  • codestring

    The promotion code, up to 255 characters.

This request applies the code WELCOME10 to the cart:

Request
curl -X POST http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/promotion \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{"code": "WELCOME10"}'

The API answers 200 OK with the cart. WELCOME10 takes 10% off the subtotal, and the VAT is recalculated on the discounted amount. The response is trimmed to the totals:

Response 200
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "promotions": [
                {
                    "code": "WELCOME10",
                    "source": "code",
                    "amount": 1800,
                    "status": "applied"
                }
            ],
            "subtotal": 18000,
            "discount_total": 1800,
            "tax_total": 2700,
            "shipping_total": 0,
            "total": 16200,
            "tax_inclusive": true
        }
    }
}

Each entry of promotions has a source of code or automatic, the amount it takes off the cart in cents, and a status. A promotion is applied when its amount is above zero, and suppressed when it takes nothing off the cart right now, such as a code that an exclusive promotion of higher priority overrides. A suppressed code stays on the cart. A cart applies at most 5 promotions at once (shopper.cart.max_promotions). Each line shows its share of the discount in its own adjustments, with the code and the amount.

A code the cart cannot use answers 422 promotion_not_applicable, with the same message whatever the reason, so codes cannot be discovered by trying them:

Response 422
{
    "errors": [
        {
            "status": "422",
            "code": "promotion_not_applicable",
            "title": "Unprocessable Content",
            "detail": "This promotion code does not apply to your cart.",
            "source": { "pointer": "/data/attributes/code" }
        }
    ]
}
Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422promotion_not_applicableThe code does not exist or does not apply to the cart
422Rule name, such as requiredA field fails validation
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

DELETE/store/carts/{cartId}/promotion
Auth
The ID, and the customer token when a customer owns it

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Body

  • codestringoptional

    The promotion code to remove. Without it, every code of the cart is removed.

Removing a code takes the same code field. Without it, the request removes every code of the cart; automatic promotions stay:

Request
curl -X DELETE http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/promotion \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{"code": "WELCOME10"}'

The API answers 200 OK with the cart. When the cart later changes currency or zone, the codes that no longer apply are dropped from it.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

Updating the Cart

The cart itself has four fields a storefront changes after creating it: the currency of a currency switcher, the zone of a country picker, the email of the checkout form and the metadata. Send only the fields that change.

PATCH/store/carts/{cartId}
Auth
The ID, and the customer token when a customer owns it
Rate limit
shopper-api

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • includestringoptional

    Related resources to return with the cart, listed in Reading a Cart.

  • fields[carts]stringoptional

    Comma-separated attributes to return, such as lines_count,total. See Sparse fieldsets.

Body

  • currency_codestringoptional

    ISO code of an enabled currency of the shop. The lines are priced again in that currency.

  • zone_codestringoptional

    Code of an enabled zone, the code the X-Shopper-Zone header carries. The lines are priced again for that zone.

  • emailstringoptional

    Contact email of the checkout, lower-cased.

  • metadataobjectoptional

    Replaces the cart metadata. null clears it.

This request switches the cart to US dollars:

Request
curl -X PATCH http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{"currency_code": "USD"}'

The API answers 200 OK with the cart priced in the new currency. Switching currency or zone resets part of the checkout:

ChangeLinesShipping methodPayment methodPromotion codes
currency_codePriced again in the new currencyRemovedKeptDropped when they no longer apply
zone_codePriced again for the new zoneRemovedRemovedDropped when they no longer apply

The currency of the cart stays the same on a zone switch: send both fields to change both. When a line has no price in the new currency, the API refuses with 422 price_missing on /data/attributes/currency_code and changes nothing. A line with a custom price cannot change currency and answers 409 cart_line_locked.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422price_missingA line has no price in the new currency
422Rule name, such as existsA field fails validation, such as a disabled zone_code
409cart_line_lockedA line has a custom price
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: complete the cart
409payment_session_in_progressAnother request is changing the cart, retry after Retry-After
503payment_provider_unavailableThe open payment could not be cancelled, retry after Retry-After
400bad_requestAn include path outside the cart list

The meaning of every code is in Error Codes.

The Cart Resource

The cart resource has the type carts and the public ID of the cart as its id. These attributes come with every cart response:

carts attributes

  • currency_codestring

    ISO code of the cart currency.

  • emailstring, null

    Contact email of the checkout.

  • promotionsarray

    The promotions on the cart.

    Child fields (4)
    • codestring

      The promotion code.

    • sourcestring

      code or automatic.

    • amountinteger

      What the promotion takes off the cart, in cents.

    • statusstring

      applied or suppressed.

  • completed_atstring, null

    When the cart became an order, ISO 8601.

  • metadataobject, null

    Your own data.

  • lines_countinteger

    Number of lines.

  • lines_quantityinteger

    Sum of the line quantities.

  • subtotalinteger

    Sum of the line subtotals, in cents.

  • discount_totalinteger

    Total of the promotions, in cents.

  • tax_totalinteger

    Tax of the cart, in cents, 0 until the cart has a shipping address.

  • shipping_totalinteger

    Price of the chosen shipping option, in cents.

  • totalinteger

    Amount to pay, in cents.

  • tax_inclusiveboolean

    Whether the prices already include tax_total.

  • shipping_option_idstring, null

    The chosen shipping option, {carrier_code}:{service_code}.

  • created_atstring

    ISO 8601.

  • updated_atstring

    ISO 8601.

The total follows the tax mode of the shipping address. When tax_inclusive is true, total is the subtotal minus the discounts, plus shipping, and tax_total is the share of VAT it already contains: show it as "VAT included". When it is false, total adds tax_total on top. The subtotal minus the discounts never goes below zero. The Cart page describes the calculation pipeline behind these numbers.

A cart-lines resource has these attributes:

cart-lines attributes

  • purchasable_typestring

    variant or product.

  • quantityinteger

    Quantity of the line.

  • unit_price_amountinteger

    Unit price frozen when the line was added, in cents.

  • is_custom_priceboolean

    Whether the price was set by hand in the back office, which locks the line.

  • subtotalinteger

    unit_price_amount times quantity, in cents.

  • discount_totalinteger

    Discount on the line, in cents.

  • tax_totalinteger

    Tax on the line, in cents.

  • adjustmentsarray

    The discounts of the line.

    Child fields (2)
    • amountinteger

      Discount amount, in cents.

    • codestring

      The promotion code.

  • tax_linesarray

    The taxes of the line.

    Child fields (4)
    • codestring

      Code of the tax rate.

    • namestring

      Name of the tax rate.

    • ratenumber

      A percentage, 20 for 20%.

    • amountinteger

      Tax amount, in cents.

  • metadataobject, null

    Data of the line.

  • created_atstring

    ISO 8601.

  • updated_atstring

    ISO 8601.

Its purchasable relationship points to a variants or a products resource, the same resources the catalog returns. A cart-addresses resource carries type (shipping or billing), first_name, last_name, full_name, company, address_1, address_2, city, state, postal_code, country_code and phone.

Errors

Errors use the JSON:API error object, with a code a client can branch on, described with every code in Error codes. On top of validation errors, 401 unauthenticated for a rejected token and 429 rate_limited, the cart endpoints answer with these codes:

CodeStatusEndpointsWhen
not_found404All but POST /cartsNo cart with this ID for this request, or no line with this ID in the cart
bad_request400All that answer with the cartAn include path outside the cart allowlist
purchasable_unavailable422Add a lineThe product or variant cannot be bought
variant_required422Add a lineThe product is sold through its variants
price_missing422Add a line, update the cartNo price in the cart currency, or in the new currency
stock_insufficient422Add a line, update a lineNot enough stock for the quantity
quantity_rule_violated422Add a line, update a lineThe quantity breaks a minimum, maximum or increment, details in meta
cart_line_metadata_conflict422Add a lineThe line already exists with other metadata
promotion_not_applicable422Apply a codeThe code does not exist or does not apply to the cart
cart_line_locked409Update a line, update the cartThe line has a custom price
cart_completed409All changesThe cart is already an order
payment_session_collected409All changesThe customer already paid: the cart can no longer change, complete it
payment_session_in_progress409All changesAnother request is changing the cart, retry after the Retry-After header (3 seconds)
payment_provider_unavailable503All changesThe open payment could not be cancelled at the provider, retry after the Retry-After header (5 seconds)

The last three come from the payment session a checkout opens. A change to the cart that alters its total cancels that session, and the storefront opens a new one, as the Checkout guide explains.

Next Steps

The cart now holds lines, an email and a shipping address. The checkout guide lists the shipping options and payment methods for this cart, opens the payment and turns the cart into an order.

Last updated on

Edit on GitHub