Payments (Stripe)

The boilerplate is quote-first: shoppers browse, add to cart, and submit a quote request — no payment required. Stripe Checkout is an optional, env-gated layer on top. Set STRIPE_SECRET_KEY and a real "Checkout" button appears next to the quote flow; leave it unset and the store behaves exactly as before.

How the store decides whether to show Checkout

The client never assumes Stripe is on. The cart asks the server first, via GET /api/checkout/config, which returns a single boolean:

{ "enabled": true }

enabled is simply Boolean(process.env.STRIPE_SECRET_KEY) — it never exposes the key or any other secret:

export function isStripeEnabled(): boolean {
  return Boolean(process.env.STRIPE_SECRET_KEY);
}

When enabled is false, the cart renders only the quote flow and the Checkout button does not appear.

Creating a Checkout Session

POST /api/checkout turns a cart into a Stripe Checkout Session and returns the hosted-page URL to redirect to.

Request

{
  "items": [
    { "id": "prod_abc", "quantity": 2 },
    { "id": "prod_xyz", "quantity": 1, "variantId": "var_red_m" }
  ],
  "customerId": "firebase-uid-optional"
}

The body is validated with Zod; anything outside these bounds returns 400 Invalid request body, and a non-JSON body returns 400 Invalid JSON body.

Prices are never trusted from the client

The request carries only ids, quantities, and an optional variant id — no prices. For each line the server re-fetches the product from Firestore and resolves the price and stock itself (src/lib/checkout-line.ts):

const snapshot = await getDoc(doc(db, "products", item.id));
if (!snapshot.exists()) {
  return NextResponse.json(
    { error: `Product ${item.id} was not found.` },
    { status: 400 }
  );
}
const resolved = resolveCheckoutLine(snapshot.data(), item);

resolveCheckoutLine treats every Firestore field as untrusted and applies these rules:

• Price comes from the product's stored price. When a variantId is present the variant's own price overrides it (falling back to the product price when the variant has none).
• Missing/invalid price (not a finite number > 0) resolves to an error: "<name>" has no price — request a quote for it instead. Such products can only go through the quote flow.
• Variant not found returns Variant "<id>" of "<product>" was not found.
• Stock is checked server-side. A variant that tracks its own numeric stock is validated against that; otherwise the product-level stock applies. If stock < quantity the line fails with Not enough stock for "<name>": <n> available, <q> requested.
• Line name is the product name, or "Product Name (Variant Name)" for a variant line. Two variants of one product become two separate line items.

The resolved price is then converted to the smallest currency unit and sent to Stripe as price_data (currency is usd), so Stripe only ever sees an amount the server computed:

price_data: {
  currency: "usd",
  unit_amount: Math.round(resolved.price * 100),
  product_data: {
    name: resolved.name,
    metadata: {
      productId: item.id,
      ...(item.variantId ? { variantId: item.variantId } : {}),
    },
  },
},

Session options

const session = await stripe.checkout.sessions.create({
  mode: "payment",
  line_items: lineItems,
  // Let shoppers enter Stripe promotion codes on the payment page.
  allow_promotion_codes: true,
  success_url: `${origin}/checkout/success?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${origin}/cart`,
  metadata: encodeItemsMetadata(items),
  client_reference_id: customerId,
});

• allow_promotion_codes: true — shoppers can enter Stripe promotion codes on the payment page.
• success_url — /checkout/success?session_id={CHECKOUT_SESSION_ID} on the request origin.
• cancel_url — back to /cart.
• metadata — the cart's [id, quantity] / [id, quantity, variantId] entries are encoded as compact JSON (encodeItemsMetadata) so the webhook can rebuild the order later. Long carts spill losslessly into items_2, items_3, … keys to stay under Stripe's 500-char metadata limit.
• client_reference_id — the optional customerId, used to attach the resulting order to a customer.

Response

{ "url": "https://checkout.stripe.com/c/pay/cs_test_..." }

Redirect the shopper to url. Error responses:

Rate limiting

POST /api/checkout is rate-limited per client IP to 10 requests per 10 minutes. Over the limit it returns 429 with a Retry-After header:

{ "error": "Too many requests" }

Example

curl -X POST https://your-store.example.com/api/checkout \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "id": "prod_abc", "quantity": 2 }],
    "customerId": "firebase-uid-123"
  }'

See the checkout API reference for the full route contract.

The webhook: turning a payment into an order

POST /api/webhooks/stripe is where a paid session becomes a real order in the fulfillment pipeline. Point your Stripe webhook (or stripe listen) at it.

Signature verification

The endpoint requires both a Stripe client and STRIPE_WEBHOOK_SECRET; missing either returns 503 { "error": "webhook not configured" }. The raw request body is read as text and verified against the stripe-signature header:

const payload = await request.text();
event = stripe.webhooks.constructEvent(payload, signature, webhookSecret);

• A missing stripe-signature header → 400 Missing signature.
• A failed verification → 400 Invalid signature.
• Only checkout.session.completed events are acted on; any other verified event type is acknowledged with { "received": true }.

What it records

For a completed session the handler (recordOrder) writes a paid order using the Firebase Admin SDK:

1. Idempotency — it first queries orders for an existing document with the same stripeSessionId and returns early if found, so Stripe's retries don't create duplicates.
2. Rebuild line items — decodeItemsMetadata reconstructs the id/quantity/variantId refs from the session metadata, then each product is re-fetched from Firestore to enrich the order item with productName, brand, price, subtotal, primaryImageURL, and (for variants) variantId / variantName.
3. Write the order — a document is added to the top-level orders collection with status: "Processing", paymentStatus: "paid", the Stripe-authoritative total (session.amount_total / 100, net of any promotion code), and customer details split from Stripe's customer_details. When client_reference_id is present, a mirror copy is written to customers/{uid}/orders/{orderNumber}.
4. Decrement stock — a best-effort, batched inventory decrement runs last. Lines are grouped per product, variant lines decrement the variant's own stock (falling back to product-level stock when a variant doesn't track its own), and untracked/unknown items are skipped. A failure here is logged but never fails the already-recorded order.

Responses

Full contract: webhooks API reference.

Setup

STRIPE_SECRET_KEY=sk_test_...

stripe listen --forward-to localhost:3000/api/webhooks/stripe

STRIPE_WEBHOOK_SECRET=whsec_...

FIREBASE_SERVICE_ACCOUNT_JSON={"type":"service_account","project_id":"...","private_key":"..."}

See environment variables for the full list, including how FIREBASE_SERVICE_ACCOUNT_JSON and FIREBASE_SERVICE_ACCOUNT relate.

Related