Customize Checkout

Learn how to customize the Stripe checkout session. The checkout is already configured with automatic tax calculation, manual payment capture, and promotion codes.

What's Already Configured

The checkout session in app/api/stripe/checkout/route.ts includes:

• Automatic tax calculation - Taxes calculated based on customer location
• Manual payment capture - Payments authorized first, captured after verification
• Promotion codes - Customers can enter promo codes (disabled when featured coupon is active)
• Custom terms text - Terms of Service and Privacy Policy links after checkout

Checkout Configuration File

app/api/stripe/checkout/route.ts

Steps

const session = await stripe.checkout.sessions.create({
  // ... other config
  success_url: `${env.SITE_URL}/order?session_id={CHECKOUT_SESSION_ID}`,
  cancel_url: `${env.SITE_URL}`,
});

const session = await stripe.checkout.sessions.create({
  // ... other config
  custom_text: {
    after_submit: {
      message: `By continuing, you agree to [Terms of Service](${env.SITE_URL}/legal/terms) and [Privacy Policy](${env.SITE_URL}/privacy-policy).`,
    },
  },
});

Additional Customization Options

Add Customer Email Prefill

Prefill email if you have it from authentication:

const session = await stripe.checkout.sessions.create({
  // ... other config
  customer_email: 'customer@example.com',
});

Collect Shipping Address

For physical products, collect shipping information:

const session = await stripe.checkout.sessions.create({
  // ... other config
  shipping_address_collection: {
    allowed_countries: ['US', 'CA', 'GB', 'FR', 'DE'],
  },
});

Set Billing Address Collection

Control when billing address is collected:

const session = await stripe.checkout.sessions.create({
  // ... other config
  billing_address_collection: 'required', // or 'auto'
});

Add Session Metadata

Track additional information with the checkout session:

const session = await stripe.checkout.sessions.create({
  // ... other config
  metadata: {
    order_id: '12345',
    source: 'website',
    campaign: 'summer-sale',
  },
});

Customize Checkout Branding

Update checkout appearance in Stripe Dashboard (no code changes needed):

1. Navigate to Settings → Branding
2. Upload your logo
3. Set brand colors
4. Configure button styles

Changes apply automatically to all checkout sessions.

Common Issues

Checkout Session Not Creating

• Verify Stripe API keys are set in .env
• Check that the price ID is valid and active
• Ensure the product has a default price
• Review server logs for detailed error messages

Success URL Not Working

• Confirm SITE_URL is set correctly in .env
• Verify the URL is publicly accessible (for production)
• Check that the order page exists at the success URL path

Custom Text Not Showing

• Verify the text is properly formatted (Markdown supported)
• Check that the position is valid (after_submit, etc.)
• Ensure the text doesn't exceed character limits

Next Steps

• Test Payments Locally - Test checkout with Stripe CLI
• Add Product - Create products for checkout
• Add Coupon - Create discount codes