Skip to main content
POST
Complete Checkout

Headers

X-Site-ID
string
required
X-Stella-Token
string | null
Idempotency-Key
string | null

Path Parameters

checkout_id
string<uuid>
required

Body

application/json

Storefront checkout completion request — Phase 8-B.

Phase 4-A's freeform payment_method: str is replaced by a Literal-restricted method discriminator. The PaymentMethodHandler registry routes the body to the matching handler. Stripe still arrives via the webhook for buyer-Stripe-Element flows; this route is for COD + (future PR-C) bank transfer + back-compat callers that explicitly know their PI.

Field rules per method:

  • stripepayment_intent_id required.
  • codcod block populated; phone required at API time when CodConfig.require_phone=true.
  • bank_transferbank_transfer_reference optional. Wired in PR-C; this route 422s today via the handler's NotImplementedError.
payment_method
enum<string>
required
Available options:
stripe,
cod,
bank_transfer
payment_intent_id
string | null
cod
CodSubmission · object | null

Buyer-supplied COD details. Phase 8-B accepts these but only phone and accepted_terms are checked at the API edge today — OTP wiring is Phase 8 Decision 3 (deferred).

bank_transfer_reference
string | null

Response

Successful Response

Schema for checkout response.

id
string<uuid>
required
cart_id
string<uuid>
required
email
string
required
shipping_address
AddressSchema · object
required

Schema for address. Fields are optional to support simpler address formats from AI widget.

billing_address
AddressSchema · object
required

Schema for address. Fields are optional to support simpler address formats from AI widget.

items
CartItemResponse · object[]
required
subtotal
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
tax_amount
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
shipping_amount
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
total
string
required
Pattern: ^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$
currency
string
required
status
string
required
created_at
string<date-time>
required
updated_at
string<date-time>
required
payment_intent_id
string | null
order_id
string<uuid> | null
completed_at
string<date-time> | null