Create and manage discounts with coupons and promotion codes. Offer percentage discounts, fixed amounts, or extended trial periods with flexible rules and limits.

How coupons work

The coupon system has three components:

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│   Coupon    │────▶│ Promotion    │────▶│  Customer   │
│  (Template) │     │    Code      │     │   Redeems   │
│             │     │ (Shareable)  │     │    Code     │
└─────────────┘     └──────────────┘     └─────────────┘
       │                                        │
       │                                        ▼
       │                             ┌─────────────────┐
       │                             │   Discount      │
       │                             │   Applied to    │
       └────────────────────────────▶│   Subscription  │
                                     └─────────────────┘

• Coupons - Reusable discount templates with rules and limits
• Promotion codes - Customer-facing codes that link to coupons
• Discounts - Applied instances of coupons on subscriptions or invoices

Discount types

Duration options

Control how long a discount lasts:

Creating a coupon

Create coupons in the dashboard or via API:

Promotion codes

Promotion codes are shareable codes that customers enter at checkout. Each code links to a coupon and can have its own restrictions.

Creating a promotion code:

$
curl -X POST https://api.paymentkit.com/v1/promotion-codes \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -d coupon_id="coupon_abc123" \
>
  -d code="SUMMER20" \
>
  -d max_redemptions=50

Promotion code restrictions

Add additional rules to promotion codes:

Product restrictions

Limit coupons to specific products:

$
curl -X POST https://api.paymentkit.com/v1/coupons \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -d name="Enterprise Discount" \
>
  -d percent_off=15 \
>
  -d duration="forever" \
>
  -d product_ids[]="prod_enterprise" \
>
  -d product_ids[]="prod_enterprise_annual"

When product IDs are specified, the discount only applies to line items matching those products.

Applying discounts

Discounts can be attached at different levels:

More specific discounts take priority over general ones.

Coupon states

Coupons have a lifecycle with automatic state transitions:

Checkout integration

Apply coupons during checkout session creation:

$
curl -X POST https://api.paymentkit.com/v1/checkout/sessions \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -d customer_id="cus_xyz" \
>
  -d line_items[0][price_id]="price_abc" \
>
  -d promotion_code="SUMMER20"

Or allow customers to enter codes at checkout:

$
curl -X POST https://api.paymentkit.com/v1/checkout/sessions \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -d allow_promotion_codes=true

Invoice discount calculation

When an invoice is generated:

1. Check for invoice-level discount
2. Fall back to subscription-level discount
3. Fall back to customer-level discount

Percentage discounts:

item_discount = item_amount × (percent_off / 100)

Fixed amount discounts (distributed proportionally):

item_discount = total_discount × (item_amount / invoice_total)

Validating promotion codes

Check if a code is valid before applying:

$
curl -X POST https://api.paymentkit.com/v1/promotion-codes/validate \
>
  -H "Authorization: Bearer sk_live_..." \
>
  -d code="SUMMER20" \
>
  -d customer_id="cus_xyz"

The response indicates whether the code can be used and any restrictions that apply.

Best practices

[MBCC]