Checkout

POST /api/v1/store/checkout is the one-shot endpoint that turns a cart into a real order, decrements inventory, dispatches notifications, and returns the order summary.

Convert cart to order

POST /api/v1/store/checkout

Headers

X-Sellvik-Key: <publishable-key> (required)
X-Sellvik-Cart: <cart-token> (required for guest checkout)
Authorization: Bearer <customer-jwt> (required for customer checkout)

Either the cart token or the customer JWT must identify a non-empty cart.

Request body

{
  "shippingAddress": {
    "name": "Rafiul Hassan",
    "phone": "+8801711000000",
    "addressLine1": "House 12, Road 5",
    "addressLine2": "Block C",
    "city": "Dhaka",
    "district": "Dhaka",
    "postalCode": "1212",
    "country": "BD"
  },
  "billingAddress": null,
  "paymentMethod": "COD",
  "couponCode": "WELCOME10",
  "shippingZoneId": "sz_inside_dhaka",
  "customerNote": "Please call before delivery."
}

Field	Type	Required	Notes
`shippingAddress`	object	yes	See below.
`billingAddress`	object \| null	no	Defaults to shipping if omitted/null.
`paymentMethod`	`"COD"` \| `"BKASH"` \| `"NAGAD"` \| `"CARD"`	yes	Cash-on-delivery is always available.
`couponCode`	string \| null	no	Applied if valid; ignored if not.
`shippingZoneId`	string	yes	From the shop's published shipping zones.
`customerNote`	string \| null	no	Up to 500 chars.

`shippingAddress` shape

Field	Type	Required
`name`	string	yes
`phone`	string (E.164)	yes
`addressLine1`	string	yes
`addressLine2`	string \| null	no
`city`	string	yes
`district`	string	yes
`postalCode`	string \| null	no
`country`	ISO 3166-1 alpha-2	yes (currently `"BD"` only)

Response

HTTP/1.1 201 Created

{
  "id": "ord_a1b2c3...",
  "orderNumber": "ACME-1042",
  "status": "PENDING",
  "subtotal": "2980.00",
  "shippingCost": "60.00",
  "discountAmount": "298.00",
  "total": "2742.00",
  "paymentMethod": "COD",
  "items": [
    {
      "id": "oi1b2c3d-...",
      "productId": "f3a7...",
      "variantId": null,
      "name": "Emerald Kurti",
      "quantity": 2,
      "price": "1490.00",
      "total": "2980.00"
    }
  ]
}

Side effects

Order created with status PENDING.
Inventory decremented atomically. If any line goes below zero, the entire checkout fails with 409 out_of_stock and no state changes.
Cart deleted.
order.created webhook dispatched (see Webhooks).
Order-confirmation email + SMS sent if the shop has those configured.
For COD, no payment processing happens — the order moves to CONFIRMED when a merchant confirms it in the panel.

Errors

Status	Code	When
400	`invalid_body`	Missing or malformed fields.
400	`empty_cart`	Cart has no items.
400	`invalid_shipping_zone`	`shippingZoneId` doesn't exist for this shop.
400	`invalid_coupon`	Coupon code doesn't exist, is expired, or doesn't apply.
409	`out_of_stock`	A line item lacks stock at checkout time. The body lists which.
409	`cart_locked`	Concurrent checkout in flight. Wait and retry.

Order status lifecycle

The status field can be:

PENDING → CONFIRMED → PROCESSING → SHIPPED → ON_THE_WAY → DELIVERED
                                                       ↘ CANCELLED, REFUNDED, DISPUTED, ON_HOLD

Storefront customers can observe status via Customer profile → Orders. Real-time updates come via webhooks.

On this page