Storefront API · Checkout

Place the order

POSThttps://{store}/api/v1/checkout

Checks the whole cart again (stock, prices, delivery, the store’s rules) and places the order. Send the sums the buyer saw: when the cart changed meanwhile, the answer is 422 and nothing is charged.

redirect_url is the payment provider’s page: send the buyer there; card data never passes through your app. It accepts payment for 30 minutes. Without redirect_url the order is already placed (cash on delivery, for example).

The same Idempotency-Key returns the same order instead of a second one, even after a dropped connection. A key used for another cart or sum answers 422 idempotency_key; use a new key for a new attempt.

Cart token from POST /carts: X-Cart-Token: {token}.

Idempotent. Needs an Idempotency-Key header: repeating the key returns the first response.

Request body application/json

expected_subtotalintegerrequired

Subtotal the buyer saw (totals.subtotal), minor units.

expected_totalintegerrequired

Total the buyer saw (totals.total), minor units.

payment_driverstring

Payment method; the store’s default when left out.

payment_tokenstring

Only for payment methods that need it.

contact_emailstring

E-mail for the order; taken from the shipping address when left out.

notesstring

Buyer’s comment, up to 1000 characters.

marketing_opt_inboolean

true asks for a newsletter subscription (confirmed by e-mail).

Example

{
    "expected_subtotal": 599900,
    "expected_total": 599900,
    "contact_email": "[email protected]",
    "notes": "Подзвоніть перед відправкою"
}

Responses

201The order; redirect_url when the buyer pays online.

{
    "data": {
        "id": "101",
        "reference": "2026-001045",
        "status": "awaiting-payment",
        "placed_at": null,
        "payment_driver": "app:com.storeforma.wayforpay",
        "redirect_url": "https://your-store.storeforma.shop/payments/8b1e…/start"
    }
}

422The cart changed, an item ran out, delivery is no longer available, or the key was used for another order.

{
    "message": "Сума кошика змінилася.",
    "errors": {
        "checkout": [
            "Сума кошика змінилася. Перевірте кошик і спробуйте ще раз."
        ]
    }
}

401No X-Cart-Token, an expired token, or a cart that is already ordered.

{
    "message": "A valid X-Cart-Token header is required.",
    "errors": {
        "cart_token": [
            "Кошик не знайдено, строк доступу минув або його вже оформлено."
        ]
    }
}

429Too many requests (cart creation 20/min per IP, cart calls 120/min, checkout 10/min).

{
    "message": "Too Many Attempts."
}