> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.solvimon.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.solvimon.com/_mcp/server.

# Coupons

Coupons define reusable discount templates you can attach to subscriptions to reduce what a customer is charged. They support percentage, fixed-amount, and usage-credit discounts, with optional scope and time limits.

---

## How it works

A coupon is a reusable discount object. You define the discount once, then apply it to one or more subscriptions. The discount is calculated at invoice generation time and appears as a reduction on the relevant line items.

Coupons have two layers of optionality:

* **Promotion codes** — human-readable codes (e.g. `SUMMER25`) that reference a coupon. Promotion codes let you distribute the same underlying discount through different channels or with different redemption limits.
* **Direct coupon IDs** — attach the coupon directly to a subscription schedule without a promotion code.

### Discount types

| Type         | Description                                       |
| ------------ | ------------------------------------------------- |
| `PERCENTAGE` | Reduces the charge by a percentage (e.g. 10%)     |
| `AMOUNT`     | Reduces the charge by a fixed currency amount     |
| `USAGE`      | Grants a free-usage credit toward metered charges |

### Duration

| Type       | Description                                               |
| ---------- | --------------------------------------------------------- |
| `ONE_TIME` | Applied to the first invoice only                         |
| `FOREVER`  | Applied to every invoice for the life of the subscription |
| `PERIOD`   | Applied for a defined number of months, weeks, or days    |

### Scope

By default, a coupon applies to the full invoice. You can restrict it to specific product categories, products, or product items using the `limited_to` field. Scoped coupons only reduce charges on matching line items.

### Lifecycle

Coupons follow the standard resource lifecycle: `DRAFT` → `ACTIVE` → `INACTIVE` → `DEPRECATED` → `ARCHIVED`. Only `ACTIVE` coupons can be redeemed. You must activate a coupon before attaching it to a subscription.

---

## Create a coupon

### Via API

Use the [Create a coupon](https://docs.solvimon.com/api-docs/configuration-api/coupons/post-coupons) endpoint:

```bash
curl -X POST https://test.api.solvimon.com/v1/coupons \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "10% off for 3 months",
    "reference": "LAUNCH-10PCT-3M",
    "description": "Introductory discount for new enterprise customers",
    "discount": {
      "type": "PERCENTAGE",
      "percentage": "10"
    },
    "duration": {
      "type": "PERIOD",
      "period": {
        "quantity": 3,
        "unit": "MONTH"
      }
    },
    "maximum_redemptions": 100
  }'
```

```json
{
  "object_type": "coupon",
  "id": "coup_KcVud5Ppq1gwW9LL5Dv8",
  "name": "10% off for 3 months",
  "reference": "LAUNCH-10PCT-3M",
  "status": "DRAFT",
  "discount": {
    "type": "PERCENTAGE",
    "percentage": "10"
  },
  "duration": {
    "type": "PERIOD",
    "period": {
      "quantity": 3,
      "unit": "MONTH"
    }
  },
  "maximum_redemptions": 100,
  "number_of_redemptions": 0,
  "created_at": "2026-04-09T10:00:00Z"
}
```

Then [activate it](https://docs.solvimon.com/api-docs/configuration-api/coupons/post-coupons-by-resource-id-or-reference-activate):

```bash
curl -X POST https://test.api.solvimon.com/v1/coupons/coup_KcVud5Ppq1gwW9LL5Dv8/activate \
  -H "X-API-KEY: <apiKey>"
```

### Via Desk

Navigate to **Product catalog → Coupons → Add coupon**. Fill in:

* **Name** — display name for internal use
* **Reference** — unique identifier; auto-generated by default
* **Description** — optional notes visible to your team
* **Discount type** — Percentage or Amount, and the value
* **Discount duration** — One-time, Forever, or Period (with count and unit)
* **Limited to** — optionally scope to a product category, product, or product item
* **Start date / End date** — optional validity window
* **Maximum redemptions** — optional cap on total uses across all customers

---

## Create a promotion code

Promotion codes are human-readable codes linked to a coupon. Create one when you want to distribute a discount through a campaign, referral link, or self-serve flow. Use the [Create a promotion code](https://docs.solvimon.com/api-docs/configuration-api/promotion-codes/post-promotion-codes) endpoint:

```bash
curl -X POST https://test.api.solvimon.com/v1/promotion-codes \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "code": "SUMMER25",
    "code_format": "SUMMER25",
    "coupon_id": "coup_KcVud5Ppq1gwW9LL5Dv8",
    "maximum_redemptions": 50
  }'
```

Promotion codes inherit the coupon's discount and duration. You can add their own `start_at`, `end_at`, and `maximum_redemptions` to further restrict a specific code without changing the underlying coupon.

---

## Apply to a subscription

Attach a coupon to a subscription schedule using either a coupon ID or a promotion code. You can pass both at the same time if needed. See the [Create a pricing plan subscription](https://docs.solvimon.com/api-docs/configuration-api/pricing-plan-subscriptions/post-pricing-plan-subscriptions) endpoint:

```bash
curl -X POST https://test.api.solvimon.com/v1/pricing-plan-subscriptions \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_id": "cust_00112233-4455-6677-8899-aabbccddeeff",
    "pricing_plan_id": "pp_abc123",
    "schedules": [
      {
        "coupon_ids": ["coup_KcVud5Ppq1gwW9LL5Dv8"]
      }
    ]
  }'
```

Or by promotion code:

```bash
"schedules": [
  {
    "promotion_codes": ["SUMMER25"]
  }
]
```

> **Note**
>
> `allow_promotion_codes` on the subscription template controls whether customers can self-apply promotion codes. Set to `SINGLE` to allow one code per subscription, or `NONE` to disable self-service redemption entirely.

Applied coupons appear on the invoice under `coupons` and `promotion_codes`, and the discount is reflected on the relevant line items.

---

## Coupons across schedule changes

A coupon is redeemed against a [pricing plan schedule](/platform-guides/customers-and-billing/subscriptions/subscription-schedules), not against the subscription, so its discounts live on that schedule.

`coupon_discount_behaviour` on [migrate](https://docs.solvimon.com/api-docs/configuration-api/pricing-plan-schedules/post-pricing-plan-schedules-by-resource-id-migrate) and [copy](https://docs.solvimon.com/api-docs/configuration-api/pricing-plan-schedules/post-pricing-plan-schedules-by-resource-id-copy) decides what happens to the coupons still running:

| Value        | Effect                                                                       |
| ------------ | ---------------------------------------------------------------------------- |
| `NONE`       | The default. The discounts end with the schedule they were redeemed on.      |
| `CARRY_OVER` | The discounts continue on the new schedule for the time the coupon has left. |

**`Migrate a schedule and keep the running coupons`**

```bash Migrate a schedule and keep the running coupons
curl -X POST https://test.api.solvimon.com/v1/pricing-plan-schedules/ppsc_jwDeeN0tYSY3F7BkeN1v/migrate \
  -H "X-API-KEY: <apiKey>" \
  -H "Content-Type: application/json" \
  -d '{
    "pricing_plan_version_id": "ppve_QwDeeN0vcYJaBLAc0C29",
    "start_at": "2026-10-01T00:00:00+02:00",
    "coupon_discount_behaviour": "CARRY_OVER"
  }'
```

`CARRY_OVER` works out the coupon's application window from where the coupon originally started on the subscription, not from the schedule being replaced. The discount clause is then re-dated to begin with the new schedule and to end where the coupon was always going to end. A three-month coupon that has run for two carries one month onto the new schedule.

> **Note**
>
> Carrying a coupon over does not redeem it again. `number_of_redemptions` on the coupon is unchanged, and a coupon that has reached `maximum_redemptions` still carries over on the subscriptions that already hold it.

A coupon needs a customer to be applied against. Carrying one over to a schedule with no customer is rejected with a validation error on `coupon_discount_behaviour`.

---

## View redemptions

Use the [Get a list of coupon redemptions](https://docs.solvimon.com/api-docs/configuration-api/coupons/get-coupons-by-resource-id-or-reference-redemptions) endpoint to see which customers have redeemed a coupon:

```bash
curl https://test.api.solvimon.com/v1/coupons/coup_KcVud5Ppq1gwW9LL5Dv8/redemptions \
  -H "X-API-KEY: <apiKey>"
```

```json
{
  "data": [
    {
      "coupon_id": "coup_KcVud5Ppq1gwW9LL5Dv8",
      "customer_id": "cust_00112233-4455-6677-8899-aabbccddeeff",
      "redeemed_at": "2026-04-09T14:22:00Z",
      "promotion_code_details": {
        "promotion_code_id": "promo_987e6543-e21b-12d3-a456-426614174999",
        "code": "SUMMER25"
      }
    }
  ]
}
```

The `number_of_redemptions` field on the coupon object tracks the running total.

---

## Edge cases

* A coupon with `maximum_redemptions` set will stop accepting new attachments once that limit is reached, even if it remains `ACTIVE`.
* Scoping a coupon to a product item that isn't on the customer's subscription has no effect — the discount silently does not apply to that invoice.
* Deactivating a coupon (`INACTIVE`) does not remove it from existing subscriptions. It only prevents new redemptions.
* Promotion codes can have stricter limits than their parent coupon (fewer max redemptions, shorter validity window), but not looser ones — the coupon's constraints always apply.

---

## API reference

Coupons and promotion codes are managed through the **Configuration API**:

* [Create a coupon](https://docs.solvimon.com/api-docs/configuration-api/coupons/post-coupons)
* [Get a coupon](https://docs.solvimon.com/api-docs/configuration-api/coupons/get-coupons-by-resource-id-or-reference)
* [Activate a coupon](https://docs.solvimon.com/api-docs/configuration-api/coupons/post-coupons-by-resource-id-or-reference-activate)
* [Deactivate a coupon](https://docs.solvimon.com/api-docs/configuration-api/coupons/post-coupons-by-resource-id-or-reference-deactivate)
* [Get a list of coupon redemptions](https://docs.solvimon.com/api-docs/configuration-api/coupons/get-coupons-by-resource-id-or-reference-redemptions)
* [Create a promotion code](https://docs.solvimon.com/api-docs/configuration-api/promotion-codes/post-promotion-codes)
* [Get a promotion code](https://docs.solvimon.com/api-docs/configuration-api/promotion-codes/get-promotion-codes-by-resource-id-or-reference)