Fill in the fields below, then reference the result from later steps as {{listCoupons.response.data}}.
Request
Query parameters
idsarray<string>
Filter results by their IDs. Up to 200 IDs can be passed at once using
commas as separators, e.g. `ids=h1at4d57xlmy,gyqgg0d3v9n1,jrsm5b4yefg6`.
**Important notes:**
* The `ids` parameter cannot be used with any other ordering or filtering
parameters (`limit`, `order`, `sort`, `begin_time`, `end_time`, etc)
* Invalid or unknown IDs will be ignored, so you should check that the
results correspond to your request.
* Records are returned in an arbitrary order. Since results are all
returned at once you can sort the records yourself.
limitinteger
Limit number of records 1-200.
Default 20
orderstring
Sort order.
One ofascdescDefault "desc"
sortstring
Sort field. You *really* only want to sort by `updated_at` in ascending
order. In descending order updated records will move behind the cursor and could
prevent some records from being returned.
One ofcreated_atupdated_atDefault "created_at"
begin_timestring (date-time)
Inclusively filter by begin_time when `sort=created_at` or `sort=updated_at`.
**Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
end_timestring (date-time)
Inclusively filter by end_time when `sort=created_at` or `sort=updated_at`.
**Note:** this value is an ISO8601 timestamp. A partial timestamp that does not include a time zone will default to UTC.
Response
Returns 200 with an object. Read it in later steps with {{listCoupons.response.data.<field>}}.
objectstring
Will always be List.
has_moreboolean
Indicates there are more results on subsequent pages.
nextstring
Path to subsequent page of results.
dataarray<object>
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>4 fields
A list of plans for which this coupon applies. This will be `null` if `applies_to_all_plans=true`.
itemsarray<object>6 fields
A list of items for which this coupon applies. This will be
`null` if `applies_to_all_items=true`.
redemption_resourcestring
Whether the discount is for all eligible charges on the account, or only a specific subscription.
One ofaccountsubscriptionDefault "account"
discountobject4 fields
Details of the discount a coupon applies. Will contain a `type`
property and one of the following properties: `percent`, `fixed`, `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`.
