# Update a coupon

> For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt).


[Idempotency Supported](/docs/api/v2/pcv-1/idempotency)

When updating coupons that are already linked to an invoice or subscription you can only update the following parameters:

-   name
-   invoice name
-   plan\_constraint - Applicable when apply\_on is set as each\_specified\_item. Allows change from none to all, none to specific, and specific to all.
-   addon\_constraint - Applicable when apply\_on is set as each\_specified\_item. Allows change from none to all, none to specific, and specific to all.
-   plan\_ids - Applicable when plan\_constraint is set as specific. Allows addition of new plan\_ids. However, existing plan\_ids cannot be removed.
-   addon\_ids - Applicable when addon\_constraint is set as specific. Allows addition of new addon\_ids. However, existing addon\_ids cannot be removed.
-   valid\_till
-   max\_redemptions
-   invoice\_notes
-   included\_in\_mrr
-   meta\_data

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/coupons/welcome_offer \
     -u {site_api_key}:\
     -d discount_type="PERCENTAGE" \
     -d discount_percentage=10 \
     -d apply_on="INVOICE_AMOUNT" \
     -d duration_type="ONE_TIME"
```

#### .NET

```dotnet
using ChargeBee.Api;
using ChargeBee.Models;

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Coupon.Update("welcome_offer")
		.DiscountType(Coupon.DiscountTypeEnum.Percentage)
		.DiscountPercentage(10)
		.ApplyOn(Coupon.ApplyOnEnum.InvoiceAmount)
		.DurationType(Coupon.DurationTypeEnum.OneTime)
		.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.Update("welcome_offer", &coupon.UpdateRequestParams{
        DiscountType : couponEnum.DiscountTypePercentage,
        DiscountPercentage : chargebee.Float64(10),
        ApplyOn : couponEnum.ApplyOnInvoiceAmount,
        DurationType : couponEnum.DurationTypeOneTime,
    }).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.CouponUpdateRequest{
    DiscountType : chargebee.CouponDiscountTypePercentage,
    DiscountPercentage : chargebee.Float64(10),
    ApplyOn : chargebee.CouponApplyOnInvoiceAmount,
    DurationType : chargebee.CouponDurationTypeOneTime,
}
  res, err := client.Coupon.Update("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.update("welcome_offer")
            .discountType(Coupon.DiscountType.PERCENTAGE)
            .discountPercentage(10.0)
            .applyOn(Coupon.ApplyOn.INVOICE_AMOUNT)
            .durationType(Coupon.DurationType.ONE_TIME)
            .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.CouponUpdateParams;
import com.chargebee.v4.models.coupon.responses.CouponUpdateResponse;

public class CouponUpdate {

    public static void main(String[] args) {
        ChargebeeClient client = ChargebeeClient.builder()
            .apiKey("{site_api_key}")
            .siteName("{site}")
            .build();

        CouponUpdateParams params = CouponUpdateParams.builder()
            .discountType(CouponUpdateParams.DiscountType.PERCENTAGE)
            .discountPercentage(10.0)
            .applyOn(CouponUpdateParams.ApplyOn.INVOICE_AMOUNT)
            .durationType(CouponUpdateParams.DurationType.ONE_TIME)
            .build();

        CouponUpdateResponse response = client
            .coupons()
            .update("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.update("welcome_offer", {
        discount_type: "percentage",
        discount_percentage: 10,
        apply_on: "invoice_amount",
        duration_type: "one_time"
    });

    console.log(result);
    const coupon = result.coupon;
} catch (err) {
    console.log(err);
}
```

#### PHP

```php
<?php

require __DIR__ . '/vendor/autoload.php';

use Chargebee\ChargebeeClient;

$chargebee = new ChargebeeClient(options: [
    "site" => "{site}",
    "apiKey" => "{site_api_key}",
]);
$result = $chargebee->coupon()->update("welcome_offer", [
    "discount_type" => "percentage",
    "discount_percentage" => 10,
    "apply_on" => "invoice_amount",
    "duration_type" => "one_time"
]);
$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("welcome_offer",
    cb_client.Coupon.UpdateParams(
        discount_type=chargebee.Coupon.DiscountType.PERCENTAGE,
        discount_percentage=10,
        apply_on=chargebee.Coupon.ApplyOn.INVOICE_AMOUNT,
        duration_type=chargebee.Coupon.DurationType.ONE_TIME
    )
)
coupon = response.coupon
```

#### Ruby

```ruby
require 'chargebee'

ChargeBee.configure(:site => "{site}",
  :api_key => "{site_api_key}")

result = ChargeBee::Coupon.update("welcome_offer",{
  :discount_type => "PERCENTAGE",
  :discount_percentage => 10,
  :apply_on => "INVOICE_AMOUNT",
  :duration_type => "ONE_TIME"
})

coupon = result.coupon
```

## Sample Response

```json
{
  "coupon": {
    "addon_constraint": "not_applicable",
    "apply_discount_on": "not_applicable",
    "apply_on": "invoice_amount",
    "created_at": 1517505791,
    "discount_percentage": 10,
    "discount_type": "percentage",
    "duration_type": "one_time",
    "id": "welcome_offer",
    "name": "welcome Offer",
    "object": "coupon",
    "plan_constraint": "not_applicable",
    "redemptions": 0,
    "resource_version": 1517505791000,
    "status": "active",
    "updated_at": 1517505791
  }
}
```

## URL Format

**POST** https://[site].chargebee.com/api/v2/coupons/{coupon-id}

## 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/v2/pcv-1/coupons/create-a-coupon#discount_amount)`.
      
      [Learn more](https://www.chargebee.com/docs/1.0/coupons.html#fixed-amount) 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/v2/pcv-1/coupons/create-a-coupon#discount_percentage)`.
      
      [Learn more](https://www.chargebee.com/docs/1.0/coupons.html#percentage) 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](/docs/api/v2/pcv-1/coupons/create-a-coupon#discount_quantity)`. The `offer_quantity` option is valid only when `[apply_on](/docs/api/v2/pcv-1/coupons/create-a-coupon#apply_on)` is set to `each_specified_item` and the `pricing_model` of the [plan](/docs/api/v2/pcv-1/plans/plan-object#pricing_model) or addon is `per_unit`.
      
      [Learn more](https://www.chargebee.com/docs/1.0/coupons.html#offer-quantity) 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 [plan](/docs/api/v2/pcv-1/plans) or [addon](/docs/api/v2/pcv-1/addons) , without affecting the total quantity sold. This parameter is applicable only when the `[discount_type](/docs/api/v2/pcv-1/coupons/create-a-coupon#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`
      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.
  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_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/v2/pcv-1/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.

- `plan_constraint` (optional, enumerated string)
  Plans the coupon can be applied to.
  Possible enum values:
    - `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.
  Possible enum values:
    - `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.

## Returns

- `coupon` (Coupon object)
  Resource object representing coupon