Modify an existing discount coupon's settings. Change the discount amount, update targeting rules, toggle auto-apply, or archive the coupon to stop new redemptions. Only the fields you include in the request body are updated.
API key access: Unrestricted project API key required. Restricted keys cannot call this endpoint.
Path Parameters
project_idstringrequired
The unique identifier of the project.
coupon_idstringrequired
The unique identifier of the coupon.
Request Body
display_namestring
Display name for the coupon.
descriptionstring
A description of the coupon.
percentagestring|number|null
Discount percentage, strictly greater than 0 and at most 100. Prefer an exact decimal string; JSON numbers must satisfy numeric precision limits.
amountstring|number|null
Fixed discount amount as a decimal string (for fixed type coupons).
min_spend_amountstring | number | null
Inclusive minimum checkout amount. Use an unsigned decimal string or nonnegative number; null clears this bound and its currency.
min_spend_currencystring | null
Minimum-spend currency: 3 to 9 uppercase ASCII letters or digits. A currency-only change preserves the existing amount; null clears the bound.
max_spend_amountstring | number | null
Inclusive maximum checkout amount. Use an unsigned decimal string or nonnegative number; null clears this bound and its currency.
max_spend_currencystring | null
Maximum-spend currency: 3 to 9 uppercase ASCII letters or digits. A currency-only change preserves the existing amount; null clears the bound.
auto_applyboolean
Whether to auto-apply this coupon.
statusstring
Coupon status: active or archived.
invitee_modestring
Who can use: all, inviteesOnly, nonInvitees.
renewal_constraintstring
When applicable: any, renewalOnly, churnedOnly.
plan_scopestring
Which plans: all, include, exclude (plan_ids required when include or exclude).
starts_atnumber | string | null
Validity start: 13-digit Unix milliseconds as a number or digit string. Send null to clear the bound. ISO dates and seconds are not accepted.
ends_atnumber | string | null
Validity end: 13-digit Unix milliseconds as a number or digit string. Send null to clear the bound. 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.
Omitted spend fields preserve the existing configuration. A currency-only change keeps that bound's stored amount. Clear a bound by setting its amount or its currency to null, for example {"min_spend_currency":null}.
Changing any spend field validates the resulting stored range: each amount needs a currency, both currencies must match, and the minimum must be no greater than the maximum. Equal bounds are allowed. An invalid merged range returns 422 VALIDATION_ERROR without applying the update. Send an amount and its currency together when introducing a bound.
