> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.solvimon.com/platform-guides/products-and-pricing/product-catalog/coupons/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: " \ -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: " ``` ### 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: " \ -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: " \ -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: " \ -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: " ``` ```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)