Checkout Flow

Checkout is where shopping carts become real orders. This page walks through how we transform a cart full of items into a paid transaction with orders ready for sellers to fulfill.

We use Stripe Checkout for the payment flow — this means we redirect users to Stripe’s hosted payment page, then handle webhooks when the payment succeeds.

The Big Picture

Before we dive into details, here’s what checkout looks like end-to-end:

Cart Validation

Before we can create a checkout session, the cart needs to pass several validation checks. Think of this as a “pre-flight check” that catches problems before we involve Stripe.

Cart Constraints

These rules are enforced throughout the cart lifecycle, not just at checkout:

How Shipping is Calculated

Shipping isn’t a flat fee — it’s calculated per-seller based on what they’re charging and where the buyer is located. Here’s how we figure it out:

Buyer Fees

On top of the item prices and shipping, buyers pay a service fee. This is calculated as:

buyerFee = (subtotal × feePercentage) + fixedFee

The exact percentages and fixed amounts are configured per region/currency. This fee goes to the platform, separate from seller fees.

Order Guardrails

After calculating the total, the checkout service applies two payment guardrails before creating the Stripe session. These prevent tiny or Stripe-incompatible charges.

Minimum Order Amount

Orders below 100 cents (1.00 in any currency) are rejected at checkout — unless a promo code is applied:

The check uses the full buyer total (items + shipping + buyer fee) before any coupon discount:

if (!couponCode && subtotalWithShipping + buyerFee.total < MINIMUM_ORDER_AMOUNT) {
  return err(CheckoutErr.orderTotalTooLow(MINIMUM_ORDER_AMOUNT, cart.currency))
}

Stripe Minimum Charge Auto-Absorb

Stripe rejects charges below a per-currency minimum with an amount_too_small error. When a coupon brings the payable total into the danger zone (between 1 cent and the Stripe minimum), we auto-absorb the remainder by increasing the discount to cover the full order:

Here’s the logic in the checkout service:

const remainder = stripeTotal - cappedDiscount
const stripeMin = STRIPE_MINIMUM_CHARGE[cart.currency] ?? 50
 
if (remainder > 0 && remainder < stripeMin) {
  cappedDiscount = stripeTotal // Absorb the entire remaining amount
}

Example: A buyer has a cart totaling 200 cents with a 180-cent coupon applied. The remainder is 20 cents, which is below the USD minimum of 50 cents. Instead of failing at Stripe, the discount is bumped from 180 to 200, making the order fully covered by the coupon.

Creating the Stripe Session

Once validation passes and we’ve calculated all the amounts, we create a Stripe Checkout Session. Here’s what we send:

Webhook Processing

The real magic happens in the webhook handler. When Stripe sends checkout.session.completed:

Transaction States

Transactions have their own lifecycle, separate from orders:

Data Snapshots

We “freeze” several pieces of data at checkout time. This protects both buyers and sellers from price changes:

Polling for Status

After the buyer is redirected back from Stripe, the frontend needs to know if the payment succeeded. It polls the /checkout/status endpoint:

// Frontend polling pattern
const pollStatus = async (transactionId: string) => {
  const status = await api.checkout.getStatus({ transactionId })
 
  switch (status) {
    case 'succeeded':
      // Navigate to order confirmation
      break
    case 'pending':
    case 'processing':
      // Continue polling
      setTimeout(() => pollStatus(transactionId), 1000)
      break
    case 'failed':
    case 'expired':
      // Show error
      break
  }
}

There’s a brief window between Stripe completing the payment and our webhook processing it. Polling handles this gracefully.

Error Handling

Here’s what can go wrong and what the buyer sees:

Code Locations