Create a coupon for items

Idempotency Supported

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

Prerequisites & Constraints

discount_percentage is required when discount_type is percentage.
discount_amount is required when discount_type is fixed_amount.

Sample Request

Create a coupon for items

Sample Result[JSON]

URL Format

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

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.

Constraint

id must be unique across all coupons on the site.

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.

Constraint

name must be unique across all coupons on the site.

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.

Constraint

Offer Quantity coupons must be enabled for your site to set discount_type to offer_quantity.

Enum Values

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 item price 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 item price 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 .

Constraint

discount_amount can be provided only when discount_type is fixed_amount.

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.

Constraints

currency_code can be provided only when discount_type is fixed_amount.
currency_code must be a valid currency code.

discount_percentage

optional, double, min=0.01, max=100

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

Constraint

discount_percentage can be provided only when discount_type is percentage.

discount_quantity

optional, integer, min=1

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

Constraint

discount_quantity can be provided only when discount_type is offer_quantity.

apply_on

required, enumerated string

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

Constraint

apply_on must be each_specified_item when discount_type is offer_quantity.

Enum Values

invoice_amount

The coupon is applied to the invoice sub_total .

each_specified_item

Applies the coupon to specified items (plans, addons, or charges), with the discount applied to each matching invoice.line_item.amount.

Requires applicability to be configured using item_constraints—for example all, criteria, or specific with item_price_ids.

When you attach this coupon to a subscription, at least one of that subscription's plans, addons, or charges must match those rules. If none do, the request fails.

duration_type

optional, enumerated string, default=forever

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

Enum Values

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.

Constraint

duration_month can be provided only when duration_type is limited_period.

valid_from

optional, timestamp(UTC) in seconds

The date from which the coupon can be applied to subscriptions.

Constraint

valid_from must be a date in the future.

valid_till

optional, timestamp(UTC) in seconds

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

Constraint

valid_till must be a date in the future.

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 .

Constraint

period can be provided 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 .

Constraint

period_unit can be provided only when duration_type is limited_period.

Enum Values

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.

status

optional, enumerated string, default=active

Status of the coupon.

Enum Values

active

Can be applied to a subscription.

archived

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

item_constraints[0..n]

Parameters for item_constraints. Multiple item_constraints can be passed by specifying unique indices.

pass parameters as item_constraints[<param name>][<idx:0..n>]

item_constraint_criteria[0..n]

Parameters for item_constraint_criteria. Multiple item_constraint_criteria can be passed by specifying unique indices.

pass parameters as item_constraint_criteria[<param name>][<idx:0..n>]

coupon_constraints[0..n]

Parameters for coupon_constraints. Multiple coupon_constraints can be passed by specifying unique indices.

pass parameters as coupon_constraints[<param name>][<idx:0..n>]

Returns

coupon

Coupon object

Resource object representing coupon