---
title: "Create coupon"
method: POST
path: "/coupons"
tags: ["Coupon"]
---

# Create coupon

`POST /coupons`

This endpoint allows the creation of coupons, which can then be redeemed at subscription creation or plan change.

## Request body

- NewCoupon
  - `redemption_code` string, required — This string can be used to redeem this coupon for a given subscription.
  - `discount` union, required
    - NewCouponPercentageDiscount
      - `discount_type` 'percentage', required
      - `percentage_discount` number, required
    - NewCouponAmountDiscount
      - `discount_type` 'amount', required
      - `amount_discount` string, required
  - `duration_in_months` integer, nullable — This allows for a coupon's discount to apply for a limited time (determined in months); a `null` value here means "unlimited time".
  - `max_redemptions` integer, nullable — The maximum number of redemptions allowed for this coupon before it is exhausted;`null` here means "unlimited".

## Response `201`

Created

- Coupon — A coupon represents a reusable discount configuration that can be applied either as a fixed or percentage amount to an invoice or subscription. Coupons are activated using a redemption code, which applies the discount to a subscription or invoice. The duration of a coupon determines how long it remains available for use by end users.
  - `id` string, required — Also referred to as coupon_id in this documentation.
  - `redemption_code` string, required — This string can be used to redeem this coupon for a given subscription.
  - `discount` union, required
    - PercentageDiscount
      - `discount_type` 'percentage', required
      - `applies_to_price_ids` string[], nullable — List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
      - `filters` PriceFilter[], nullable — The filters that determine which prices to apply this discount to.
        - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
        - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
        - `values` string[], required — The IDs or values that match this filter.
      - `reason` string, nullable
      - `percentage_discount` number, required — Only available if discount_type is `percentage`. This is a number between 0 and 1.
    - AmountDiscount
      - `discount_type` 'amount', required
      - `applies_to_price_ids` string[], nullable — List of price_ids that this discount applies to. For plan/plan phase discounts, this can be a subset of prices.
      - `filters` PriceFilter[], nullable — The filters that determine which prices to apply this discount to.
        - `field` 'price_id' | 'item_id' | 'price_type' | 'currency' | 'pricing_unit_id', required — The property of the price to filter on.
        - `operator` 'includes' | 'excludes', required — Should prices that match the filter be included or excluded.
        - `values` string[], required — The IDs or values that match this filter.
      - `reason` string, nullable
      - `amount_discount` string, required — Only available if discount_type is `amount`.
  - `times_redeemed` integer, required — The number of times this coupon has been redeemed.
  - `duration_in_months` integer, nullable, required — This allows for a coupon's discount to apply for a limited time (determined in months); a `null` value here means "unlimited time".
  - `max_redemptions` integer, nullable, required — The maximum number of redemptions allowed for this coupon before it is exhausted; `null` here means "unlimited".
  - `archived_at` string, date-time, nullable, required — An archived coupon can no longer be redeemed. Active coupons will have a value of null for `archived_at`; this field will be non-null for archived coupons.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.dev/withorb/apis/api-reference.md) · [All operations](https://skmtc.dev/withorb/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/withorb/api-reference/revisions/816dfe734e2e/schema)