Checkout and orders

Checkout turns a ready cart into an order. Your storefront sets up the payment with the store's own Stripe or PayPal account, the shopper pays in the provider's own form, and one call places the order. With an Idempotency-Key, that call can be retried safely and still places exactly one order.

Before you startCopy Anchor Link

A cart is ready for checkout when it has at least one line, a billing address, and, if anything in it ships, a shipping address and a chosen shipping option. See carts. A cart that is not ready is refused with 422 VALIDATION_FAILED.

The stepsCopy Anchor Link

{
  "data": {
    "gateways": ["stripe", "paypal"],
    "currency": "GBP",
    "country": "GB",
    "gateway_mode": "live",
    "stripe_publishable_key": "pk_live_…",
    "stripe_capture_method": "manual",
    "paypal_client_id": "AX…"
  }
}

curl -X POST https://api.elaraone.app/api/v1/checkout/complete \
  -H "X-Tenant-Key: $ELARAONE_TENANT_KEY" \
  -H "X-Tenant-Secret: $ELARAONE_TENANT_SECRET" \
  -H "X-Cart-Token: $CART_TOKEN" \
  -H "Idempotency-Key: 9b2c6f0e-4a7d-4c1e-9f3b-2d8a5e7c1b04" \
  -H "Content-Type: application/json" \
  -d '{ "payment": { "gateway": "stripe", "payment_intent": "pi_3QxYz…" } }'

For PayPal, the body of POST /v1/checkout/paypal/capture is { "paypal_order_id": "5O190127TN364715T" }. POST /v1/checkout/complete also accepts { "payment": { "gateway": "paypal", "paypal_order_id": "…" } }.

The orderCopy Anchor Link

{
  "data": {
    "id": 3051,
    "reference": "00003051",
    "status": "payment-received",
    "status_label": "Payment Received",
    "placed_at": "2026-10-24T10:12:31+00:00",
    "dispatched_at": null,
    "delivered_at": null,
    "cancelled_at": null,
    "lines": [
      {
        "id": 9120,
        "type": "physical",
        "description": "Linen cushion",
        "identifier": "CUSH-LIN-NAT",
        "option": null,
        "quantity": 2,
        "unit_price": { "amount": 3400, "currency": "GBP", "formatted": "£34.00" },
        "total": { "amount": 6800, "currency": "GBP", "formatted": "£68.00" }
      }
    ],
    "shipping_method": { "identifier": "standard", "name": "Standard delivery", "kind": "delivery", "collection_location": null },
    "shipments": [],
    "sub_total": { "amount": 6800, "currency": "GBP", "formatted": "£68.00" },
    "shipping_total": { "amount": 495, "currency": "GBP", "formatted": "£4.95" },
    "tax_total": { "amount": 1216, "currency": "GBP", "formatted": "£12.16" },
    "total": { "amount": 7295, "currency": "GBP", "formatted": "£72.95" }
  },
  "meta": {
    "order_access_token": "eyJ…",
    "order_access_token_expires_at": "2026-10-24T11:12:31+00:00"
  }
}

After a successful checkout the cart token stops working (404 CART_NOT_FOUND). Create a new cart for the shopper's next order. The store's order confirmation email is sent automatically, if the store has it switched on.

Exactly onceCopy Anchor Link

Send an Idempotency-Key on POST /v1/checkout/complete and POST /v1/checkout/paypal/capture. If the response is lost (a timeout, a dropped connection, a double click), retry with the same key and the same body:

• if the first request placed the order, you get the same 201 back, with Idempotent-Replayed: true, and no second order is created;
• if the first request is still running, you get 409 IDEMPOTENCY_IN_PROGRESS; wait a moment and retry with the same key;
• if the first request failed, the retry runs again, so a shopper who fixes their card can pay with the same key.

A PayPal capture is recorded before the order is placed, so a retry never captures the payment twice. See idempotency keys.

What can go wrongCopy Anchor Link

SHIPPING_OPTION_CHANGED can also come back from POST /v1/checkout/payment-intent and POST /v1/checkout/paypal/order: the engine checks the shipping price before any payment is set up.

Order statesCopy Anchor Link

Branch on status, which never changes meaning, and show status_label, which is the store's own wording. dispatched_at, delivered_at and cancelled_at are filled in when the order reaches that state, and shipments lists the parcels with their carrier and tracking details once the order is dispatched. A cancelled order's stock is put back.

Guest ordersCopy Anchor Link

A guest has no account, so a guest order comes with a short-lived access token in meta.order_access_token, and meta.order_access_token_expires_at says when it stops working. Use it straight away to show the confirmation page:

curl https://api.elaraone.app/api/v1/orders/guest/00003051 \
  -H "X-Tenant-Key: $ELARAONE_TENANT_KEY" \
  -H "X-Tenant-Secret: $ELARAONE_TENANT_SECRET" \
  -H "X-Order-Access-Token: $ORDER_ACCESS_TOKEN"

To let a guest look up an order later, ask for the order reference and the email used at checkout, and call POST /v1/orders/lookup:

{ "reference": "00003051", "email": "[email protected]" }

It returns the order and a fresh meta.order_access_token. A reference and email that do not match return 404. Lookups share the sign-in rate limit (10 a minute per store and IP), because a reference and email together act like a password.

A missing, tampered or expired access token returns 403 ORDER_ACCESS_TOKEN_INVALID. details.reason is expired (ask for the email again) or invalid.

Signed-in customers see their orders with GET /v1/orders and GET /v1/orders/{reference}. See customers.