Create Coupon

post

https://{subdomain}.{domain}/v2/coupons

Creates a new coupon. Please note: coupons cannot be updated after being created.

DISCOUNT IN DOLLARS
When specifying a discount amount as a flat amount, the currency must be specified with the amount in an array. For example:

<discount_type>dollars</discount_type>
<discount_in_cents>
  <USD>500</USD>
  <EUR>400</EUR>
  <GBP>300</GBP>
</discount_in_cents>

DISCOUNT IN PERCENTAGE
Percentage discounts only need to specify the discount percentage. For example:

<discount_type>percent</discount_type>
<discount_percent>10</discount_percent>

LIMITING TO SPECIFIC PLANS
If a coupon applies to all plans, it will also apply to any plans created in the future. To limit a coupon to specific plans, you may specify an array of plan codes. For example:

<applies_to_all_plans>false</applies_to_all_plans>
<plan_codes>
  <plan_code>silver</plan_code>
  <plan_code>gold</plan_code>
</plan_codes>

LIMITING TO SPECIFIC ITEMS
To limit a coupon to specific items, you may specify an array of item codes. For example:

<applies_to_all_items>false</applies_to_all_items>
<item_codes>
  <item_code>terracotta</item_code>
  <item_code>terrazzo</item_code>
  <item_code>marble</item_code>
</item_codes>

CREATING UNIQUE CODE TEMPLATES
If you are creating a bulk coupon, you will need to create a unique_code_template. Here are the rules:

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 +.

<coupon_code>thankyou</coupon_code>
<coupon_type>bulk</coupon_type>
<unique_code_template>'thankyou'99999999</unique_code_template>

This example will create a unique code like: thankyou41863675

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

coupon_code

string

required

Unique code to identify and redeem the coupon. This code may only contain the following characters: [a-z A-Z 0-9 + - _ ]. Max of 50 characters.

name

string

required

Coupon name.

description

string

Description of the coupon on the hosted payment pages.

discount_type

string

required

percent, dollars, or free_trial.

discount_in_cents

integer

Mapping of discount amounts by currency if discount_type is dollars. Max 10000000.

discount_percent

integer

Discount percentage if discount_type is percent.

invoice_description

string

Description of the coupon on the invoice.

redeem_by_date

date-time

Last date to redeem the coupon, defaults to no date.

single_use

boolean

DEPRECATED: Please use duration. If true, the coupon applies to the first invoice only.

applies_for_months

integer

DEPRECATED: Please use temporal_unit and temporal_amount. Number of months after redemption that the coupon is valid, defaults to no date.

max_redemptions

integer

Maximum number of accounts that may use the coupon before it can no longer be redeemed.

applies_to_all_plans

boolean

Defaults to true

The coupon is valid for all plans if true, defaults to true.

applies_to_all_items

boolean

Defaults to false

The coupon is valid for all items if true, defaults to false.

duration

string

Defaults to forever

forever, single_use, or temporal. If single_use, the coupon applies to the first invoice only. If temporal the coupon will apply to invoices for the duration determined by the temporal_unit and temporal_amount attributes.

temporal_unit

string

day, week, month, or year. If duration is temporal then temporal_unit is multiplied by temporal_amount to define the duration that the coupon will be applied to invoices for.

temporal_amount

integer

If duration is temporal then temporal_amount is an integer which is multiplied by temporal_unit to define the duration that the coupon will be applied to invoices for.

applies_to_non_plan_charges

boolean

Defaults to false

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

redemption_resource

string

Defaults to account

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

max_redemptions_per_account

integer

The number of times the coupon can be redeemed on a specific account. null is the default and means unlimited.

coupon_type

string

Defaults to single_code

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.

unique_code_template

string

The template for generating unique codes. See rules below for creating unique code templates.

plan_codes

array of strings

Array of plan_codes the coupon applies to, if applies_to_all_plans is false.

plan_codes

item_codes

array of strings

Array of item_codes the coupone applies to, if applies_to_all_items is false.

item_codes

free_trial_amount

integer

Only relevant when the coupon type is free_trial. The free_trial_amount is used together with free_trial_unit to define the length of a free trial coupon. For example, a 2 week free trial would be defined as free_trial_amount = 2 and free_trial_unit = Week.

free_trial_unit

string

Only relevant when the coupon type is free_trial. Allowed values are day or week or month. free_trial_unit is used together with free_trial_unit to define the length of a free trial coupon. For example, a 2 week free trial would be defined as free_trial_amount = 2 and free_trial_unit = Week.

Response

201