Coupons | Solvimon | Documentation

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 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
  }'

{
  "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:

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 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_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 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_KcVud5Ppq1gwW9LL5Dv8"]
      }
    ]
  }'

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.

Coupons across schedule changes

A coupon is redeemed against a pricing plan schedule, not against the subscription, so its discounts live on that schedule.

coupon_discount_behaviour on migrate and 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

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.

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 endpoint to see which customers have redeemed a coupon:

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

{
  "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: