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

# Create a coupon

`POST /coupons`

Creates a new coupon with a discount configuration.

## Request body

- CouponCreate
  - `name` string, required — A display name for the coupon.
  - `discount_type` 'percentage' | 'fixed_amount', required — The type of discount. 'percentage' applies a percentage reduction. 'fixed_amount' applies a fixed currency reduction.
  - `value` number, required — The discount value. For percentage: 20 = 20% (max 100 = 100%). For fixed_amount: 5.00 = 5.00 in the specified currency.
  - `currency` 'GBP' | 'USD' | 'EUR', nullable — Required for fixed_amount discounts. Must be null for percentage discounts.
  - `duration` 'once' | 'repeating' | 'forever', required — How long the discount applies when used on a subscription.
  - `duration_in_cycles` integer, nullable — Number of billing cycles the discount applies for. Required when duration is 'repeating'. Must be null otherwise.
  - `max_redemptions` integer, nullable — Maximum number of times this coupon can be applied across all subscriptions. Null for unlimited.

## Response `200`

Coupon Created

- Coupon
  - `id` string, required — Unique ID assigned by Acquired to the coupon when it is created.
  - `name` string, required — Display name for the coupon.
  - `discount_type` 'percentage' | 'fixed_amount', required — Whether the coupon applies a `percentage` or `fixed_amount` reduction.
  - `value` number, required — The discount value. For percentage: 20 = 20%, 100 = 100%. For fixed_amount: 5.00 = 5.00 in the specified currency.
  - `currency` 'GBP' | 'USD' | 'EUR', nullable — Required for fixed_amount discounts. Null for percentage discounts.
  - `duration` 'once' | 'repeating' | 'forever', required — How long the discount applies. 'once' applies to a single billing cycle, 'repeating' applies for a set number of cycles, 'forever' applies indefinitely.
  - `duration_in_cycles` integer, nullable — Number of billing cycles the discount applies for. Required when duration is 'repeating'. Null otherwise.
  - `max_redemptions` integer, nullable — Maximum number of times this coupon can be applied across all subscriptions. Null for unlimited.
  - `times_redeemed` integer, required — Number of times this coupon has been applied to subscriptions.
  - `status` 'active' | 'expired' | 'archived', required — Current lifecycle status of the coupon.
  - `created_at` string, date-time, required — When the coupon was created.
  - `links` object[], required
    - `rel` 'self'
    - `href` string — Link to the resource which should be appended to base URL.
    - `method` string — The HTTP method to use with the link.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized

---

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