# Update a coupon for items > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). [Idempotency Supported](/docs/api/idempotency) This API updates a coupon that is created for a specific promotion or offers. ## Sample Request ### Default #### cURL ```bash curl https://{site}.chargebee.com/api/v2/coupons/sample_coupon/update_for_items \ -X POST \ -u {site_api_key}:\ -d discount_percentage=20 \ -d "item_constraints[constraint][0]"="ALL" \ -d "item_constraints[item_type][0]"="PLAN" \ -d "item_constraints[constraint][1]"="ALL" \ -d "item_constraints[item_type][1]"="ADDON" ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = Coupon.UpdateForItems("sample_coupon") .DiscountPercentage(20) .ItemConstraintConstraint(0, Coupon.CouponItemConstraint.ConstraintEnum.All) .ItemConstraintItemType(0, Coupon.CouponItemConstraint.ItemTypeEnum.Plan) .ItemConstraintConstraint(1, Coupon.CouponItemConstraint.ConstraintEnum.All) .ItemConstraintItemType(1, Coupon.CouponItemConstraint.ItemTypeEnum.Addon) .Request(); Coupon coupon = result.Coupon; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" couponAction "github.com/chargebee/chargebee-go/v3/actions/coupon" "github.com/chargebee/chargebee-go/v3/models/coupon" couponEnum "github.com/chargebee/chargebee-go/v3/models/coupon/enum" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := couponAction.UpdateForItems("sample_coupon", &coupon.UpdateForItemsRequestParams{ ItemConstraints : []*coupon.UpdateForItemsItemConstraintParams{ { Constraint : couponEnum.ItemConstraintConstraintAll, ItemType : couponEnum.ItemConstraintItemTypePlan, }, { Constraint : couponEnum.ItemConstraintConstraintAll, ItemType : couponEnum.ItemConstraintItemTypeAddon, }, }, DiscountPercentage : chargebee.Float64(20), }).Request() if err != nil { fmt.Println(err) } else { Coupon := res.Coupon } } ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v4" ) func main() { config := &chargebee.ClientConfig{ SiteName: "{site}", ApiKey: "{site_api_key}", } client := chargebee.NewClient(config) req := &chargebee.CouponUpdateForItemsRequest{ ItemConstraints : []*chargebee.CouponUpdateForItemsItemConstraint{ { Constraint : chargebee.CouponItemConstraintConstraintAll, ItemType : chargebee.CouponItemConstraintItemTypePlan, }, { Constraint : chargebee.CouponItemConstraintConstraintAll, ItemType : chargebee.CouponItemConstraintItemTypeAddon, }, }, DiscountPercentage : chargebee.Float64(20), } res, err := client.Coupon.UpdateForItems("sample_coupon", req) if err != nil { fmt.Println(err) } else { Coupon := res.Coupon } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = Coupon.updateForItems("sample_coupon") .discountPercentage(20.0) .itemConstraintConstraint(0, Coupon.ItemConstraint.Constraint.ALL) .itemConstraintItemType(0, Coupon.ItemConstraint.ItemType.PLAN) .itemConstraintConstraint(1, Coupon.ItemConstraint.Constraint.ALL) .itemConstraintItemType(1, Coupon.ItemConstraint.ItemType.ADDON) .request(); Coupon coupon = result.coupon(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.coupon.Coupon; import com.chargebee.v4.models.coupon.params.CouponUpdateForItemsParams; import com.chargebee.v4.models.coupon.responses.CouponUpdateForItemsResponse; import java.util.List; public class CouponUpdateForItems { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); CouponUpdateForItemsParams.ItemConstraintsParams itemConstraint0 = CouponUpdateForItemsParams.ItemConstraintsParams.builder() .constraint(CouponUpdateForItemsParams.ItemConstraintsParams.Constraint.ALL) .itemType(CouponUpdateForItemsParams.ItemConstraintsParams.ItemType.PLAN) .build(); CouponUpdateForItemsParams.ItemConstraintsParams itemConstraint1 = CouponUpdateForItemsParams.ItemConstraintsParams.builder() .constraint(CouponUpdateForItemsParams.ItemConstraintsParams.Constraint.ALL) .itemType(CouponUpdateForItemsParams.ItemConstraintsParams.ItemType.ADDON) .build(); List itemConstraintsList = List.of(itemConstraint0, itemConstraint1); CouponUpdateForItemsParams params = CouponUpdateForItemsParams.builder() .discountPercentage(20.0) .itemConstraints(itemConstraintsList) .build(); CouponUpdateForItemsResponse response = client .coupons() .updateForItems("sample_coupon", params); Coupon coupon = response.getCoupon(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.coupon.updateForItems("sample_coupon", { item_constraints: [ { constraint: "all", item_type: "plan" }, { constraint: "all", item_type: "addon" } ], discount_percentage: 20 }); console.log(result); const coupon = result.coupon; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->coupon()->updateForItems("sample_coupon", [ "item_constraints" => [ [ "constraint" => "all", "item_type" => "plan" ], [ "constraint" => "all", "item_type" => "addon" ] ], "discount_percentage" => 20 ]); $coupon = $result->coupon; ``` #### Python ```python import chargebee from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.Coupon.update_for_items("sample_coupon", cb_client.Coupon.UpdateForItemsParams( item_constraints=[ cb_client.Coupon.UpdateForItemsItemConstraintParams( constraint=chargebee.Coupon.ItemConstraintConstraint.ALL, item_type=chargebee.Coupon.ItemConstraintItemType.PLAN ), cb_client.Coupon.UpdateForItemsItemConstraintParams( constraint=chargebee.Coupon.ItemConstraintConstraint.ALL, item_type=chargebee.Coupon.ItemConstraintItemType.ADDON ) ], discount_percentage=20 ) ) coupon = response.coupon ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::Coupon.update_for_items("sample_coupon",{ :discount_percentage => 20, :item_constraints => [ { :constraint => "ALL", :item_type => "PLAN" }, { :constraint => "ALL", :item_type => "ADDON" } ] }) coupon = result.coupon ``` ### Update a coupon for items #### cURL ```bash curl https://{site}.chargebee.com/api/v2/coupons/welcome_offer/update_for_items \ -X POST \ -u {site_api_key}:\ -d name="return_offer" \ -d discount_percentage=25 \ -d "coupon_constraints[entity_type][0]"="CUSTOMER" \ -d "coupon_constraints[type][0]"="EXISTING_CUSTOMER" \ -d "coupon_constraints[value][0]"="based_on_invoice" ``` #### .NET ```dotnet using ChargeBee.Api; using ChargeBee.Models; ApiConfig.Configure("{site}","{site_api_key}"); EntityResult result = Coupon.UpdateForItems("welcome_offer") .Name("return_offer") .DiscountPercentage(25) .CouponConstraintEntityType(0, Coupon.CouponCouponConstraint.EntityTypeEnum.Customer) .CouponConstraintType(0, Coupon.CouponCouponConstraint.TypeEnum.ExistingCustomer) .CouponConstraintValue(0, "based_on_invoice") .Request(); Coupon coupon = result.Coupon; ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v3" couponAction "github.com/chargebee/chargebee-go/v3/actions/coupon" "github.com/chargebee/chargebee-go/v3/models/coupon" couponEnum "github.com/chargebee/chargebee-go/v3/models/coupon/enum" ) func main() { chargebee.Configure("{site_api_key}","{site}"); res,err := couponAction.UpdateForItems("welcome_offer", &coupon.UpdateForItemsRequestParams{ CouponConstraints : []*coupon.UpdateForItemsCouponConstraintParams{ { EntityType : couponEnum.CouponConstraintEntityTypeCustomer, Type : couponEnum.CouponConstraintTypeExistingCustomer, Value : "based_on_invoice", }, }, Name : "return_offer", DiscountPercentage : chargebee.Float64(25), }).Request() if err != nil { fmt.Println(err) } else { Coupon := res.Coupon } } ``` #### Go ```go package main import ( "fmt" "github.com/chargebee/chargebee-go/v4" ) func main() { config := &chargebee.ClientConfig{ SiteName: "{site}", ApiKey: "{site_api_key}", } client := chargebee.NewClient(config) req := &chargebee.CouponUpdateForItemsRequest{ CouponConstraints : []*chargebee.CouponUpdateForItemsCouponConstraint{ { EntityType : chargebee.CouponCouponConstraintEntityTypeCustomer, Type : chargebee.CouponCouponConstraintTypeExistingCustomer, Value : "based_on_invoice", }, }, Name : "return_offer", DiscountPercentage : chargebee.Float64(25), } res, err := client.Coupon.UpdateForItems("welcome_offer", req) if err != nil { fmt.Println(err) } else { Coupon := res.Coupon } } ``` #### Java ```java import com.chargebee.*; import com.chargebee.ListResult; import com.chargebee.models.*; import com.chargebee.models.enums.*; import java.io.IOException; public class Sample { public static void main(String args[]) throws IOException, Exception { Environment.configure("{site}", "{site_api_key}"); Result result = Coupon.updateForItems("welcome_offer") .name("return_offer") .discountPercentage(25.0) .couponConstraintEntityType(0, Coupon.CouponConstraint.EntityType.CUSTOMER) .couponConstraintType(0, Coupon.CouponConstraint.Type.EXISTING_CUSTOMER) .couponConstraintValue(0, "based_on_invoice") .request(); Coupon coupon = result.coupon(); } } ``` #### Java ```java import com.chargebee.v4.client.ChargebeeClient; import com.chargebee.v4.models.coupon.Coupon; import com.chargebee.v4.models.coupon.params.CouponUpdateForItemsParams; import com.chargebee.v4.models.coupon.responses.CouponUpdateForItemsResponse; import java.util.List; public class CouponUpdateForItems { public static void main(String[] args) { ChargebeeClient client = ChargebeeClient.builder() .apiKey("{site_api_key}") .siteName("{site}") .build(); CouponUpdateForItemsParams.CouponConstraintsParams couponConstraint0 = CouponUpdateForItemsParams.CouponConstraintsParams.builder() .entityType(CouponUpdateForItemsParams.CouponConstraintsParams.EntityType.CUSTOMER) .type(CouponUpdateForItemsParams.CouponConstraintsParams.Type.EXISTING_CUSTOMER) .value("based_on_invoice") .build(); List couponConstraintsList = List.of(couponConstraint0); CouponUpdateForItemsParams params = CouponUpdateForItemsParams.builder() .name("return_offer") .discountPercentage(25.0) .couponConstraints(couponConstraintsList) .build(); CouponUpdateForItemsResponse response = client .coupons() .updateForItems("welcome_offer", params); Coupon coupon = response.getCoupon(); } } ``` #### Node.js ```node import Chargebee from "chargebee"; const chargebee = new Chargebee({ site: "{site}", apiKey: "{site_api_key}", }); try { const result = await chargebee.coupon.updateForItems("welcome_offer", { coupon_constraints: [ { entity_type: "customer", type: "existing_customer", value: "based_on_invoice" } ], name: "return_offer", discount_percentage: 25 }); console.log(result); const coupon = result.coupon; } catch (err) { console.log(err); } ``` #### PHP ```php "{site}", "apiKey" => "{site_api_key}", ]); $result = $chargebee->coupon()->updateForItems("welcome_offer", [ "coupon_constraints" => [ [ "entity_type" => "customer", "type" => "existing_customer", "value" => "based_on_invoice" ] ], "name" => "return_offer", "discount_percentage" => 25 ]); $coupon = $result->coupon; ``` #### Python ```python import chargebee from chargebee import Chargebee cb_client = Chargebee(api_key="{site_api_key}", site="{site}") response = cb_client.Coupon.update_for_items("welcome_offer", cb_client.Coupon.UpdateForItemsParams( coupon_constraints=[ cb_client.Coupon.UpdateForItemsCouponConstraintParams( entity_type=chargebee.Coupon.CouponConstraintEntityType.CUSTOMER, type=chargebee.Coupon.CouponConstraintType.EXISTING_CUSTOMER, value="based_on_invoice" ) ], name="return_offer", discount_percentage=25 ) ) coupon = response.coupon ``` #### Ruby ```ruby require 'chargebee' ChargeBee.configure(:site => "{site}", :api_key => "{site_api_key}") result = ChargeBee::Coupon.update_for_items("welcome_offer",{ :name => "return_offer", :discount_percentage => 25, :coupon_constraints => [ { :entity_type => "CUSTOMER", :type => "EXISTING_CUSTOMER", :value => "based_on_invoice" } ] }) coupon = result.coupon ``` ## Sample Response ```json { "coupon": { "apply_discount_on": "not_applicable", "apply_on": "each_specified_item", "created_at": 1517495316, "discount_percentage": 20, "discount_type": "percentage", "duration_type": "forever", "id": "sample_coupon", "item_constraints": [ { "constraint": "all", "item_type": "plan" }, {..} ], "name": "Sample Coupon", "object": "coupon", "redemptions": 0, "resource_version": 1517495317068, "status": "active", "updated_at": 1517495317 } } ``` ## URL Format **POST** https://[site].chargebee.com/api/v2/coupons/{coupon-id}/update_for_items ## Input Parameters - `name` (optional, 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](https://www.urlencoder.org/) 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. Possible enum values: - `fixed_amount` A fixed amount is deducted as a discount. The discount amount is specified in `[discount_amount](/docs/api/coupons/create-a-coupon-for-items#discount_amount)`. [Learn more](https://www.chargebee.com/docs/2.0/coupons.html#fixed-amount-coupons) about `fixed_amount` coupons. - `percentage` A percentage of the original price is deducted as a discount. The discount percentage is specified in `[discount_percentage](/docs/api/coupons/create-a-coupon-for-items#discount_percentage)`. [Learn more](https://www.chargebee.com/docs/2.0/coupons.html#percentage-coupons) 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](/docs/api/coupons/create-a-coupon-for-items#discount_quantity)`. The `offer_quantity` option is valid only when `[apply_on](/docs/api/coupons/create-a-coupon-for-items#apply_on)` is set to `each_specified_item` and the `[pricing_model](/docs/api/item_prices/item_price-object#pricing_model)` of the item price is `per_unit`. [Learn more](https://www.chargebee.com/docs/2.0/coupons.html#offer-quantity-coupons) 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](/docs/api/currencies) . - `currency_code` (required if Multicurrency is enabled, string, max chars=3) The currency code ([ISO 4217 format](https://www.chargebee.com/docs/2.0/supported-currencies.html) ) 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 [item price](/docs/api/item_prices) , without affecting the total quantity sold. This parameter is applicable only when the `[discount_type](/docs/api/coupons/create-a-coupon-for-items#discount_type)` is set to `offer_quantity` . - `apply_on` (optional, enumerated string) The amount on the invoice to which the coupon is applied. Possible 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`](/docs/api/coupons/create-a-coupon-for-items#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. Possible 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. - `valid_from` (optional, timestamp(UTC) in seconds) The date from which the coupon can be applied to subscriptions. - `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](/docs/api/invoices/invoice-object#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](/docs/api/advanced-features) . - `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](/docs/api/coupons/coupon-object#duration_type)` is `[limited_period](/docs/api/coupons/coupon-object#duration_type)` . - `period_unit` (optional, enumerated string) The unit of time for period. Applicable only when `[duration_type](/docs/api/coupons/coupon-object#duration_type)` is `[limited_period](/docs/api/coupons/coupon-object#duration_type)` . Possible 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. - `item_constraints` (optional, array) Parameters for item\_constraints - `constraint` (required, enumerated string) Constraint applicable for the item Possible enum values: - `none` Coupon not applicable to any items. - `all` Coupon applicable to all items. - `specific` Coupon applicable to specific items. - `criteria` Coupon applicable based on criteria. - `item_type` (required, enumerated string) Item type for which this criteria is applicable for. Possible enum values: - `plan` Plan - `addon` Addon - `charge` Charge - `item_price_ids` (optional, array) 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](https://www.chargebee.com/docs/2.0/plans.html#defining-price-points-for-plan), [Addons](https://www.chargebee.com/docs/2.0/addons.html#defining-price-points-for-an-addon), and [Charges](https://www.chargebee.com/docs/2.0/charges.html#defining-price-points-for-a-charge). - `item_constraint_criteria` (optional, array) Parameters for item\_constraint\_criteria - `item_type` (optional, enumerated string) Item type for which this criteria is applicable for. Possible enum values: - `plan` Plan is a type of item - `addon` Addon is a type of item - `charge` Charge is a type of item - `item_family_ids` (optional, array) List of families for which this coupon is applicable. - `currencies` (optional, array) List of currencies ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html) ) for which this coupon is applicable. - `item_price_periods` (optional, array) Pass the item price period units for this criterion. `period` followed by `period_units`. Such as `[1 day,1 week,3 month,6 month]` - `coupon_constraints` (optional, array) Parameters for `coupon_constraints`. Multiple `coupon_constraints` can be passed by specifying unique indices. - `entity_type` (required, enumerated string) The resource type for the constraint. This, along with `type` and `value` , helps define the specific rule applied. Possible enum values: - `customer` The constraint is based on `customer` records. - `type` (required, enumerated string) The type of coupon constraint. Possible enum values: - `max_redemptions` The coupon can be redeemed up to a set number of times for a specific resource type. The maximum redemptions are specified using `value` , and the resource type is specified using `entity_type`. For example, if `entity_type` is `customer` and `value` is `10` then the coupon can only be redeemed up to 10 times for any particular `customer` record. - `unique_by` Indicates - when `entity_type` is `customer` - that the coupon can be redeemed only once for every unique value of a specified `customer` attribute. The `customer` attribute is specified using `value`. For example, if `value` is `email` , then the coupon can be redeemed only once for every unique value of `customer.email`. In other words, when there are multiple `customer` records with the same value for `email` , once the coupon has been redeemed for one of those customer records, no further redemptions of the coupon are allowed for any of those `customer` records. - `existing_customer` The coupon is applicable only for existing customer(s). A customer will be considered as `existing_customer` when they have at least one non-void, non-zero-dollar invoice. - `new_customer` The coupon is applicable only for new customer(s). A customer will be considered as `new_customer` when they do not have any prior non-void, non-zero-dollar invoices. - `value` (optional, string, max chars=65k) 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`. ## Returns - `coupon` (Coupon object) Resource object representing coupon