Coupons and promotion codes

PayBridgeNP uses a two-level discount model: a coupon is a reusable discount template; a promotion code is a customer-facing string (like LAUNCH50) that redeems a coupon.

Concepts

Coupon

The template. Defines:

Discount: percent (1-100%) or amount (fixed paisa off)
Duration: once (next invoice only), repeating (N cycles), or forever
Caps: maxRedemptions, redeemBy expiry
Scope: appliesToPlanIds (nullable = all plans)

Promotion code

A public handle pointing at a coupon. Has its own independent limits:

maxRedemptions
expiresAt
minimumAmount (order floor in paisa)
customerIds restriction

A single coupon can have multiple promotion codes - useful for split tests (LAUNCH50 vs WELCOME50).

Creating a coupon

curl -X POST https://api.paybridgenp.com/v1/billing/coupons \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "LAUNCH",
    "name": "Launch discount",
    "discountType": "percent",
    "percentOff": 50,
    "duration": "repeating",
    "durationInCycles": 3,
    "maxRedemptions": 100
  }'

Creating a promotion code

curl -X POST https://api.paybridgenp.com/v1/billing/promotion-codes \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{
    "couponId": "cpn_…",
    "code": "LAUNCH50",
    "maxRedemptions": 500,
    "expiresAt": "2026-06-01T00:00:00Z"
  }'

The code is case-insensitive and stored uppercase.

Validating before applying

curl -X POST https://api.paybridgenp.com/v1/billing/promotion-codes/validate \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"code":"LAUNCH50","planId":"bp_…","amount":50000}'

Returns { valid: true, coupon, promotion_code, discount_preview } or { valid: false, reason }. This is read-only and safe to call on every keystroke.

Applying to a subscription

curl -X POST https://api.paybridgenp.com/v1/billing/subscriptions/sub_…/apply-coupon \
  -H "Authorization: Bearer sk_test_…" \
  -H "Content-Type: application/json" \
  -d '{"promotionCode":"LAUNCH50"}'

Or pass couponId directly to skip the promo-code layer.

Duration semantics

Duration	Behavior
`once`	Applied to the next invoice only. Deactivated after.
`repeating`	Applied for the next `durationInCycles` invoices. Auto-deactivates.
`forever`	Applied to every future invoice until the coupon is deactivated.

Redemption atomicity

Coupon and promotion code counters update atomically against the redemption cap - racing N parallel applies can never exceed it. The N-1 losers get an error like "Promotion code redemption limit reached". Safe to retry.

Invoice math

When an invoice is generated for a subscription with an active discount, PayBridgeNP emits line items in this order:

Subscription (plan amount, positive)
Discount (coupon discount, negative)
Tax (VAT on the discounted amount - see Tax guide)

Totals apply the discount before tax:

subtotal       = subscription line amount
discount_total = |discount line amount|
taxable_base   = max(0, subtotal - discount_total)
tax_total      = round(taxable_base * rate_bps / 10000)
amount_due     = subtotal - discount_total + tax_total

Webhooks

Event	When it fires
`coupon.created`	Coupon created via API or dashboard.
`coupon.deleted`	Deactivation.
`coupon.expired`	Daily sweep deactivates expired coupons.
`promotion_code.redeemed`	Each time a promo is applied to a subscription.
`subscription.discount_applied`	Coupon attached to a sub.
`subscription.discount_removed`	Active discount cleared.

Disabling the feature

Want coupons switched off for your account? Contact support@paybridgenp.com and we’ll disable them; existing subscriptions then invoice exactly as they did before coupons were introduced.

Getting Started

Accepting Payments

Checkout

Providers

Subscriptions & Billing

Branding

Operations

Integrations

Coupons and promotion codes

Concepts

Coupon

Promotion code

Creating a coupon

Creating a promotion code

Validating before applying

Applying to a subscription

Duration semantics

Redemption atomicity

Invoice math

Webhooks

Disabling the feature

​Concepts

​Coupon

​Promotion code

​Creating a coupon

​Creating a promotion code

​Validating before applying

​Applying to a subscription

​Duration semantics

​Redemption atomicity

​Invoice math

​Webhooks

​Disabling the feature

Concepts

Coupon

Promotion code

Creating a coupon

Creating a promotion code

Validating before applying

Applying to a subscription

Duration semantics

Redemption atomicity

Invoice math

Webhooks

Disabling the feature