Overview

Coupons provide discounts to customers during checkout. They can offer percentage-based or fixed-amount discounts and can be restricted to specific plans. Coupons track redemption counts and can have expiration dates.

API Endpoints

Method	Endpoint	Description
`GET`	`/coupons`	List coupons
`POST`	`/coupons`	Create coupon
`GET`	`/coupons/{id}`	Get coupon
`PUT`	`/coupons/{id}`	Update coupon
`DELETE`	`/coupons/{id}`	Delete coupon

Important Behaviors

Soft delete: Coupons are soft-deleted. Existing subscriptions using the coupon are not affected.
Metadata merge: On update, metadata is merged with existing values, not replaced.
Plan detach: If plans is not provided on update, existing plan associations may be detached.
Redeem by: The redeem_by field is parsed as a date. After this date, the coupon can no longer be applied.
Valid default: New coupons default to valid: true.

Coupon Duration

Duration	Description
`forever`	Discount applies to all future invoices
`once`	Discount applies only to the first invoice

Coupon Object

Attribute	Type	Description
`id`	integer	Unique identifier for the coupon
`name`	string	Display name shown on invoices and receipts
`coupon_code`	string	The code customers enter at checkout
`amount_off`	integer	Fixed discount amount in cents
`percent_off`	number	Percentage discount (e.g. 25 for 25% off)
`currency`	string	Currency for fixed-amount discounts (ISO 4217)
`duration`	string	How long the discount applies: `forever` or `once`
`duration_in_months`	integer	Number of months for recurring discounts
`max_redemptions`	integer	Maximum number of times the coupon can be used
`times_redeemed`	integer	Number of times the coupon has been used
`expires_on`	integer	Unix timestamp after which the coupon cannot be used
`valid`	boolean	Whether the coupon is currently valid
`plans`	array	Array of plans the coupon is restricted to
`metadata`	object	Key-value pairs for storing additional data
`created_at`	integer	Unix timestamp of creation
`updated_at`	integer	Unix timestamp of last update