Named billing discounts

Stripe and Mollie accept fixed monetary discounts when you create invoices, checkout sessions, or billed subscriptions. No coupon ID or prior coupon setup is required.

{
  "name": "Partner deal",
  "amount": 1000,
  "duration": "forever"
}

amount is a positive integer in the price currency's minor units: 1000 means EUR 10.00. The name is trimmed and must contain 1–100 characters. A discount reduces the whole product line once, including when quantity exceeds one. It must be smaller than that line's subtotal, and the charge must meet the provider minimum. Setup sessions cannot have discounts.

For checkout, send discount beside productUuid and unitAmount. For invoices, send it on each lineItems entry. Invoice lines may have different deals; subscription invoices still require exactly one product line. Existing productPriceUuid and provider price identifiers also support discounts. Inline invoice descriptions are optional and default to the product name.

{
  "type": "subscription",
  "taxRateUuid": "33333333-3333-4333-8333-333333333333",
  "lineItems": [
    {
      "productUuid": "22222222-2222-4222-8222-222222222222",
      "unitAmount": 19900,
      "currency": "EUR",
      "quantity": 1,
      "recurringInterval": "month",
      "discount": {
        "name": "Partner deal",
        "amount": 1000,
        "duration": "forever"
      }
    }
  ]
}

The invoice retains Growth at EUR 199.00 and displays Partner deal as a EUR 10.00 reduction. The provider controls the document layout. Mollie includes the deal name in the product line description and uses its native line-discount field. Exclusive tax is calculated after the reduction; inclusive prices retain their existing tax treatment.

Once and forever

• once applies to the first billable invoice. The same unpaid invoice keeps its discount when payment is retried. Subsequent regular invoices use the full price.
• forever applies to every invoice for that subscription until replaced.
• Both durations affect only the requested payment for a standalone invoice or payment checkout. They never create a customer-wide discount.

For EUR 199 with a EUR 10 deal, the first invoice is EUR 189 before any exclusive tax. Renewals are EUR 199 for once and EUR 189 for forever.

Upgrades and replacement subscriptions

An in-place upgrade without a new discount preserves the current forever deal. Supplying a new discount replaces the old deal after payment succeeds. A replacement subscription does not inherit the previous subscription's discount; send its intended discount explicitly.

Discounted midterm upgrades require the same currency and billing cadence. Mollie also requires the same tax rate. They preserve the billing date and change the subscription only after the upgrade payment succeeds. Payment failures leave the old billing terms active; webhook retries resume the pending change.

Proration uses actual billing-period timestamps and rounds each displayed monetary component to minor units. For a 30-day period with 20 days remaining:

Upgrade component	Amount
Unused old plan, EUR 100 × 20/30	−EUR 66.67
Reverse unused old EUR 10 discount	+EUR 6.67
Remaining new plan, EUR 150 × 20/30	+EUR 100.00
Apply new EUR 20 discount for remaining time	−EUR 13.33
Upgrade amount before exclusive tax	EUR 26.67

The net discount adjustment is EUR 6.66. A new forever deal then discounts each regular invoice by the full EUR 20; a new once deal ends with this upgrade invoice. An old once discount is credited only if it applied to the period being replaced.

Local billing history and deployment

Billing snapshots retain the undiscounted unitAmount, the named discount, and discountAppliedAmount for the current reconciled period. A consumed once deal can remain in history with no applied amount on later periods. Upgrade records retain the target terms and payment identity for recovery.

Deploy the additive 20260907000000_named_billing_discounts migration before the new API code. Existing rows have null discount fields. Monitor existing webhook error logs and pending upgrade records if payment succeeds but reconciliation needs a retry.