Discounts and promotion codes

Numeral for Stripe Checkout supports Stripe coupons and promotion codes in payment and subscription sessions. Choose one approach for each session:

Approach	Field inside `checkout`	When the discount is applied
Let the buyer enter a code in Stripe Checkout	`allow_promotion_codes: true`	After Numeral prepares the initial quote
Apply an existing coupon	`discounts: [{ coupon: "coupon_123" }]`	Before Numeral calculates the quote
Apply an existing promotion-code ID	`discounts: [{ promotion_code: "promo_123" }]`	Before Numeral calculates the quote

These fields are optional. Omitting them preserves the existing checkout behavior. Continue using X-API-Version: 2026-03-01.

Let buyers enter a promotion code

Set checkout.allow_promotion_codes to true when your server creates the Bridge session. Stripe displays the code-entry field on its payment page; the Numeral address collector does not collect the code.

curl https://api.numeralhq.com/tax/bridge/sessions \
  -H "Authorization: Bearer $NUMERAL_API_KEY" \
  -H "X-API-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout_order_8421" \
  -d '{
    "config_id": "brcfg_123",
    "collection_mode": "hosted",
    "checkout": {
      "mode": "payment",
      "line_items": [{ "price": "price_123", "quantity": 1 }],
      "success_url": "https://store.example/success",
      "cancel_url": "https://store.example/cart",
      "allow_promotion_codes": true
    }
  }'

Replace the configuration and Price IDs with your own. The configuration supplies the tax-location policy; Numeral collects missing address fields before redirecting to Stripe. Use a new idempotency key for each logical checkout and reuse it only when retrying that request.

Tax eligibility for buyer-entered codes

Buyer-entered codes are supported when the applicable tax rules remain valid as the discounted price changes. Percentage-based taxes and eligible zero-rate or exempt carts can qualify. Rules with price thresholds, tax caps, flat fees, or other unsupported calculations cannot use this option. Numeral checks eligibility before returning the Stripe Checkout URL. If the cart is ineligible, use a pre-applied discount so Numeral can calculate tax from the discounted amounts.

Enabling promotion codes permits the buyer’s final total to differ from the initial quote. In manual-confirmation flows, accepted_total still refers to that initial quote.

Apply a discount before calculating tax

Replace allow_promotion_codes in the request above with one of these checkout.discounts values:

{
  "discounts": [{ "coupon": "coupon_123" }]
}

{
  "discounts": [{ "promotion_code": "promo_123" }]
}

promotion_code takes Stripe’s promo_... object ID, not the buyer-facing code such as SUMMER20. Create and manage coupons and promotion codes in the connected Stripe account. See Stripe’s discount guide. Numeral applies percentage or fixed-amount discounts to eligible products before calculating tax, then verifies the amounts against Stripe before exposing the checkout URL.

Restrictions

discounts accepts at most one entry, containing exactly one of coupon or promotion_code.
Do not combine a pre-applied discount with allow_promotion_codes: true.
Prices, coupons, and promotion codes must belong to the configuration’s connected Stripe account and the same test or live mode.
If the Stripe connection uses a restricted key, it needs permission to read coupons and promotion codes.
Stripe enforces redemption limits, customer restrictions, minimum spend, and expiration. Pass checkout.customer when a code is restricted to an existing Stripe Customer.
Combine repeated instances of the same Stripe Price into one line item with the total quantity when using discounts.

Subscription discounts use Stripe’s subscription behavior. Numeral verifies the initial checkout; subsequent renewal invoices continue through the existing Stripe invoice integration.

Read the initial and final amounts

For sessions that opt into discounts, the server response includes amount_discount on the quote and its lines, plus a settlement field. Amounts use the currency’s smallest unit, such as cents for USD.

Field	Meaning
`quote.subtotal`	Initial subtotal after discounts, excluding tax
`quote.amount_discount`	Discount included in the initial quote; zero before a buyer enters a code
`quote.total_tax_amount`	Tax calculated for the initial quote
`quote.total`	Initial subtotal plus tax
`settlement`	Final verified discounted calculation, or `null` until verification completes

The original subtotal before discounts is subtotal + amount_discount. For example, a $24.00 cart with a 20% discount has subtotal: 1920 and amount_discount: 480 before tax. Numeral retains quote after checkout. Retrieve the Bridge session from your server and read settlement for the verified final amounts, especially when the buyer entered a code in Stripe. Numeral verifies the final cart and tax before committing the discounted transaction. Sessions that omit discount options retain their existing response shape; the additional discount and settlement fields are not required for those sessions.

Handle errors and retries

Error code	What to do
`provider_option_conflict`	Choose either buyer-entered codes or one pre-applied discount.
`tax_shape_not_supported`	Create a new checkout using a pre-applied discount instead of buyer-entered codes.
`tax_rate_unavailable`	If `last_error.retryable` is `true`, retry the create request with the same payload and idempotency key.
`provider_total_mismatch`	Do not redirect or fulfill. Numeral could not verify Stripe’s amounts against the calculated quote.

Codes in a session’s last_error.code use lowercase, as shown above. Immediate API errors use an uppercase type, such as PROVIDER_OPTION_CONFLICT. A temporary eligibility-check failure can return a session in phase: "processing" with a retryable last_error. Repeating the create request resumes that session with its original cart and configuration.

Test discounted and zero-dollar orders

Test a valid code, an expired or ineligible code, a pre-applied discount, and a 100% discount using your test-mode Stripe connection. For a zero-dollar payment checkout:

Stripe does not collect a payment method. A 100% discount cannot be used to collect a card for future charges.
Do not require a PaymentIntent to exist.
Wait for the Bridge session to reach a completed, verified state. Fulfillment must also handle status: "complete", payment_status: "no_payment_required", and tax_status: "not_applicable", rather than requiring every completed checkout to report paid.

Read Metadata and saved cards to combine discounts with application tracking or future-payment setup.

​Let buyers enter a promotion code

​Tax eligibility for buyer-entered codes

​Apply a discount before calculating tax

​Restrictions

​Read the initial and final amounts

​Handle errors and retries

​Test discounted and zero-dollar orders

Let buyers enter a promotion code

Tax eligibility for buyer-entered codes

Apply a discount before calculating tax

Restrictions

Read the initial and final amounts

Handle errors and retries

Test discounted and zero-dollar orders