Promotion Codes

Promotion codes live on your connected Stripe account. Create them with the CLI, then opt in at checkout from your app.

Create a code

buildspace app billing promos create --code LAUNCH20 --percent-off 20 --max-redemptions 100 --expires 2026-12-31
buildspace app billing promos create --code SAVE5 --amount-off 5 --duration repeating --months 3 --products Pro
buildspace app billing promos                     # list
buildspace app billing promos deactivate LAUNCH20

• Codes are per environment (--env dev|prod, default dev). billing sync doesn't copy them.
• A code applies to the app's current products unless you pass --products.
• --duration once|repeating|forever sets how many subscription invoices get the discount.
• Creating a prod code asks for confirmation. Pass --yes in non-interactive sessions.

Let customers type a code

Subscription prices only. Stripe Checkout shows an "Add promotion code" field:

await bs.billing.createCheckout({
  userId,
  lookupKey: "pro-monthly",
  allowPromotionCodes: true,
  successUrl,
  cancelUrl,
});

The browser client accepts the same option on redirectToCheckout.

Apply a code from your server

Works for any price type. Use this for ?promo= links, your own "Have a code?" field, or codes reserved for specific users:

await bs.billing.createCheckout({
  userId,
  lookupKey: "lifetime",
  promotionCode: "LAUNCH20",
  successUrl,
  cancelUrl,
});

promotionCode needs a secret key; publishable keys get a 403. Unknown, expired, or used-up codes fail with an error you can show next to the code input.

Rules

• Pass allowPromotionCodes or promotionCode, not both.
• One-time prices can't use allowPromotionCodes. The platform fee on a one-time payment is fixed when checkout starts, so Buildspace needs to know the discount up front. Collect the code in your app and pass promotionCode.
• Codes created for one of your apps can't be redeemed through another app's checkout. Codes created directly in the Stripe dashboard work in any of your apps.