Create a coupon

Idempotency Supported

This API creates a new coupon for a specific promotion or offers.

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/coupons

Input Parameters

required, string, max chars=100

Used to uniquely identify the coupon in your website/application and to integrate with Chargebee.

Note:

When the coupon ID contains a special character; for example: #, the API returns an error. Make sure that you encode the coupon ID in the path parameter before making an API call.

name

required, string, max chars=50

The display name used in web interface for identifying the coupon.

Note:

When the name of the coupon set contains a special character; for example: #, the API returns an error. Make sure that you encode the name of the coupon set in the path parameter before making an API call.

invoice_name

optional, string, max chars=100

Display name used in invoice. If it is not configured then name is used in invoice.

discount_type

optional, enumerated string, default=percentage

Specifies the type of discount to be applied.

fixed_amount

A fixed amount is deducted as a discount. The discount amount is specified in discount_amount.

Learn more about fixed_amount coupons.

percentage

A percentage of the original price is deducted as a discount. The discount percentage is specified in discount_percentage.

Learn more about percentage coupons.

offer_quantity

A specified number of units of the plan or addon are offered for free. The number of free units is specified in discount_quantity. The offer_quantity option is valid only when apply_on is set to each_specified_item and the pricing_model of the plan or addon is per_unit.

Learn more about offer_quantity coupons.

discount_amount

optional, in cents, min=0

The value of the deduction. The format of this value depends on the kind of currency .

currency_code

required if Multicurrency is enabled, string, max chars=3

The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.

discount_percentage

optional, double, min=0.01, max=100

The percentage of the original amount that should be deducted from it.

discount_quantity

optional, integer, min=1

Specifies the number of free units provided for the plan or addon , without affecting the total quantity sold. This parameter is applicable only when the discount_type is set to offer_quantity .

apply_on

required, enumerated string

The amount on the invoice to which the coupon is applied.

invoice_amount

The coupon is applied to the invoice sub_total .

each_specified_item

The coupon is applied to the invoice.line_item.amount that corresponds to the plan or addon specified by plan_ids and addon_ids .

duration_type

optional, enumerated string, default=forever

Specifies the time duration for which this coupon is attached to the subscription.

one_time

The coupon stays attached to the subscription till it is applied on an invoice once. It is removed after that from the subscription.

forever

The coupon is attached to the subscription and applied on the invoices until explicitly removed.

limited_period

The discount is attached to the subscription and applied on the invoices for a limited duration. This duration starts from the point it is applied to an invoice for the first time and expires after a period specified by period and period_unit .

duration_month

optional, integer, min=1, max=240

(Deprecated) The duration of time in months for which the coupon is attached to the subscription. Applicable only when duration_type is limited_period.

Note: This parameter has been deprecated. Use period and period_unit instead.

valid_till

optional, timestamp(UTC) in seconds

Date upto which the coupon can be applied to new subscriptions.

max_redemptions

optional, integer, min=1

Maximum number of times this coupon can be redeemed.

Note:

If not specified, the coupon can be redeemed an indefinite number of times.

invoice_notes

optional, string, max chars=2000

A customer-facing note added to all invoices associated with this API resource. This note becomes one among all the notes displayed on the invoice PDF.

meta_data

optional, jsonobject

A collection of key-value pairs that provides extra information about the coupon.

Note: There's a character limit of 65,535.

Learn more .

included_in_mrr

optional, boolean

The coupon is included in MRR calculations for your site. This attribute is only applicable for coupons of duration_type = one_time and when the feature is enabled in Chargebee. Note: If the site-level setting is to exclude one-time coupons from MRR calculations, this value is always returned false .

period

optional, integer, min=1

The duration of time for which the coupon is attached to the subscription, in period_units. Applicable only when duration_type is limited_period .

period_unit

optional, enumerated string

The unit of time for period. Applicable only when duration_type is limited_period .

day

A period of 24 hours.

week

A period of 7 days.

month

A period of 1 calendar month.

year

A period of 1 calendar year.

plan_constraint

optional, enumerated string

Plans the coupon can be applied to.

none

Coupon not applicable to any plans.

all

Coupon applicable to all plans.

specific

Coupon only applicable to specified plans. If used, it is mandatory to specify the plan(s).

addon_constraint

optional, enumerated string

Addons the coupon can be applied to.

none

Coupon not applicable to any addons.

all

Coupon applicable to all addons.

specific

Coupon only applicable to specified addons. If used, it is mandatory to specify the addon(s).

plan_ids

optional, string, max chars=100

Identifier of the plan.

addon_ids

optional, string, max chars=100

Identifier of the addon.

status

optional, enumerated string, default=active

Status of the coupon.

active

Can be applied to a subscription.

archived

Cannot be applied to a subscription. Existing associations remain unaffected.

Returns

couponCoupon object

Resource object representing coupon