v1

latestOpenAPI 3.0.32026-07-248079274.0 KB

Coupons

Create a coupon

Creates a new coupon with a discount configuration.

post/coupons

Request body

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

valuenumber 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_cyclesinteger nullable

Number of billing cycles the discount applies for. Required when duration is 'repeating'. Must be null otherwise.

max_redemptionsinteger nullable

Maximum number of times this coupon can be applied across all subscriptions. Null for unlimited.

Example request

{
  "name": "Summer Sale 20%",
  "discount_type": "percentage",
  "value": 20,
  "duration": "repeating",
  "duration_in_cycles": 3,
  "max_redemptions": 100
}

Response

Coupon Created

idstring required

Unique ID assigned by Acquired to the coupon when it is created.

namestring required

Display name for the coupon.

discount_type'percentage' | 'fixed_amount' required

Whether the coupon applies a percentage or fixed_amount reduction.

valuenumber 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_cyclesinteger nullable

Number of billing cycles the discount applies for. Required when duration is 'repeating'. Null otherwise.

max_redemptionsinteger nullable

Maximum number of times this coupon can be applied across all subscriptions. Null for unlimited.

times_redeemedinteger required

Number of times this coupon has been applied to subscriptions.

status'active' | 'expired' | 'archived' required

Current lifecycle status of the coupon.

created_atstring date-time required

When the coupon was created.

Example response

{
  "id": "01JCX5Y8K9M3N4P6Q7R8S9T0UV",
  "name": "Summer Sale 20%",
  "discount_type": "percentage",
  "value": 20,
  "duration": "repeating",
  "duration_in_cycles": 3,
  "max_redemptions": 100,
  "times_redeemed": 5,
  "status": "active",
  "links": [
    {
      "rel": "self",
      "href": "/v1/coupons/01JCX5Y8K9M3N4P6Q7R8S9T0UV",
      "method": "GET"
    }
  ]
}