coupons

Stable. Describes behaviour that is built and covered by tests in this repository.

GET `/v1/coupons` #

Coupons, newest first

Not paged: the response is the complete list.

Responses

Status	Meaning	Body
`200`	OK	ListCouponsResponse

Example response

{
  "coupons": [
    {
      "code": "string",
      "name": "string",
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "percent_bps": 1,
      "amount_minor": "string",
      "currency": "string",
      "bonus_percent_bps": 1,
      "applies_to": [
        "COUPON_TARGET_SUBSCRIPTION"
      ],
      "duration": "COUPON_DURATION_ONCE",
      "duration_periods": 1,
      "max_redemptions": 1,
      "redeemed": 1,
      "expire_time": "2026-11-03T10:15:00Z",
      "active": false,
      "create_time": "2026-11-03T10:15:00Z",
      "promotion_code_count": 1,
      "without_default_code": false
    }
  ]
}

curl

curl -X GET https://YOUR-API-ADDRESS/v1/coupons \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/coupons` #

Make a coupon

Request body

Field	Type	Description
`code` required	string	2–40 letters, digits, - or _
`name`	string
`id`	string · uuid
`percent_bps`	integer	1000 is 10 %. Use one of percent_bps, amount_minor and bonus_percent_bps
`amount_minor`	string · int64	Minor units of currency; applies only in that currency
`currency`	string
`bonus_percent_bps`	integer	Extra credits on a credit purchase, in the same lot: 1000 is 10 % more. Credit purchases only
`applies_to`	array of `COUPON_TARGET_SUBSCRIPTION` \| `COUPON_TARGET_CREDIT_PURCHASE` \| `COUPON_TARGET_PAYMENT`	Where the coupon works; empty means all three (a bonus coupon: credit purchases)
`duration`	`COUPON_DURATION_ONCE` \| `COUPON_DURATION_REPEATING` \| `COUPON_DURATION_FOREVER`	How long a subscription keeps the coupon; required when it applies to subscriptions
`duration_periods`	integer	For a repeating coupon, how many fees
`max_redemptions`	integer	0 or absent = unlimited. Counts the uses through all the coupon's codes
`redeemed`	integer	The uses that count against the limit
`expire_time`	string · date-time
`active`	boolean
`create_time`	string · date-time
`promotion_code_count`	integer
`without_default_code`	boolean	Do not make the promotion code with the coupon's own text that a new coupon gets

Example

{
  "code": "string"
}

Responses

Status	Meaning	Body
`201`	Created	Coupon
`400`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "code": "string",
  "name": "string",
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "percent_bps": 1,
  "amount_minor": "string",
  "currency": "string",
  "bonus_percent_bps": 1,
  "applies_to": [
    "COUPON_TARGET_SUBSCRIPTION"
  ],
  "duration": "COUPON_DURATION_ONCE",
  "duration_periods": 1,
  "max_redemptions": 1,
  "redeemed": 1,
  "expire_time": "2026-11-03T10:15:00Z",
  "active": false,
  "create_time": "2026-11-03T10:15:00Z",
  "promotion_code_count": 1,
  "without_default_code": false
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/coupons \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code":"string"}'

DELETE `/v1/coupons/{code}` #

Stop new redemptions of a coupon (subscriptions that have it keep it)

Parameters

Name	In	Type	Description
`code` required	path	string

Responses

Status	Meaning	Body
`200`	OK	Coupon
`404`	Error envelope	Error

Example response

{
  "code": "string",
  "name": "string",
  "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
  "percent_bps": 1,
  "amount_minor": "string",
  "currency": "string",
  "bonus_percent_bps": 1,
  "applies_to": [
    "COUPON_TARGET_SUBSCRIPTION"
  ],
  "duration": "COUPON_DURATION_ONCE",
  "duration_periods": 1,
  "max_redemptions": 1,
  "redeemed": 1,
  "expire_time": "2026-11-03T10:15:00Z",
  "active": false,
  "create_time": "2026-11-03T10:15:00Z",
  "promotion_code_count": 1,
  "without_default_code": false
}

curl

curl -X DELETE https://YOUR-API-ADDRESS/v1/coupons/<code> \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY"

POST `/v1/coupons/{code}/promotion-codes` #

Make promotion codes for a coupon

Name the codes (2-40 letters, digits, - or _; the same in any case) or ask for count random ones (1-1000, prefix + 8 characters without 0, O, 1, I, L). Every code gets the template's limit, expiry and restrictions.

Parameters

Name	In	Type	Description
`code` required	path	string

Request body

Field	Type	Description
`template`	PromotionCodeInput	What a customer types. Many codes point to one coupon, each with its own limit, expiry and restrictions.
`codes`	array of string	Name the codes, or ask for count
`count`	integer
`prefix`	string	For random codes; at most 20 characters

Example

{}

Responses

Status	Meaning	Body
`201`	Created	CreatePromotionCodesResponse
`400`	Error envelope	Error
`404`	Error envelope	Error
`409`	Error envelope	Error

Example response

{
  "codes": [
    {
      "id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "coupon_id": "0192f0b4-6f6e-7c3a-9a3e-6a1f2b3c4d5e",
      "coupon_code": "string",
      "code": "string",
      "active": false,
      "max_redemptions": 1,
      "redeemed": 1,
      "expire_time": "2026-11-03T10:15:00Z",
      "first_purchase_only": false,
      "one_per_customer": false,
      "min_amount_minor": "string",
      "min_amount_currency": "string",
      "allowed_plans": [
        "string"
      ],
      "allowed_packs": [
        "string"
      ],
      "allowed_currencies": [
        "string"
      ],
      "restore_on_reversal": false,
      "create_time": "2026-11-03T10:15:00Z"
    }
  ]
}

curl

curl -X POST https://YOUR-API-ADDRESS/v1/coupons/<code>/promotion-codes \
  -H "Authorization: Bearer $PAYRUDDER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Models

Coupon

Field	Type	Description
`code` required	string	2–40 letters, digits, - or _
`name` required	string
`id` required	string · uuid
`percent_bps` required	integer	1000 is 10 %. Use one of percent_bps, amount_minor and bonus_percent_bps
`amount_minor` required	string · int64	Minor units of currency; applies only in that currency
`currency` required	string
`bonus_percent_bps` required	integer	Extra credits on a credit purchase, in the same lot: 1000 is 10 % more. Credit purchases only
`applies_to` required	array of `COUPON_TARGET_SUBSCRIPTION` \| `COUPON_TARGET_CREDIT_PURCHASE` \| `COUPON_TARGET_PAYMENT`	Where the coupon works; empty means all three (a bonus coupon: credit purchases)
`duration` required	`COUPON_DURATION_ONCE` \| `COUPON_DURATION_REPEATING` \| `COUPON_DURATION_FOREVER`	How long a subscription keeps the coupon; required when it applies to subscriptions
`duration_periods` required	integer	For a repeating coupon, how many fees
`max_redemptions` required	integer	0 or absent = unlimited. Counts the uses through all the coupon's codes
`redeemed` required	integer	The uses that count against the limit
`expire_time` required	string · date-time
`active` required	boolean
`create_time` required	string · date-time
`promotion_code_count` required	integer
`without_default_code` required	boolean	Do not make the promotion code with the coupon's own text that a new coupon gets

CouponInput

Field	Type	Description
`code` required	string	2–40 letters, digits, - or _
`name`	string
`id`	string · uuid
`percent_bps`	integer	1000 is 10 %. Use one of percent_bps, amount_minor and bonus_percent_bps
`amount_minor`	string · int64	Minor units of currency; applies only in that currency
`currency`	string
`bonus_percent_bps`	integer	Extra credits on a credit purchase, in the same lot: 1000 is 10 % more. Credit purchases only
`applies_to`	array of `COUPON_TARGET_SUBSCRIPTION` \| `COUPON_TARGET_CREDIT_PURCHASE` \| `COUPON_TARGET_PAYMENT`	Where the coupon works; empty means all three (a bonus coupon: credit purchases)
`duration`	`COUPON_DURATION_ONCE` \| `COUPON_DURATION_REPEATING` \| `COUPON_DURATION_FOREVER`	How long a subscription keeps the coupon; required when it applies to subscriptions
`duration_periods`	integer	For a repeating coupon, how many fees
`max_redemptions`	integer	0 or absent = unlimited. Counts the uses through all the coupon's codes
`redeemed`	integer	The uses that count against the limit
`expire_time`	string · date-time
`active`	boolean
`create_time`	string · date-time
`promotion_code_count`	integer
`without_default_code`	boolean	Do not make the promotion code with the coupon's own text that a new coupon gets

CreatePromotionCodes

Field	Type	Description
`template`	PromotionCodeInput	What a customer types. Many codes point to one coupon, each with its own limit, expiry and restrictions.
`codes`	array of string	Name the codes, or ask for count
`count`	integer
`prefix`	string	For random codes; at most 20 characters

CreatePromotionCodesResponse

Field	Type	Description
`codes` required	array of PromotionCode

Error

Field	Type	Description
`error` required	object

ListCouponsResponse

Field	Type	Description
`coupons` required	array of Coupon

PromotionCode

Field	Type	Description
`id` required	string · uuid
`coupon_id` required	string · uuid
`coupon_code` required	string
`code` required	string
`active` required	boolean
`max_redemptions` required	integer	0 or absent = unlimited
`redeemed` required	integer
`expire_time` required	string · date-time
`first_purchase_only` required	boolean	Only a customer who has paid for nothing yet
`one_per_customer` required	boolean
`min_amount_minor` required	string · int64	A purchase under this amount cannot use the code; needs min_amount_currency
`min_amount_currency` required	string
`allowed_plans` required	array of string	Plan codes; empty means any
`allowed_packs` required	array of string	Credit pack ids; empty means any
`allowed_currencies` required	array of string	Empty means any
`restore_on_reversal` required	boolean	A void or full refund gives the use back to the count. Off by default
`create_time` required	string · date-time

PromotionCodeInput

Field	Type	Description
`id`	string · uuid
`coupon_id`	string · uuid
`coupon_code`	string
`code`	string
`active`	boolean
`max_redemptions`	integer	0 or absent = unlimited
`redeemed`	integer
`expire_time`	string · date-time
`first_purchase_only`	boolean	Only a customer who has paid for nothing yet
`one_per_customer`	boolean
`min_amount_minor`	string · int64	A purchase under this amount cannot use the code; needs min_amount_currency
`min_amount_currency`	string
`allowed_plans`	array of string	Plan codes; empty means any
`allowed_packs`	array of string	Credit pack ids; empty means any
`allowed_currencies`	array of string	Empty means any
`restore_on_reversal`	boolean	A void or full refund gives the use back to the count. Off by default
`create_time`	string · date-time

coupons

GET /v1/coupons #

Responses

POST /v1/coupons #

Request body

Responses

DELETE /v1/coupons/{code} #

Parameters

Responses

POST /v1/coupons/{code}/promotion-codes #

Parameters

Request body

Responses

Models

Coupon

CouponInput

CreatePromotionCodes

CreatePromotionCodesResponse

Error

ListCouponsResponse

PromotionCode

PromotionCodeInput

GET `/v1/coupons` #

POST `/v1/coupons` #

DELETE `/v1/coupons/{code}` #

POST `/v1/coupons/{code}/promotion-codes` #