# Coupons

> 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

| Type                | Description                       | Example       |
| ------------------- | --------------------------------- | ------------- |
| **Percentage**      | Percentage off the total (1-100%) | 20% off       |
| **Fixed amount**    | Fixed discount in a currency      | \$10 off      |
| **Trial extension** | Additional free trial days        | 14 extra days |

# Duration options

Control how long a discount lasts:

| Duration      | Behavior                      | Use case                                    |
| ------------- | ----------------------------- | ------------------------------------------- |
| **Once**      | Applies to first invoice only | One-time promotions                         |
| **Repeating** | Applies for N months          | Limited-time offers (e.g., "3 months free") |
| **Forever**   | Applies indefinitely          | Loyalty discounts, partner pricing          |

# Creating a coupon

Create coupons in the dashboard or via API:

<Tabs>
  <Tab title="Dashboard">
    1. Navigate to **Coupons** in the sidebar
    2. Click **Create Coupon**
    3. Configure discount type, amount, and duration
    4. Set optional limits (max redemptions, expiration date)
    5. Save the coupon
  </Tab>

  <Tab title="API">
    ```bash
    curl -X POST https://api.paymentkit.com/v1/coupons \
      -H "Authorization: Bearer sk_live_..." \
      -d name="Summer Sale 20%" \
      -d discount_type="percent_off" \
      -d percent_off=20 \
      -d duration="repeating" \
      -d duration_in_months=3 \
      -d max_redemptions=100
    ```
  </Tab>
</Tabs>

# 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:**

```bash
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:

| Restriction         | Description                               |
| ------------------- | ----------------------------------------- |
| **First-time only** | Only customers with no prior transactions |
| **Minimum amount**  | Minimum order total required              |
| **Expiration date** | Code expires after a specific date        |
| **Max redemptions** | Total number of times code can be used    |

<Note>
  Promotion code restrictions are checked **in addition to** the coupon's rules. Both must pass for the discount to apply.
</Note>

# Product restrictions

Limit coupons to specific products:

```bash
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:

| Level            | Scope                    | Use case                        |
| ---------------- | ------------------------ | ------------------------------- |
| **Customer**     | All future subscriptions | VIP customers, partner accounts |
| **Subscription** | Specific subscription    | Promotional pricing on one plan |
| **Invoice**      | Single invoice           | One-time adjustment             |
| **Invoice item** | Single line item         | Per-product discounts           |

More specific discounts take priority over general ones.

# Coupon states

Coupons have a lifecycle with automatic state transitions:

| State        | Can redeem? | Description                         |
| ------------ | ----------- | ----------------------------------- |
| **Active**   | Yes         | Available for use                   |
| **Inactive** | No          | Manually paused, can be reactivated |
| **Depleted** | No          | Max redemptions reached (terminal)  |
| **Expired**  | No          | Past expiration date (terminal)     |

# Checkout integration

Apply coupons during checkout session creation:

```bash
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:

```bash
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:

```bash
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

<CardGroup cols={2}>
  <Card title="Use coupons as templates" icon="solid copy" color="#C6C7F8">
    Create coupons with business rules, then distribute via multiple promotion codes.
  </Card>

  <Card title="Set redemption limits" icon="solid hashtag" color="#C6C7F8">
    Always configure max\_redemptions for promotional campaigns to control costs.
  </Card>

  <Card title="Use validity periods" icon="solid calendar" color="#C6C7F8">
    Set expiration dates to create urgency and manage campaign timelines.
  </Card>

  <Card title="Track redemption sources" icon="solid chart-pie" color="#C6C7F8">
    Use different promotion codes for different channels to measure effectiveness.
  </Card>
</CardGroup>

***

\[MBCC]