Coupons

Create discount codes customers can apply at checkout. Percentage or fixed-amount, time-limited or capped, one-time or recurring.

Coupons are managed in the Dashboard > Commerce > Coupons tab in the builder, or through the SDK at proyecta.commerce.coupons.

Anatomy of a coupon

Field	Notes
code	The promo code customers type at checkout (e.g. LAUNCH20)
percent_off or amount_off	Mutually exclusive. Percent is 1–100. Amount is in the smallest currency unit (cents).
currency	Required for amount_off discounts (three-letter ISO code)
duration	once (first payment only), repeating (for duration_in_months), or forever
duration_in_months	Required when duration is repeating
max_redemptions	Total cap across all customers
redeem_by	Expiration date after which the coupon stops working
name	Display name shown to customers
active	Toggle to enable/disable without deleting

Create a coupon

From the Coupons tab, click Create coupon and fill in the fields. Or via the SDK:

// 20% off forever
await proyecta.commerce.coupons.create({
  code: 'LAUNCH20',
  name: 'Launch discount',
  percent_off: 20,
  duration: 'forever',
});

// $10 off, single use, expires in 30 days
await proyecta.commerce.coupons.create({
  code: 'WELCOME10',
  amount_off: 1000,
  currency: 'USD',
  duration: 'once',
  max_redemptions: 1,
  redeem_by: new Date(Date.now() + 30 * 86400 * 1000).toISOString(),
});

// 50% off for the first 3 months of a subscription
await proyecta.commerce.coupons.create({
  code: 'EARLY3',
  percent_off: 50,
  duration: 'repeating',
  duration_in_months: 3,
});

Apply a coupon at checkout

Pass the code as promotion_code in your checkout call:

await proyecta.commerce.checkout({
  customer_id,
  line_items: [{ variant_id: 'var_pro_monthly' }],
  success_url: 'https://myapp.com/welcome',
  promotion_code: 'LAUNCH20',
});

You can also let customers enter the code themselves on the Stripe-hosted checkout page — the field is shown automatically.

List, update, deactivate

// Browse every coupon
for await (const coupon of proyecta.commerce.coupons.list()) {
  console.log(coupon.code, coupon.times_redeemed, '/', coupon.max_redemptions);
}

// Disable a coupon (without deleting)
await proyecta.commerce.coupons.update('coupon_123', { active: false });

Notes and limits

• Codes and discount amounts are immutable. You can update the display name and toggle active, but not percent_off, amount_off, or code itself. Create a new coupon if you need different terms.
• times_redeemed auto-increments and is read-only — useful for tracking campaign performance.
• Coupons apply per customer, not per order — if a coupon is forever and a customer subscribes, every renewal gets the discount.