Cart & checkout

There are two cart APIs: the cookie-backed facade on the Next.js / browser clients (no cart id), and the explicit core-client methods (you pass the cart id). Both are shown below.

No cart id needed; it's tracked in a cookie. Mutations need a Server Action / Route Handler on the server (see Next.js adapter).

await storekit.cart.current();              // Cart | null
await storekit.cart.count();                // number
await storekit.cart.add({ variantId, quantity: 1, modifiers });
await storekit.cart.setQuantity(lineId, 3); // qty ≤ 0 removes the line
await storekit.cart.remove(lineId);
await storekit.cart.clear();

In the browser, prefer the useCart() hook so shared state stays in sync.

cart — explicit (core client)

Address lines by their line id (cart.items[].id), not the variant id.

Method	Description
`cart.create(input, options?)`	Create a cart. Merges into the customer's cart when authenticated.
`cart.get(cartId, options?)`	Fetch a cart by id.
`cart.me(options?)`	The authenticated customer's active cart.
`cart.update(cartId, input, options?)`	Replace all items (full replace).
`cart.delete(cartId, options?)`	Delete a cart.
`cart.claim(cartId, options?)`	Merge a guest cart into the customer's cart.
`cart.addItem(cartId, item, options?)`	Add an item; merges into a matching line.
`cart.setQuantity(cartId, lineId, qty, options?)`	Set a line's quantity.
`cart.removeItem(cartId, lineId, options?)`	Remove a line.

const { data: cart } = await client.cart.create({
  items: [{ variantId, quantity: 1 }],
});
await client.cart.addItem(cart.id, { variantId: other, quantity: 2 });

A CartItemInput is { variantId, quantity, modifiers? } where modifiers is Record<groupId, modifierId[]>.

checkout

checkout.create(input, options?)

Create an order + payment intent. Requires a logged-in customer. Returns a redirectUrl for the payment provider.

const { data, error } = await storekit.checkout.create({
  orderType: "delivery",            // "delivery" | "pickup" | "dine_in"
  shipping: { firstName, address, city, state, zipCode, country },
  couponCode: "WELCOME10",          // optional
  notes: "Ring the bell",           // optional, ≤ 500 chars
  scheduledFor: new Date("..."),    // optional
  // idempotencyKey is auto-generated if omitted
});
// data → { orderId, status: "pending", redirectUrl, paymentIntent }

See Carts & checkout for the error codes (INSUFFICIENT_STOCK, STALE_CHECKOUT, COUPON_*, …).

checkout.confirm(orderId, options?)

Reconcile payment after the provider redirect.

const { data } = await storekit.checkout.confirm(orderId);
// data → { success, status, order, error? }

Safe to call repeatedly. In React, prefer usePaymentConfirmation().

coupons

coupons.validate(input, options?)

Validate a coupon against the customer's cart.

const { data, error } = await storekit.coupons.validate({ code: "WELCOME10" });
if (data?.valid) {
  // { valid: true, code, discount, couponId }
} else if (data) {
  // { valid: false, reason }
}

Not an error

An invalid coupon returns data.valid === false (HTTP 200) — not an error. The error channel is only for auth/empty-cart style failures.