Coupons
Create, retrieve, update, delete, and list discount coupons.
A coupon is a discount code that customers can redeem at checkout to reduce the amount they are charged. Coupons support percentage-based and fixed-amount discounts, and can be configured with usage limits and duration rules.
Illustrative content. Hand-authored to demonstrate the Standard/Advanced pattern; the production page will be generated from the VINR OpenAPI spec (roadmap item #1). Field names are representative.
The coupon objectAsk
idstringUnique identifier for the coupon, e.g. cpn_5Hx1pR.
namestringHuman-readable name or code that customers enter at checkout, e.g. SUMMER20.
percent_offnumberPercentage discount applied when this coupon is redeemed. Mutually exclusive with amount_off.
amount_offintegerFixed discount amount in the smallest currency unit. Mutually exclusive with percent_off.
currencystringThree-letter ISO currency code, required when amount_off is
set, e.g. USD.
durationenumOne of once (applied to the first invoice only), repeating (applied to recurring invoices
for a set number of months), or forever (applied to all invoices).
times_redeemedintegerTotal number of times this coupon has been redeemed.
max_redemptionsintegerMaximum number of times this coupon can be redeemed. null means unlimited.
validbooleantrue if the coupon can still be redeemed (times_redeemed has not reached max_redemptions
and it has not been deleted).
createdintegerUnix timestamp when this coupon was created.
Create a couponAsk
Provide either percent_off or amount_off (with currency). Set max_redemptions to cap total
usage.
Retrieve a couponAsk
Fetch a coupon by its ID.
Update a couponAsk
Update the coupon's display name or raise the redemption cap. Discount values and duration are immutable after creation.
| Parameter | Type | Description |
|---|---|---|
name | string | New human-readable name or code for the coupon. |
max_redemptions | integer | Raise (not lower) the maximum redemption limit. |
Delete a couponAsk
Permanently deletes a coupon. It can no longer be redeemed. Existing redemptions are not affected.
List couponsAsk
Returns a paginated list of coupons, newest first.
| Parameter | Type | Description |
|---|---|---|
limit | integer | Number of results to return. Default 10, max 100. |
Related eventsAsk
coupon.created, coupon.updated, and coupon.deleted. See Events.
