Create a new coupon

post

https://v3.recurly.com/coupons

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

name

string

required

The internal name for the coupon.

max_redemptions

integer

A maximum number of redemptions for the coupon. The coupon will expire when it hits its maximum redemptions.

max_redemptions_per_account

integer

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.

hosted_description

string

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_description

string

length ≤ 255

Description of the coupon on the invoice.

redeem_by_date

string

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.

code

string

required

The code the customer enters to redeem the coupon.

discount_type

string

enum

required

The type of discount provided by the coupon (how the amount discounted is calculated)

Allowed:

discount_percent

integer

The percent of the price discounted by the coupon. Required if discount_type is percent.

free_trial_unit

string

enum

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. Required if discount_type is free_trial. Use billing_period to grant a free trial for a number of billing cycles.

Allowed:

free_trial_amount

integer

1 to 9999

Sets the duration of time the free_trial_unit is for. Required if discount_type is free_trial.

currencies

array of objects

Fixed discount currencies by currency. Required if the coupon type is fixed. This parameter should contain the coupon discount values

Currencies

applies_to_non_plan_charges

boolean

Defaults to false

The coupon is valid for one-time, non-plan charges if true.

applies_to_all_plans

boolean

Defaults to true

The coupon is valid for all plans if true. If false then plans will list the applicable plans.

applies_to_all_items

boolean

Defaults to false

To apply coupon to Items in your Catalog, include a list
of item_codes in the request that the coupon will apply to. Or set value
to true to apply to all Items in your Catalog. The following values
are not permitted when applies_to_all_items is included: free_trial_amount
and free_trial_unit.

plan_codes

array of strings

List of plan codes to which this coupon applies. Required
if applies_to_all_plans is false. Overrides applies_to_all_plans
when applies_to_all_plans is true.

Plan codes

item_codes

array of strings

List of item codes to which this coupon applies. Sending
item_codes is only permitted when applies_to_all_items is set to false.
The following values are not permitted when item_codes is included:
free_trial_amount and free_trial_unit.

Item codes

duration

string

enum

Defaults to forever

This field does not apply when the discount_type is free_trial.

"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.
"forever" coupons will apply to invoices forever.

Allowed:

temporal_amount

integer

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_unit

string

enum

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.

Allowed:

coupon_type

string

enum

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.

Allowed:

unique_code_template

string

On a bulk coupon, the template from which unique coupon codes are generated.

You must start the template with your coupon_code wrapped in single quotes.
Outside of single quotes, use a 9 for a character that you want to be a random number.
Outside of single quotes, use an "x" for a character that you want to be a random letter.
Outside of single quotes, use an * for a character that you want to be a random number or letter.
Use single quotes ' ' for characters that you want to remain static. These strings can be alphanumeric and may contain a - _ or +.
For example: "'abc-'****'-def'"

redemption_resource

string

enum

Defaults to account

Whether the discount is for all eligible charges on the account, or only a specific subscription.

Allowed:

Responses

201A new coupon.

400Bad request, perhaps invalid JSON?

404Incorrect site ID.

422Invalid request parameters.

defaultUnexpected error.