Skip to content

Checkout

Choose shipping and payment for a cart, open a payment session, and turn the cart into an order with the Store API.

Checkout turns a cart into an order. The storefront offers the shipping options and payment methods the API returns for the cart, opens a payment at the provider for the amount the API computes, lets the customer pay in the browser, then completes the cart. The API owns every amount: it quotes shipping, sets the amount of the payment, checks prices and stock again before it places the order, and answers with the order.

This guide starts where Cart ends, with a cart that holds lines, an email and a shipping address. Amounts are integers in cents, as on the cart. A checkout goes through four steps:

Set the shipping method

List the shipping options of the cart and send back the one the customer picks.

Set the payment method

List the payment methods of the cart and send back the one the customer picks.

Open a payment session

Ask the API to open the payment at the provider, then let the customer confirm it in the browser with the provider's SDK, such as Stripe.js.

Complete the cart

Place the order once the provider has confirmed the payment. The provider's webhooks then move the payment status of the order.

A cart that needs no delivery skips the first step, and a payment method that collects offline, such as a bank transfer, skips the third.

Endpoints

The checkout endpoints take the cart ID and follow the access rules of the cart endpoints: a guest cart answers to any request that carries its ID, a customer cart only to the bearer token of its owner, as described in Cart. The calls that set the payment method, open the payment session and complete the cart share the checkout rate limit of 30 requests per minute (shopper.http.rate_limiters), counted per IP address, on top of the general limit described in Rate limits.

The two listing endpoints return every option in one response: they take no filters, sorts, includes or pagination. Request bodies are flat JSON objects sent with Content-Type: application/json, and responses are JSON:API documents, described in JSON:API Conventions.

Shipping Options

The shipping options depend on the cart: its zone, the carriers of that zone, the shippable lines and the shipping address. Carriers that quote live rates, such as UPS, FedEx or USPS once their credentials are set, need the shipping address and an inventory location to ship from: until the address is set, they are left out without a warning. The other carriers of the zone offer the options set up for them in the admin panel, at a fixed price. Carriers describes both kinds. List the options after the shipping address is set, so that every carrier can answer.

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

Path parameters

Query parameters

  • fields[shipping-options]stringoptional

    Comma-separated attributes to return, such as name,amount,estimated_days. See Sparse fieldsets.

This request lists the shipping options of the cart, once its shipping address is set:

Request
curl http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/shipping-options \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK with the options and a meta.warnings list:

Response 200
{
    "data": [
        {
            "id": "colissimo:01JD8XM5N7Q9S1T3W5Y7A9C1E3",
            "type": "shipping-options",
            "attributes": {
                "name": "Colissimo Home",
                "carrier_name": "Colissimo",
                "carrier_code": "colissimo",
                "service_code": "01JD8XM5N7Q9S1T3W5Y7A9C1E3",
                "amount": 690,
                "currency": "EUR",
                "price_type": "flat",
                "estimated_days": null,
                "estimated_delivery": null
            }
        },
        {
            "id": "chronopost:01JD8XN8P0R2T4V6X8Z0B2D4F6",
            "type": "shipping-options",
            "attributes": {
                "name": "Chronopost 24h",
                "carrier_name": "Chronopost",
                "carrier_code": "chronopost",
                "service_code": "01JD8XN8P0R2T4V6X8Z0B2D4F6",
                "amount": 1490,
                "currency": "EUR",
                "price_type": "flat",
                "estimated_days": null,
                "estimated_delivery": null
            }
        }
    ],
    "meta": {
        "warnings": []
    }
}

The id of an option is {carrier_code}:{service_code}, the value the storefront sends back to choose it. The options are computed for each request and never stored, so their IDs and prices can change between two calls.

shipping-options attributes

  • namestring

    Name of the service, to show to the customer.

  • carrier_namestring

    Name of the carrier.

  • carrier_codestring

    Slug of the carrier.

  • service_codestring

    Code of the service at the carrier, or the ID of the option for a fixed-price option.

  • amountinteger

    Price of the option, in cents.

  • currencystring

    ISO code of the price, always the cart currency.

  • price_typestring

    flat for a fixed-price option, calculated for a live rate.

  • estimated_daysstring, null

    Delivery time quoted by the carrier, null for a fixed-price option.

  • estimated_deliverystring, null

    Delivery date quoted by the carrier, null for a fixed-price option.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422http_errorThe cart has no zone

The meaning of every code is in Error Codes.

Empty Lists and Warnings

An empty list does not always mean the same thing, and meta.warnings explains most cases. Warnings are sentences meant for a log or a notice, not codes: branch on the options themselves.

SituationOptionsWarning
No line of the cart shipsNoneNone: the cart needs no shipping method
The country of the shipping address is outside the zone of the cartNone"The shipping address is outside the cart zone. Choose the zone of its country."
No inventory location can be the origin of a shipmentFixed-price options only"Live carrier rates are unavailable: no inventory location can act as the shipment origin."
A carrier did not answerThe options of the other carriers"Rates from "UPS" are temporarily unavailable."
A carrier quoted in another currencyThe options in the cart currency"Options priced in USD were removed: the cart is priced in EUR."

A line ships unless it holds a virtual product added as a product, such as an e-book. A variant always counts as shippable, even when its product is virtual. When the shipping address is outside the zone, switch the cart to the zone of that country with zone_code, as described in Cart, and list the options again.

A cart created without a known X-Shopper-Zone header, in an application that sets no shopper.http.zone.default_code, has no zone. Listing its options answers 422 with the generic code http_error and the detail "The cart has no shipping zone, so no shipping option applies to it.": set a zone on the cart first.

Setting the Shipping Method

The storefront sends back the ID of the option the customer picked. The API quotes the options of the cart again and keeps the price of that new quote, so the shipping price always comes from the server.

POST/store/carts/{cartId}/shipping-method
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

  • option_idstring

    The id of a shipping option, such as colissimo:01JD8XM5N7Q9S1T3W5Y7A9C1E3.

This request picks the Colissimo option of the listing above:

Request
curl -X POST http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/shipping-method \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{"option_id": "colissimo:01JD8XM5N7Q9S1T3W5Y7A9C1E3"}'

The API answers 200 OK with the cart. Shipping now shows in shipping_total and in total. The response is trimmed to the totals:

Response 200
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "subtotal": 18000,
            "discount_total": 1800,
            "tax_total": 2700,
            "shipping_total": 690,
            "total": 16890,
            "tax_inclusive": true,
            "shipping_option_id": "colissimo:01JD8XM5N7Q9S1T3W5Y7A9C1E3"
        }
    }
}

An ID that the carriers no longer quote for this cart answers 422 shipping_option_unavailable on /data/attributes/option_id: list the options again. When the carrier of that option failed to answer, the API answers 503 shipping_provider_unavailable with a Retry-After: 5 header instead, since the option may come back.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422shipping_option_unavailableThe carriers no longer quote this option for the cart
422http_errorThe cart has no zone
422Rule name, such as requiredoption_id 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
503shipping_provider_unavailableThe carrier of the option did not answer, 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.

Changing the currency or the zone of the cart removes its shipping method: list the options and set it again after such a change.

Payment Methods

A payment method is the way the customer pays: a card through Stripe, a bank transfer, cash on delivery. The API offers the enabled payment methods of the zone of the cart whose driver is configured, so a Stripe method shows only once its secret key and webhook secret are set. A cart without a zone gets every enabled method with a configured driver. Payment Methods describes how methods are set up and attached to zones.

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

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • fields[payment-methods]stringoptional

    Comma-separated attributes to return, such as title,logo. See Sparse fieldsets.

This request lists the payment methods of the cart:

Request
curl http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/payment-methods \
  -H "Accept: application/vnd.api+json"

The API answers 200 OK with the methods:

Response 200
{
    "data": [
        {
            "id": "01JD8XR3T5V7X9Z1B3D5F7H9K1",
            "type": "payment-methods",
            "attributes": {
                "title": "Credit card",
                "slug": "credit-card",
                "description": "Visa, Mastercard and American Express.",
                "instructions": null,
                "driver": "stripe",
                "logo": "http://localhost:8000/vendor/shopper/images/payments/stripe.svg"
            }
        },
        {
            "id": "01JD8XR3T5V7X9Z1B3D5F7H9K2",
            "type": "payment-methods",
            "attributes": {
                "title": "Bank transfer",
                "slug": "bank-transfer",
                "description": "Pay by bank transfer within 7 days.",
                "instructions": "Transfer the total to IBAN FR76 3000 6000 0112 3456 7890 189 with your order number as the reference.",
                "driver": "manual",
                "logo": "http://localhost:8000/vendor/shopper/images/payments/cod.svg"
            }
        }
    ]
}

The driver tells the storefront which flow to run. A manual method collects offline: it needs no payment session, and its instructions hold what the customer must do, to show on the confirmation page. Any other driver, such as stripe, collects online through a payment session. The logo is the URL of the logo of the driver, the same for every method of that driver, and null for a driver without a logo.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request

The meaning of every code is in Error Codes.

Setting the Payment Method

The storefront sends the ID of the method the customer picked. Ask for the paymentMethod include to get the method back with the cart.

POST/store/carts/{cartId}/payment-method
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

  • payment_method_idstring

    The id of a payment method listed for the cart.

This request picks the credit card method of the listing above, and asks for it back with include=paymentMethod:

Request
curl -X POST "http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/payment-method?include=paymentMethod" \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -d '{"payment_method_id": "01JD8XR3T5V7X9Z1B3D5F7H9K1"}'

The API answers 200 OK with the cart, trimmed here to the total and the method:

Response 200
{
    "data": {
        "id": "01JD8Z6Q4M3K2V7R9T5W1XNB0C",
        "type": "carts",
        "attributes": {
            "currency_code": "EUR",
            "total": 16890
        },
        "relationships": {
            "paymentMethod": {
                "data": { "id": "01JD8XR3T5V7X9Z1B3D5F7H9K1", "type": "payment-methods" }
            }
        }
    },
    "included": [
        {
            "id": "01JD8XR3T5V7X9Z1B3D5F7H9K1",
            "type": "payment-methods",
            "attributes": {
                "title": "Credit card",
                "slug": "credit-card",
                "description": "Visa, Mastercard and American Express.",
                "instructions": null,
                "driver": "stripe",
                "logo": "http://localhost:8000/vendor/shopper/images/payments/stripe.svg"
            }
        }
    ]
}

An ID that matches no enabled payment method answers 422 exists on /data/attributes/payment_method_id. An enabled method that the cart does not offer, because of its zone or an unconfigured driver, answers 422 payment_method_unavailable on the same pointer.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422existsNo enabled payment method has this ID
422payment_method_unavailableThe cart does not offer this method, because of its zone or an unconfigured driver
422Rule name, such as requiredpayment_method_id fails validation
409cart_completedThe cart is already an order
409payment_session_collectedThe customer already paid: the method can no longer change
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.

Changing the method cancels the payment session opened for the previous one at the provider, so the order never holds a payment of another method. Once the customer has paid, the method can no longer change and the API answers 409 payment_session_collected. A zone switch removes the payment method of the cart; a currency switch keeps it.

Opening a Payment Session

The payment provider must collect an amount that the server computed, not the browser. The payment session does that: the API prices the lines again, quotes the shipping method again, computes the total, and opens a payment for that total at the provider of the payment method, such as a Stripe PaymentIntent. The response carries what the provider's browser SDK needs to collect the payment. The request has no body.

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

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • fields[payment-sessions]stringoptional

    Comma-separated attributes to return, such as status,redirect_url. See Sparse fieldsets.

This request opens the payment session of the cart, at the provider of its payment method:

Request
curl -X POST http://localhost:8000/store/carts/01JD8Z6Q4M3K2V7R9T5W1XNB0C/payment-session \
  -H "Accept: application/vnd.api+json"

The API answers 201 Created with the session. With Stripe, its id is the PaymentIntent ID:

Response 201
{
    "data": {
        "id": "pi_3QL2mNLkdIwHu7ix0Ab3Cd4E",
        "type": "payment-sessions",
        "attributes": {
            "driver": "stripe",
            "status": "pending",
            "amount": 16890,
            "currency_code": "EUR",
            "client_secret": "pi_3QL2mNLkdIwHu7ix0Ab3Cd4E_secret_Z8kQw2nV5rT1yH6pL3mX",
            "redirect_url": null,
            "data": {
                "stripe_status": "requires_payment_method",
                "publishable_key": "pk_test_51QJ7xYLkdIwHu7ixT9bWm2Qe",
                "idempotency_key": "cart_01JD8Z6Q4M3K2V7R9T5W1XNB0C_01JD8ZH6K8M0P2R4T6V8X0Z2B4"
            }
        }
    }
}

payment-sessions attributes

  • driverstring

    Driver of the payment method, such as stripe.

  • statusstring

    Status of the payment at the provider: pending, requires_action, processing, authorized, captured or canceled.

  • amountinteger

    Amount to collect, in cents, the total of the cart.

  • currency_codestring

    Currency of the cart.

  • client_secretstring, null

    Secret the provider's browser SDK confirms the payment with.

  • redirect_urlstring, null

    Page of the provider to send the customer to, for a driver that collects on its own page.

  • dataobject, array

    Extra values for the browser: stripe_status, publishable_key and idempotency_key when the driver sets them, an empty array [] when it sets none.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422payment_method_requiredThe cart has no payment method
422price_changedA price went up
422price_missingA line has no price in the cart currency anymore
422quantity_rule_violatedA quantity breaks a rule of its price, details in meta
422shipping_method_requiredThe cart has no shipping method
422shipping_option_unavailableThe shipping option is no longer quoted
422shipping_price_changedThe shipping option costs more
422cart_nothing_to_collectThe total is zero
409conflictThe cart is already an order
409cart_completedThe cart was completed during the call
409payment_session_in_progressAnother request holds the cart, retry after Retry-After
409payment_session_collectedThe payment was collected meanwhile: complete the cart
503payment_method_not_configuredThe driver lost its configuration
503shipping_provider_unavailableThe carrier did not answer, retry after Retry-After
503payment_provider_unavailableThe provider did not answer, retry after Retry-After

The meaning of every code is in Error Codes.

With Stripe, load Stripe.js with data.publishable_key, mount the Payment Element with client_secret and confirm the payment with stripe.confirmPayment(). The Stripe page walks through the browser side, and Payments describes sessions for every driver.

Calling It Again

The storefront can call the endpoint again, for example when the payment page reloads. When the amount, the currency and the promotions of the cart have not changed, the API resumes the open session and answers with the same id and client_secret. A resumed Stripe session carries only stripe_status in data, so keep the publishable key in the storefront configuration as well. Drivers that cannot read a payment back from the provider open a new session on every call.

When the cart changed, the API cancels the open payment at the provider and opens a new one with a new client_secret: mount the payment form again with it. Changing the lines, a promotion code, the currency, the zone or the shipping method also cancels the open session right away. A form that still holds the previous client secret cannot confirm the payment, so open a new session after every change to the cart.

Once the provider has collected the payment (authorized, captured or processing), the API returns that session as it is and the cart is frozen: every change answers 409 payment_session_collected. Complete the cart.

Manual Payment Methods

A method with the manual driver needs no session: complete the cart directly. Opening one anyway answers 201 with a session whose status is authorized and whose id starts with manual_, which collects nothing: its client_secret and redirect_url are null and its data is an empty array.

When the Session Cannot Open

The API checks the cart before it calls the provider. Each failure answers with a code the storefront can act on:

CodeStatusPointerWhat to do
conflict409The cart is already an order: read the order
cart_completed409Same, when the cart was completed during the call
payment_method_required422/data/attributes/payment_methodSet a payment method
payment_method_not_configured503The driver lost its configuration: offer another method
price_changed422/data/attributes/cartA price went up: show the new total, then open the session again
price_missing422/data/attributes/cartA line has no price in the cart currency anymore: remove it
quantity_rule_violated422/data/attributes/cartA quantity breaks a rule of its price, details in meta
shipping_method_required422/data/attributes/shipping_methodSet a shipping method
shipping_option_unavailable422/data/attributes/shipping_methodThe option is no longer quoted: choose another one
shipping_price_changed422/data/attributes/shipping_methodThe option costs more: set the shipping method again to accept the new price
shipping_provider_unavailable503The carrier did not answer: retry after Retry-After (5 seconds)
cart_nothing_to_collect422/data/attributes/cartThe total is zero
payment_provider_unavailable503The provider did not answer: retry after Retry-After (5 seconds)
payment_session_in_progress409Another request holds the cart: retry after Retry-After (3 seconds)
payment_session_collected409The payment was collected meanwhile: complete the cart

A completed cart answers the generic conflict code on this endpoint, where every other endpoint answers cart_completed: treat both the same way. A cart with a total of zero, after a 100% promotion for example, cannot open a session, and completing it with an online method answers payment_session_required: such a cart can only be completed with a manual method.

Completing the Cart

Completing the cart places the order. The API checks the cart one last time, reserves the stock, records the payment session on the order and marks the cart as completed. Call it once the provider has confirmed the payment: with Stripe, on the page Stripe sends the customer back to (return_url). For a manual method, call it when the customer confirms the order.

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

Path parameters

  • cartIdstring

    The cart ID.

Query parameters

  • includestringoptional

    items to return the order items with the order. Other paths are ignored.

  • fields[orders]stringoptional

    Comma-separated attributes to return, such as number,status. See Sparse fieldsets.

This request places the order of the cart, and asks for its items with include=items:

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

The API answers 201 Created with the order, and its items when the request asks for include=items:

Response 201
{
    "data": {
        "id": "01JD8ZM4P6R8T0V2X4Z6B8D0F2",
        "type": "orders",
        "attributes": {
            "number": "ORD-20261119-000042",
            "status": "new",
            "payment_status": "pending",
            "shipping_status": "unfulfilled",
            "total": 16200,
            "tax_amount": 2700,
            "shipping_amount": 690,
            "price_amount": 16890,
            "currency_code": "EUR",
            "created_at": "2026-11-19T10:24:31+00:00"
        },
        "relationships": {
            "items": {
                "data": [
                    { "id": "01JD8ZM4P6R8T0V2X4Z6B8D0F3", "type": "order-items" }
                ]
            }
        }
    },
    "included": [
        {
            "id": "01JD8ZM4P6R8T0V2X4Z6B8D0F3",
            "type": "order-items",
            "attributes": {
                "name": "Classic Leather Sneakers / 42 / Black",
                "sku": "CLS-BLK-42",
                "quantity": 2,
                "unit_price_amount": 9000,
                "total": 16200,
                "metadata": null
            }
        }
    ]
}

Completing a cart that is already completed answers 200 OK with the same order. A storefront that loses the response to a timeout calls the endpoint again and gets the order it placed, never a second one. Keep the order id: the Orders guide reads the order back with it. Only items is loaded on this response; other include paths are ignored here.

orders attributes

  • numberstring

    Order number to show to the customer, from the shopper.orders.generator setting.

  • statusstring

    new when the order is placed.

  • payment_statusstring

    pending until the provider confirms, then authorized, paid, partially_refunded, refunded or voided.

  • shipping_statusstring

    unfulfilled when the order is placed.

  • totalinteger

    Sum of the item totals (unit price times quantity, minus discounts), in cents, without shipping.

  • tax_amountinteger

    Tax of the order, in cents.

  • shipping_amountinteger, null

    Shipping price, in cents.

  • price_amountinteger

    Amount charged, in cents: the total of the cart.

  • currency_codestring

    Currency of the order.

  • emailstring, null

    Contact email of the order.

  • created_atstring

    ISO 8601.

The total of an order is not the total of the cart: the amount the customer pays is price_amount. An order-items resource carries name (the product name, followed by the variant name for a variant), sku, quantity, unit_price_amount, total (unit price times quantity, minus the discount of the item) and metadata, copied from the cart line. Orders describes the statuses.

The email of the order is the email of the cart, or the account email of the customer for a customer cart. A guest cart without an email answers 422 email_required on /data/attributes/email: set it with the addresses or with a cart update.

Errors
StatusCodeWhen
404not_foundNo cart with this ID for this request
422cart_emptyThe cart has no line
422payment_method_requiredThe cart has no payment method
422email_requiredA guest cart has no email
422shipping_method_requiredThe cart has no shipping method
422shipping_option_unavailableThe shipping option is no longer quoted
422shipping_price_changedThe shipping option costs more
422payment_session_requiredAn online payment method has no payment session
422payment_session_mismatchThe cart changed since the session opened
422price_changedA price went up
422price_missingA line has no price
422quantity_rule_violatedA quantity breaks a rule of its price, details in meta
422stock_insufficientNot enough stock for a line
422payment_releasedThe stock ran out after the payment, and the payment was given back
422promotion_not_applicableA promotion of the cart no longer applies
422promotion_limit_reachedA promotion reached its usage limit
422promotion_budget_reachedThe campaign of a promotion spent its budget
409payment_session_in_progressAnother request holds the cart, retry after Retry-After
503shipping_provider_unavailableThe carrier did not answer, retry after Retry-After
503payment_provider_unavailableThe provider did not answer, retry after Retry-After

The meaning of every code is in Error Codes.

Payment Status After Placement

The order starts with payment_status: "pending", and the provider's events, received on the payment webhook, move it. With Stripe, the browser confirms the payment before the storefront completes the cart, so the event often arrives first: the API applies the events that arrived before the order during the complete call, and the response can already show authorized or paid. When shopper.payment.reconciliation.pull_on_completion is on (the default), the API also queues a check of the payment at the provider. A confirmation page shows the order as awaiting payment until the status moves.

An order still unpaid 24 hours after it was placed through an online method is cancelled by the hourly shopper:orders:reclaim command, which cancels the payment at the provider and puts the stock back on sale. The delay is shopper.orders.reclaim_pending_after_hours. Orders paid with a manual method are never cancelled this way.

When the Order Cannot Be Placed

The complete call runs the checks of the payment session again, and adds its own:

CodeStatusPointerWhat to do
cart_empty422/data/attributes/cartAdd a line
payment_method_required422/data/attributes/payment_methodSet a payment method
email_required422/data/attributes/emailSet an email on the cart
shipping_method_required422/data/attributes/shipping_methodSet a shipping method
shipping_option_unavailable422/data/attributes/shipping_methodChoose another shipping option
shipping_price_changed422/data/attributes/shipping_methodSet the shipping method again to accept the new price
shipping_provider_unavailable503Retry after Retry-After (5 seconds)
payment_session_required422/data/attributes/payment_sessionOpen a payment session first
payment_session_mismatch422/data/attributes/payment_sessionThe cart changed since the session opened: open a new session and pay again
price_changed422/data/attributes/cartA price went up: show the new total
price_missing422/data/attributes/cartRemove the line that has no price
quantity_rule_violated422/data/attributes/cartFix the quantity, details in meta
stock_insufficient422/data/attributes/cartLower the quantity or remove the line
payment_released422/data/attributes/cartThe stock ran out after the payment: the payment was given back, update the cart and pay again
promotion_not_applicable422/data/attributes/promotionA promotion of the cart no longer applies: show the new total
promotion_limit_reached422/data/attributes/promotionA promotion reached its usage limit
promotion_budget_reached422/data/attributes/promotionThe campaign of a promotion spent its budget
payment_session_in_progress409Retry after Retry-After (3 seconds)
payment_provider_unavailable503Retry after Retry-After (5 seconds)

The three promotion errors cancel the open payment session, so the storefront opens a new one for the new total before it completes the cart again.

Price, Stock and Shipping Changes

Time passes between the basket and the payment: a price changes in the admin panel, the last pair sells, a carrier raises a rate. The API checks the cart when the payment session opens and when the cart completes, and never charges more than the customer saw without telling the storefront first.

ChangeOpening the payment sessionCompleting the cart
A price went upThe cart takes the new price, then 422 price_changedThe cart takes the new price, then 422 price_changed
A price went downThe cart takes the new priceThe cart takes the new price
The stock ran outNot checked422 stock_insufficient, or 422 payment_released when the payment was collected
The shipping price went up422 shipping_price_changed422 shipping_price_changed
The shipping price went downThe cart takes the new priceThe cart takes the new price
The shipping option is gone422 shipping_option_unavailable422 shipping_option_unavailable

On price_changed, the cart already holds the new prices: read it again, show the new total to the customer, and open the payment session again once they accept it. On shipping_price_changed, the cart keeps the old shipping price until the storefront sets the shipping method again.

Once the provider has collected the payment, the order keeps what the customer paid for: the API honors the paid prices and the paid shipping price, and a price change no longer blocks the order. Missing stock still does, and the API then gives the payment back before it answers payment_released.

Retries, Idempotency and Locking

Checkout calls reach the payment provider and the carriers, can time out, and can race: a double click, two tabs, a retry. The API holds one lock per cart, so these calls run one at a time and a retry is always safe.

Setting the shipping method, setting the payment method, opening the payment session, completing the cart and every change to the lines, addresses, promotions, currency or zone of the cart hold the lock of the cart while they run. A call that waits more than 3 seconds for it answers 409 payment_session_in_progress with Retry-After: 3. A provider or a carrier that does not answer gives 503 with Retry-After: 5. Retry the same call after the delay.

Each new payment session opens at the provider under its own idempotency key, cart_{cartId}_{ulid}, which Stripe sessions return in data.idempotency_key, and the payment carries the cart ID in its cart_id metadata. Completing the cart is idempotent, as Completing the cart explains.

A customer can pay and close the tab before the storefront completes the cart. The scheduled shopper:payments:reconcile command, which runs every 15 minutes, finds payments collected without an order after 30 minutes (shopper.payment.reconciliation.orphan_after_minutes) and completes their cart, as described in Orphaned Payments. The storefront still completes the cart itself: the command is a safety net.

Payment Webhooks

The provider reports the outcome of each payment to Shopper through webhooks: authorized, captured, failed, refunded. The payment status of the order follows those events, so the storefront never reports a payment result itself. Register the route of the driver in the provider's dashboard, such as https://shop.example.com/store/webhooks/stripe for Stripe, with the events listed in Handled Events.

POST/store/webhooks/{driver}
Auth
Provider signature, checked by the driver

Path parameters

  • driverstring

    Code of a registered and configured payment driver, such as stripe.

The webhook routes sit in their own route group, without authentication, limited to 120 requests per minute per IP address. The driver checks each request, such as the Stripe-Signature header against the webhook secret, then Shopper records the event once by its provider event ID, so a redelivered event is never applied twice. An event that arrives before the order exists waits until the cart is completed.

Request
curl -X POST http://localhost:8000/store/webhooks/stripe \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  -H "Stripe-Signature: t=1763547871,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" \
  --data-binary @stripe-event.json

The route answers 200 OK, also for an event the driver ignores:

Response 200
{
    "received": true
}

A payload the driver rejects, such as one with an invalid signature, answers 400 Bad Request with a plain error body, not a JSON:API error object:

Response 400
{
    "error": "Invalid webhook payload."
}
Errors
StatusCodeWhen
400None, plain bodyThe driver rejects the payload, such as an invalid signature
404not_foundThe driver is not registered or not configured

The meaning of every code is in Error Codes.

A driver that is not registered, or not configured, answers 404. Payments describes how Shopper applies the events.

Shipping Webhooks

The /store/webhooks/shipping/{driver} route receives tracking updates pushed by a carrier and applies them to the shipment. It answers only for a carrier driver that supports webhooks. None of the bundled carriers (manual, UPS, FedEx, USPS) does, so for them the route answers 404, and tracking comes from the scheduled shopper:shipments:sync-tracking command, every 30 minutes while shopper.shipping.tracking.sync is on. The route returns the same 200, 400 and 404 answers as the payment webhooks. Carrier Tracking describes how tracking reaches the order, and Carriers how to add a carrier driver.

POST/store/webhooks/shipping/{driver}
Auth
Provider signature, checked by the driver

Path parameters

  • driverstring

    Code of a registered and configured carrier driver whose supportsWebhooks() returns true.

This request posts a tracking update to dhl, a driver of your own registered as in Custom Shipping Drivers, whose supportsWebhooks() returns true. The body is the payload of the carrier, in its own format: the handleWebhook() method of the driver checks that the carrier sent it and reads the tracking update, as Driver Capabilities describes.

Request
curl -X POST http://localhost:8000/store/webhooks/shipping/dhl \
  -H "Accept: application/vnd.api+json" \
  -H "Content-Type: application/json" \
  --data-binary @dhl-tracking-update.json

The route answers 200 OK once the driver has read the payload, also when it carries nothing to record:

Response 200
{
    "received": true
}

A payload the driver rejects answers 400 Bad Request with the same plain error body as the payment webhooks:

Response 400
{
    "error": "Invalid webhook payload."
}

A driver that is not registered, not configured or without webhook support, such as the bundled manual driver, answers 404 with a JSON:API error object:

Response 404
{
    "errors": [
        {
            "status": "404",
            "code": "not_found",
            "title": "Not Found",
            "detail": "Not Found"
        }
    ]
}
Errors
StatusCodeWhen
400None, plain bodyThe driver rejects the payload, such as a failed signature check
404not_foundThe driver is not registered, not configured or does not support webhooks, as for every bundled driver

The meaning of every code is in Error Codes.

Errors

Errors use the JSON:API error object, with a code a client can branch on, described with every code in Error codes. Validation errors put the field in source.pointer, such as /data/attributes/option_id, even though request bodies are flat JSON. On top of 401 unauthenticated for a token without the store ability, 404 not_found for an unknown cart or a customer cart requested without its owner's token, and 429 rate_limited, the checkout endpoints answer with these codes:

EndpointCodes
List the shipping optionshttp_error (422, no zone)
Set the shipping methodrequired, shipping_option_unavailable, shipping_provider_unavailable, http_error, cart_completed, payment_session_collected, payment_session_in_progress, payment_provider_unavailable
List the payment methodsNone beyond the common ones
Set the payment methodrequired, exists, payment_method_unavailable, cart_completed, payment_session_collected, payment_session_in_progress, payment_provider_unavailable
Open the payment sessionThe codes of When the session cannot open
Complete the cartThe codes of When the order cannot be placed

Next Steps

The cart is now an order. The orders guide reads it back for the confirmation page and lists the orders of a customer, and the customers guide covers accounts and the transfer of a guest cart.

Last updated on

Edit on GitHub