Generate a new discount code for your subscription bot. Configure percentage or fixed-amount discounts, set auto-apply rules, restrict usage to specific plans or user types, and control whether the coupon applies to first payments only or renewals too.
POST/v2/projects/{project_id}/coupons
Authorization
Bearer API KeyRequired
API key access: Unrestricted project API key required. Restricted keys cannot call this endpoint.
Path Parameters
project_idstringrequired
The unique identifier of the project.
Request Body
codestringrequired
The coupon code users will enter.
display_namestringrequired
Display name for the coupon.
descriptionstring
A description of the coupon.
coupon_typestringrequired
Type of discount: percentage or fixed.
percentagestring|number|null
Discount percentage as a decimal string, greater than 0 and at most 100 (required for percentage type).
amountstring|number|null
Fixed discount amount as a decimal string (required for fixed type).
currencystring
Currency for fixed discounts (e.g., USD). Required for fixed type.
min_spend_amountstring | number | null
Optional inclusive minimum checkout amount. Prefer an unsigned decimal string; nonnegative JSON numbers are also accepted. Requires min_spend_currency. Null means no minimum.
min_spend_currencystring | null
Currency for the minimum checkout amount: 3 to 9 uppercase ASCII letters or digits.
max_spend_amountstring | number | null
Optional inclusive maximum checkout amount. Prefer an unsigned decimal string; nonnegative JSON numbers are also accepted. Requires max_spend_currency. Null means no maximum.
max_spend_currencystring | null
Currency for the maximum checkout amount: 3 to 9 uppercase ASCII letters or digits.
auto_applyboolean
Whether to auto-apply this coupon. Default: false
usage_limitinteger
Total redemptions allowed across all users.
per_user_limitinteger
Redemptions allowed per user.
invitee_modestring
Who can use: all, inviteesOnly, nonInvitees. Default: all
renewal_constraintstring
When applicable: any, renewalOnly, churnedOnly. Default: any
plan_scopestring
Which plans: all, include, exclude. Default: all (plan_ids required when include or exclude).
plan_idsarray
Plan UUIDs to include or exclude, per plan_scope.
starts_atnumber | string | null
Validity start: 13-digit Unix milliseconds as a number or digit string, or null for no bound. ISO dates and seconds are not accepted.
ends_atnumber | string | null
Validity end: 13-digit Unix milliseconds as a number or digit string, or null for no bound. Must be after starts_at. ISO dates and seconds are not accepted.
metadataobject
Custom metadata for the coupon.
Numeric coupon values follow the decimal input contract. A nullable value may be cleared only when the resulting coupon still satisfies its type requirements.
Spend bounds apply to this checkout's amount. Both endpoints are inclusive. Each amount needs its currency, and when both bounds are set their currencies must match and the minimum must be no greater than the maximum. Equal bounds are valid; invalid combinations return 422 VALIDATION_ERROR. The checkout currency must match the configured bound; no currency conversion is performed.
All monetary fields and percentage follow the decimal input rules. Percentage bounds are checked exactly: "100" is valid, but "100.000000000000000001" returns 422 VALIDATION_ERROR. Spend bounds are compared as exact decimals rather than rounded floating-point values.
