Process

Upsert a shopping cart (store/{sid}/carts/{cart}). Carts are deliberately inert: no triggers, no hooks, no stock interaction - one document write per call. Omit cart to create (a new id is returned - keep it client-side, e.g. localStorage). Provided fields overwrite (the items map wholesale - send the full desired map); absent fields survive. Every set restamps expires (now + setup/order.cart_ttl_days, default 30 d) - Firestore TTL garbage-collects stale carts. Callers on an identity-token are forced to their own customer id as the cart id (and uid). Check out with order/make {cart}.

Parameters

Response

object — Returns the stored cart including its id and the computed expires stamp.

Sample request

{
  "items": {
    "tshirt-blue": 2,
    "mug-white": 1
  },
  "locale": "en_US",
  "email": "customer@example.com"
}

Omit cart to create a new cart (its id is returned - keep it client-side). items replaces the stored map wholesale, so always send the full map.

Read a cart by id. Identity-token callers read their own cart (the id is forced to the identity's customer).

Parameters

Response

object — Returns the cart document. 404 when it does not exist (expired carts are TTL-deleted).

Sample request

{
  "cart": "cart_123"
}

Delete a cart by id (e.g. after an anon-to-login merge). Identity-token callers delete their own cart. Deleting a missing cart succeeds (idempotent).

Parameters

Response

object — Returns {id, deleted}.

Sample request

{
  "cart": "cart_123"
}

Operations that needs to process input request. Should be exclusively used on backend.

When dealing with async mode it's recommended to implement custom pipeline with create/update endpoints. Buyers vs staff - staff is a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders; every identity-token caller and every other role (service tokens, tenant serving tokens, module tokens) is a buyer. A buyer may not send payment personal (400 payment_method_unavailable), a status other than cart/open, finalize or number (403 order_field_forbidden); a buyer's order must already exist (404 order_not_found), be cart/open/none and be its own (403 order_not_editable). An identity token (or a token carrying a customer) always acts as its own customer - user is overwritten. Refusals happen before anything is written.

Parameters

Response

object — Returns payment intent or state of the order - based on input params.\nWhen any item is out of stock, then whole order is denied.

Sample request

{
  "items": {
    "tshirt-blue": 2
  },
  "user": "user_123",
  "payment": "stripe_checkout",
  "locale": "en_US"
}

Pass cart instead of items to check out a cart created with cart/set. With a Stripe payment method the returned order carries the payment intent or checkout session to continue with.

Create a subscription order. Same contract as order/make, but the payment defaults to stripe_subscription and the order starts as cart (stock preview). Items must reference products with a subscription interval; the Stripe Checkout Session URL surfaces as payment.service_intent.session on the returned order - redirect the customer there.

Same buyer/staff rules as order/make - staff is a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders. A buyer (identity tokens and every other role) gets 400 payment_method_unavailable for payment personal, 403 order_field_forbidden for finalize, number or a status other than cart/open, 404 order_not_found / 403 order_not_editable for an order id that is unknown or not its own open order. user is forced to the identity's (or the token's) customer.

Parameters

Response

object — Returns the order with payment.service_intent.session (the Stripe Checkout URL).

Sample request

{
  "items": {
    "plan-pro": 1
  },
  "user": "user_123"
}

Replace an existing order's item map. The supplied items object overwrites the order's current one wholesale - send the full desired map, not a delta. The order's status is NOT checked and totals/stock are NOT recomputed by this call, so re-run order/make against the same order afterwards to re-price and re-reserve.

Staff only - a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders; every other caller (identity tokens, service / serving / module tokens) gets 403 staff_only (a buyer edits its own cart-state order through order/make with order). An unknown order is 404 order_not_found - nothing is created.

Parameters

Response

object — Returns result of write operation (confirmation).

Sample request

{
  "order": "ord_123",
  "items": {
    "tshirt-blue": 3,
    "mug-white": 1
  }
}

Close an order (status closed). When order is closed, any pending payment is canceled - but not refunded.

Staff (a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders) close any existing order. An identity-token caller may close only its own order (else 403 order_not_editable) while it is unpaid and at most confirmed (else 409 order_not_cancellable with reason paid or status). Every other caller (service / serving / module tokens) gets 403 staff_only - abandoned unpaid orders are closed by the hourly sweeper. An unknown order is 404 order_not_found - nothing is created.

Parameters

Response

object — Returns {id, status closed}.

Sample request

{
  "order": "ord_123"
}

Cancel a Stripe subscription - by its id or by the order it belongs to. The subscription must belong to the store (checked against the provider's subscription record). Already-canceled subscriptions are a no-op.

Staff (a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders) cancel any of the store's subscriptions. An identity-token caller may cancel only its own - the subscription's order must be the identity customer's (else 403 order_not_editable). Every other caller (service / serving / module tokens) gets 403 staff_only.

Parameters

Response

object — Returns {sub, status, cancel_at_period_end}.

Sample request

{
  "order": "ord_123",
  "at_period_end": true
}

Staff only - a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders; every other caller (identity tokens included) gets 403 staff_only before anything is read.

Parameters

Response

object — Returns the subscription id and its resulting discount.

Sample request

{
  "store": "my-store",
  "order": "xrmgetVCMCbDOSWPpgqX",
  "batch": "SUMMER25"
}

Grants a discount on an EXISTING subscription - the checkout only attaches one at creation. The discount comes from the store's own coupon batch; it replaces any existing discount rather than stacking, so re-running is idempotent.

Buyers vs staff (see order/make) - staff is a master token, or an owner/editor token whose scope is absent or writes store/{sid}/orders. For a buyer the effective service (service, else the store's default payment method) may not be personal (400 payment_method_unavailable); the order must be open or confirmed and not already paid (409 order_not_payable); an identity-token caller may pay only its own order (403 order_not_editable). user is forced to the caller's own customer (and customer is ignored) for identity tokens and tokens carrying a customer.

Parameters

Response

object — Returns payment intent.

Sample request

{
  "order": "ord_123",
  "service": "stripe_checkout",
  "callbacks": {
    "success_url": "https://shop.example.com/thank-you",
    "cancel_url": "https://shop.example.com/cart"
  }
}

Returns payment methods for given user and Intent to initialize new method.

Parameters

Response

object — Returns available payment methods.

Sample request

{
  "user": "user_123",
  "type": "cards"
}

Create a Stripe CustomerSession for the Payment Element so it can show the user's saved payment methods plus a save/remove UI (saved cards are charged off_session later). Returns the session client secret for stripe.elements({customerSessionClientSecret}).

Parameters

Response

object — Returns { customer, secret } - the Stripe customer id and the CustomerSession client secret.

Sample request

{
  "user": "user_123"
}

Read a payment back - the return leg of a checkout. By event (a Stripe payment id) or by order. For an order paid through a module gateway (payment.service = module:{id}, .dev/plans/invoice-providers.md G4) the gateway is asked once (payment.status) and its answer is applied through the one state writer before it is returned as {provider, state}; a gateway that cannot answer is 502 module_failed and nothing is applied. A bank-transfer order (.dev/plans/proforma-invoices.md) answers {status, transfer} - transfer is {pending: true} while its proforma is being issued, then {number, status, url?, account?, iban?, iban_print?, vs, amount, currency, due, spayd} (the QR Platba payload).

Parameters

Response

object — The stored payment object (Stripe), or {provider: 'module:{id}', state: {status, amount, currency, ...}} for a module gateway's payment.

Sample request

{
  "order": "ord_123"
}

Parameters

Response

object — Returns result of the operation.

Sample request

{
  "user": "user_123",
  "method": "pm_1AbCdEfGhIjKlMnO"
}

Parameters

Response

object — Returns link to onboarding or already connected account.