Checkout

How checkout works — cart, coupons, delivery, and placing an order with StoreOS.

What checkout is

Checkout is when a customer turns their cart into a real order on StoreOS. Your app owns the cart UI and checkout form; StoreOS validates inventory, applies coupons, calculates delivery, and creates the invoice.

Cart (your app)  →  verifyCoupon (optional)  →  createOrder  →  Order on StoreOS

Who does what

Step	Your app	StoreOS API
Cart items	Track productId, variantId, qty	—
Shipping form	Collect address, delivery area	—
Delivery fee	Display total	`getTenant()` → `charges`
Coupon field	UI + apply button	`verifyCoupon`
Place order button	Submit	`createOrder`
Confirmation page	Show `invoiceUID`	Returns order object

Flow

Shipping address — caption, latitude, longitude (location reference)
Delivery area — e.g. DHAKA or OUTSIDE_CAPITAL (affects fee)
Delivery charge — read from tenant.charges via getTenant()
Coupon (optional) — verifyCoupon with code + line items
Payment method — COD (cash on delivery) or ONLINE
createOrder — submits everything to StoreOS
Redirect — /order-confirmation/[invoiceUID]

Cart (your app or React SDK)

StoreOS has no cart API on the server. Keep items until checkout:

// Example cart item shape — matches createOrder input
{ productId: "…", variantId: "…", quantity: 2 }

Persist in React state, localStorage, or your state library — or use useCart from the React SDK, which stores the cart in localStorage for you.

SDK example

import { store } from "@/lib/store";

// 1. Load delivery rules
const tenant = await store.getTenant();

// 2. Verify coupon (optional)
const coupon = await store.verifyCoupon({
  code: "SAVE10",
  lineItems: cartItems,
});

// 3. Place order
const { order, authToken } = await store.createOrder({
  lineItems: cartItems,
  shippingAddress: {
    caption: "House 12, Road 5, Dhaka",
    latitude: 23.8103,
    longitude: 90.4125,
  },
  paymentMethod: "COD",
  deliveryArea: "DHAKA",
  couponCode: coupon.valid ? "SAVE10" : undefined,
});

// 4. Redirect — order.invoiceUID is the public order ID
router.push(`/order-confirmation/${order.invoiceUID}`);

Guest vs logged-in

Customer	What to do
Guest	Call `createOrder` without a token; pass name/phone in order input if required
Logged in	`store.setAccessToken()` before checkout — order links to their account
Guest after order	API may return `authToken` — SDK saves it for `getOrder()` tracking

Payment methods

Value	Meaning
`COD`	Cash on delivery — no payment gateway needed
`ONLINE`	Online payment — your app integrates the payment provider