Products & plansProduct Catalog

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

TypeDescription
PERCENTAGEReduces the charge by a percentage (e.g. 10%)
AMOUNTReduces the charge by a fixed currency amount
USAGEGrants a free-usage credit toward metered charges

Duration

TypeDescription
ONE_TIMEApplied to the first invoice only
FOREVERApplied to every invoice for the life of the subscription
PERIODApplied 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 endpoint:

$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
>  }'
1{
2  "object_type": "coupon",
3  "id": "coup_123e4567-e89b-12d3-a456-426614174000",
4  "name": "10% off for 3 months",
5  "reference": "LAUNCH-10PCT-3M",
6  "status": "DRAFT",
7  "discount": {
8    "type": "PERCENTAGE",
9    "percentage": "10"
10  },
11  "duration": {
12    "type": "PERIOD",
13    "period": {
14      "quantity": 3,
15      "unit": "MONTH"
16    }
17  },
18  "maximum_redemptions": 100,
19  "number_of_redemptions": 0,
20  "created_at": "2026-04-09T10:00:00Z"
21}

Then activate it:

$curl -X POST https://test.api.solvimon.com/v1/coupons/coup_123e4567-e89b-12d3-a456-426614174000/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 endpoint:

$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_123e4567-e89b-12d3-a456-426614174000",
>    "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 endpoint:

$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_123e4567-e89b-12d3-a456-426614174000"]
>      }
>    ]
>  }'

Or by promotion code:

$"schedules": [
>  {
>    "promotion_codes": ["SUMMER25"]
>  }
>]

📘 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.

View redemptions

Use the Get a list of coupon redemptions endpoint to see which customers have redeemed a coupon:

$curl https://test.api.solvimon.com/v1/coupons/coup_123e4567-e89b-12d3-a456-426614174000/redemptions \
>  -H "X-API-KEY: <apiKey>"
1{
2  "data": [
3    {
4      "coupon_id": "coup_123e4567-e89b-12d3-a456-426614174000",
5      "customer_id": "cust_00112233-4455-6677-8899-aabbccddeeff",
6      "redeemed_at": "2026-04-09T14:22:00Z",
7      "promotion_code_details": {
8        "promotion_code_id": "promo_987e6543-e21b-12d3-a456-426614174999",
9        "code": "SUMMER25"
10      }
11    }
12  ]
13}

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: