POST /coupons/create_for_items

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

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`discount_quantity`	Integer	No	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` .
`included_in_mrr`	Boolean	No	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` .
`invoice_name`	String	No	Display name used in invoice. If it is not configured then name is used in invoice.
`currency_code`	String	No	The currency code (ISO 4217 format ) of the coupon. Applicable for fixed_amount coupons alone.
`meta_data`	Object	No	A collection of key-value pairs that provides extra information about the coupon. Note: There's a character limit of 65,535. [Learn more](/docs/api/advanced-features) .
`valid_from`	Integer	No	The date from which the coupon can be applied to subscriptions.
`valid_till`	Integer	No	Date upto which the coupon can be applied to new subscriptions.
`max_redemptions`	Integer	No	Maximum number of times this coupon can be redeemed. Note: If not specified, the coupon can be redeemed an indefinite number of times. .
`status`	String	No	Status of the coupon. * future - The coupon is scheduled to start at a future date and cannot be applied to a subscription. From the valid_from date, the status changes to active. * expired - Cannot be applied to a subscription. A coupon may expire due to exceeding `max_redemptions` or `valid_till` date is past. Existing associations remain unaffected. * archived - Cannot be applied to a subscription. Existing associations remain unaffected. * active - Can be applied to a subscription. * deleted - Indicates the coupon has been deleted. Valid values: `"active"` `"archived"` Default value: "active"
`duration_month`	Integer	No	(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.
`invoice_notes`	String	No	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.
`coupon_constraints`	Object	No	Parameters for `coupon_constraints`. Multiple `coupon_constraints` can be passed by specifying unique indices.
`coupon_constraints.type[]`	Array	Yes
`coupon_constraints.value[]`	Array	No	The value of the coupon constraint. The possible values depend on the value of `constraints[type]`: When `type` is `unique_by`, then `value` can be `email` or `id`. When `type` is `max_redemptions`, then `value` can be any integer in the range `1` `coupon.max_redemptions`, inclusive. When type is `new_customer` or `existing_customer` then `value` can be `based_on_invoice`.
`coupon_constraints.entity_type[]`	Array	Yes
`item_constraints`	Object	No	Parameters for item_constraints
`item_constraints.constraint[]`	Array	Yes
`item_constraints.item_price_ids[]`	Array	No	List of item price ids for which this coupon is applicable. Note: When specifying a value for `item_price_ids`, make sure that the value is wrapped in square brackets (`[]`), for example: `[cbdemo_advanced-USD-Daily]` instead of `cbdemo_advanced-USD-Daily`; otherwise, a `param_wrong_value` error returns. For information about `item_price_ids`, refer to Defining Price Points in Plans, Addons, and Charges.
`item_constraints.item_type[]`	Array	Yes
`id`	String	Yes	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. .
`apply_on`	String	Yes	The amount on the invoice to which the coupon is applied. * invoice_amount - The coupon is applied to the invoice `sub_total` . * each_unit_of_specified_items - Discount will be applied to each unit of plan and addon items specified. * 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. * specified_items_total - Discount will be applied to the total of plan and addon items specified. Valid values: `"each_specified_item"` `"invoice_amount"`
`period_unit`	String	No	The unit of time for period. Applicable only when `duration_type` is `limited_period` . * month - A period of 1 calendar month. * week - A period of 7 days. * year - A period of 1 calendar year. * day - A period of 24 hours. Valid values: `"month"` `"day"` `"week"` `"year"`
`name`	String	Yes	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. .
`period`	Integer	No	The duration of time for which the coupon is attached to the subscription, in `period_units`. Applicable only when `duration_type` is `limited_period` .
`duration_type`	String	No	Specifies the time duration for which this coupon is attached to the subscription. * forever - The coupon is attached to the subscription and applied on the invoices until explicitly removed. * 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. * 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` . Valid values: `"limited_period"` `"forever"` `"one_time"` Default value: "forever"
`discount_type`	String	No	Specifies the type of discount to be applied. * 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. * fixed_amount - A fixed amount is deducted as a discount. The discount amount is specified in `discount_amount`. Learn more about `fixed_amount` 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. Valid values: `"fixed_amount"` `"offer_quantity"` `"percentage"` Default value: "percentage"
`discount_amount`	Integer	No	The value of the deduction. The format of this value depends on the kind of currency .
`discount_percentage`	Number	No	The percentage of the original amount that should be deducted from it.
`item_constraint_criteria`	Object	No	Parameters for item_constraint_criteria
`item_constraint_criteria.currencies[]`	Array	No	List of currencies (ISO 4217 format ) for which this coupon is applicable.
`item_constraint_criteria.item_price_periods[]`	Array	No	Pass the item price period units for this criterion. `period` followed by `period_units`. Such as `[1 day,1 week,3 month,6 month]`
`item_constraint_criteria.item_type[]`	Array	No
`item_constraint_criteria.item_family_ids[]`	Array	No	List of families for which this coupon is applicable.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.