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.
- 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.
| Duration | Description |
|---|
forever | Discount applies to all future invoices |
once | Discount applies only to the first invoice |
| 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 |
