Fill in the fields below, then reference the result from later steps as {{getCoupon.response.data}}.
Request
Path parameters
coupon_idstringrequired
Coupon ID or code. For ID no prefix is used e.g. `e28zov4fw0v2`. For code use prefix `code-`, e.g. `code-10off`.
Response
Returns 200 with an object. Read it in later steps with {{getCoupon.response.data.<field>}}.
idstring
objectstring
codestring
The code the customer enters to redeem the coupon.
namestring
The internal name for the coupon.
statestring
Indicates if the coupon is redeemable, and if it is not, why.
One ofexpiredmaxed_outredeemable
max_redemptionsinteger
A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions.
max_redemptions_per_accountinteger
Redemptions per account is the number of times a specific account can redeem the coupon. Set redemptions per account to `1` if you want to keep customers from gaming the system and getting more than one discount from the coupon campaign.
unique_coupon_codes_countinteger
When this number reaches `max_redemptions` the coupon will no longer be redeemable.
unique_code_templatestring
On a bulk coupon, the template from which unique coupon codes are generated.
unique_coupon_codeobject
Will be populated when the Coupon being returned is a `UniqueCouponCode`.
durationstring
- "single_use" coupons applies to the first invoice only.
- "temporal" coupons will apply to invoices for the duration determined by the `temporal_unit` and `temporal_amount` attributes.
One offoreversingle_usetemporalbilling_periods
temporal_amountinteger
If `duration` is "temporal" than `temporal_amount` is an integer which is multiplied by `temporal_unit` to define the duration that the coupon will be applied to invoices for. When `temporal_unit` is "billing_period", this is the number of complete billing cycles.
temporal_unitstring
The temporal unit for the coupon's duration. Used with temporal_amount to define how long the coupon applies. When temporal_unit is billing_period, the coupon applies for temporal_amount complete billing cycles rather than a fixed calendar duration. billing_period requires redemption_resource=subscription.
One ofdaymonthweekyearbilling_period
free_trial_unitstring
Description of the unit of time the coupon is for. Used with `free_trial_amount` to determine the duration of time the coupon is for.
One ofdaymonthweekbilling_period
free_trial_amountinteger
Sets the duration of time the `free_trial_unit` is for.
applies_to_all_plansboolean
The coupon is valid for all plans if true. If false then `plans` will list the applicable plans.
Default true
applies_to_all_itemsboolean
The coupon is valid for all items if true. If false then `items`
will list the applicable items.
Default false
applies_to_non_plan_chargesboolean
The coupon is valid for one-time, non-plan charges if true.
Default false
plansarray<object>
A list of plans for which this coupon applies. This will be `null` if `applies_to_all_plans=true`.
idstring
objectstring
codestring
Unique code to identify the plan. This is used in Hosted Payment Page URLs and in the invoice exports.
namestring
This name describes your plan and will appear on the Hosted Payment Page and the subscriber's invoice.
itemsarray<object>
A list of items for which this coupon applies. This will be
`null` if `applies_to_all_items=true`.
idstring
objectstring
codestring
Unique code to identify the item.
statestring
The current state of the item.
One ofactiveinactive
namestring
This name describes your item and will appear on the invoice when it's purchased on a one time basis.
descriptionstring
Optional, description.
redemption_resourcestring
Whether the discount is for all eligible charges on the account, or only a specific subscription.
One ofaccountsubscriptionDefault "account"
discountobject
Details of the discount a coupon applies. Will contain a `type`
property and one of the following properties: `percent`, `fixed`, `trial`.
typestring
One offixedfree_trialpercent
percentinteger
This is only present when `type=percent`.
currenciesarray<object>2 fields
This is only present when `type=fixed`.
trialobject2 fields
This is only present when `type=free_trial`.
coupon_typestring
Whether the coupon is "single_code" or "bulk". Bulk coupons will require a `unique_code_template` and will generate unique codes through the `/generate` endpoint.
One ofbulksingle_code
hosted_page_descriptionstring
This description will show up when a customer redeems a coupon on your Hosted Payment Pages, or if you choose to show the description on your own checkout page.
invoice_descriptionstring
Description of the coupon on the invoice.
redeem_bystring (date-time)
The date and time the coupon will expire and can no longer be redeemed. Time is always 11:59:59, the end-of-day Pacific time.
created_atstring (date-time)
updated_atstring (date-time)
expired_atstring (date-time)
The date and time the coupon was expired early or reached its `max_redemptions`.
