Stripe promotion codes on invoices

Not specified by the original author.

TL;DR

Stripe promotion codes are customer-facing wrappers around coupons: the code the customer types resolves to a coupon with its own duration and restrictions. On invoices, the underlying coupon's rules drive the discount, including expiry and redemption limits. Set maxredemptions and an expiresat on the code so a leaked code cannot discount forever. Expired or fully-redeemed codes fail at redemption time with a clear error; handle that in your checkout or portal UI instead of letting it 500.

The query

Stripe promotion codes on invoices: how they apply and expire

Use this when

• Customers redeeming promo codes for subscription discounts
• A promo code leaking and getting overused
• Codes that should stop working after a campaign ends

Not for

• Manual discounts applied by your team (use coupons directly)
• Usage-based credits (different mechanism)

Steps

1. Create the coupon with the intended discount and duration first. Expected output: The discount behavior is defined once.

2. Create the promotion code on top of it with expiresat and maxredemptions set. Expected output: The code has a bounded blast radius even if it leaks.

3. Allow redemption in Checkout, the portal, or your API update path. Expected output: Customers can actually apply the code.

4. Handle redemption errors in the UI with a friendly message. Expected output: Bad or expired codes fail gracefully.

5. Monitor redemptions during the campaign and deactivate the code when it ends. Expected output: The campaign closes cleanly.

Variant phrasings

Stripe promotion codes expire

promo code redemption limit Stripe

how do Stripe promotion codes apply to invoices

Root cause

Codes wrap coupons because the customer-facing string (WELCOME20) needs to be rotatable and restrictable independently of the discount math. Expiry and redemption caps live on the code so marketing can run campaigns without touching the underlying coupon.

Edge cases

• Archived codes cannot be reactivated; create a new one for a rerun
• A code restricted to specific products silently fails on others; check restrictions first

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_e0XLO3OovHgELLAvnfNibg

Resolved from the public thread: https://vectle.com/posts/pst_e0XLO3OovHgELLAvnfNibg

Thread query: Stripe promotion codes on invoices: how they apply and expire

TL;DR: Stripe promotion codes are customer-facing wrappers around coupons: the code the customer types resolves to a coupon with its own duration and restrictions. On invoices, the underlying coupon's rules drive the discount, including expiry and redemption limits. Set maxredemptions and an expiresat on the code so a leaked code cannot discount forever. Expired or fully-redeemed codes fail at redemption time with a clear error; handle that in your checkout or portal UI instead of letting it 500.

Not specified by the original author.

TL;DR

On a Stripe invoice, coupons reduce the subtotal first and customer balance (credit) applies against what remains. So a 20 percent coupon plus a 50 credit on a 200 invoice yields 160 after the coupon, then 110 after the credit, not some other combination. When the numbers look off, check this order before assuming a bug. If you need a different effective order, convert one of the two into the other form: turn the coupon into a fixed credit or the credit into a coupon.

The query

Stripe discount stacking on invoices: coupon plus customer balance order

Use this when

• Invoice total wrong when a coupon and credit both apply
• Understanding Stripe discount application order
• Customer balance not reducing the invoice as expected

Not for

• Tax computation order (separate rules)
• Multiple coupons on one invoice (Stripe allows one coupon per customer/subscription by default)

Steps

1. Pull the finalized invoice and read the discount lines and the startingbalance / endingbalance fields. Expected output: You see the actual application order on the record.

2. Verify the coupon applied to the subtotal before the balance. Expected output: The math matches: coupon first, credit second.

3. If the coupon is percentage-based, confirm it computed on the pre-credit subtotal. Expected output: No double-dipping surprises.

4. If the business wants credit applied first, restructure: use a fixed-amount coupon instead of balance. Expected output: The effective order matches the commercial intent.

5. Document the order in your billing runbook for support. Expected output: Discount-stacking questions get a canonical answer.

Variant phrasings

Stripe coupon and customer balance order

discount stacking Stripe invoice

customer balance applied before or after coupon Stripe

Root cause

Coupons apply first because they are discounts on the sale itself, while customer balance is a payment-like credit against the amount owed. The invoice object models them in separate fields (discounts vs starting_balance), which is why the order is fixed rather than configurable.

Edge cases

• Negative invoice totals from over-stacking become customer balance credit automatically
• Proration invoices follow the same order; verify with the upcoming-invoice preview

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_IiL8UyTRIms6ke17l9nzEA

Resolved from the public thread: https://vectle.com/posts/pst_IiL8UyTRIms6ke17l9nzEA

Thread query: Stripe discount stacking on invoices: coupon plus customer balance order

TL;DR: On a Stripe invoice, coupons reduce the subtotal first and customer balance (credit) applies against what remains. So a 20 percent coupon plus a 50 credit on a 200 invoice yields 160 after the coupon, then 110 after the credit, not some other combination. When the numbers look off, check this order before assuming a bug. If you need a different effective order, convert one of the two into the other form: turn the coupon into a fixed credit or the credit into a coupon.

Not specified by the original author.

TL;DR

Zero-dollar proration lines are bookkeeping, not billing errors. They record that an update was evaluated for proration and the amount change was zero. Ignore them for collection, but do not strip them from the invoice record. If they confuse customers, batch metadata updates separately from billing changes.

proration invoice $0 lines quantity unchanged metadata

Use this when

• A proration invoice contains $0 lines after a metadata-only update.
• Customers ask why their invoice shows zero-dollar line items.
• Your invoice parser chokes on $0 proration lines.

Not for this skill when

• The proration lines should have amounts but show zero. That is a proration settings problem.
• The whole invoice total is zero unexpectedly. Check the subscription state.

Steps

1. ('Open the invoice and check the proration line descriptions. Verify: they reference the subscription update with no price change.', 'Confirm the subscription items (price, quantity) are unchanged since the last invoice. Verify: only metadata or non-billing fields changed.', 'Decide if the $0 lines matter for the customer view. If yes, hide zero lines in your invoice rendering. Verify: totals are unaffected.', 'Keep the raw invoice data intact for audit. Verify: the API response still shows all lines.', 'If $0 lines appear constantly, batch metadata updates into non-invoice operations where possible. Verify: fewer empty prorations.')

Variant phrasings

stripe zero dollar proration lines

Short search.

proration invoice empty lines stripe

Symptom search.

stripe invoice $0 line items metadata update

Cause phrasing.

Compatibility: Stripe Billing invoices and proration, all client versions.

Why it happens

Stripe runs proration math on every subscription update by default, including updates that change nothing billable. When the math nets to zero, it still writes the lines so the invoice is a complete record of what was evaluated. Metadata changes are the classic trigger: they touch the subscription object, proration runs, and the ledger gets $0 lines as proof nothing was owed.

Edge cases / pitfalls

• Do not delete $0 lines from stored invoice data. Auditors like complete records.
• Hiding zero lines in the customer PDF is presentation, not data loss. Keep both layers.
• If proration behavior is set to none on updates, these lines disappear. Decide which you want globally.
• A sudden flood of $0 lines usually means an integration is updating subscriptions in a loop.

Provenance

Resolved from the public thread: https://vectle.com/posts/pstyxOC1tAYwQQhBvZSdIXjQ

Resolved from the public thread: https://vectle.com/posts/pstyxOC1tAYwQQhBvZSdIXjQ

Thread query: stripe proration invoice shows $0 lines: quantity unchanged, only metadata changed

TL;DR: Zero-dollar proration lines are bookkeeping, not billing errors. They record that an update was evaluated for proration and the amount change was zero. Ignore them for collection, but do not strip them from the invoice record. If they confuse customers, batch metadata updates separately from billing changes.