# Create 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)

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

## Sample Request

#### cURL

```bash
curl  https://{site}.chargebee.com/api/v2/coupons \
     -u {site_api_key}:\
     -d id="sample_offer" \
     -d name="Sample Offer" \
     -d discount_type="FIXED_AMOUNT" \
     -d discount_amount=500 \
     -d apply_on="INVOICE_AMOUNT" \
     -d duration_type="FOREVER"
```

#### .NET

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

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = Coupon.Create()
		.Id("sample_offer")
		.Name("Sample Offer")
		.DiscountType(Coupon.DiscountTypeEnum.FixedAmount)
		.DiscountAmount(500)
		.ApplyOn(Coupon.ApplyOnEnum.InvoiceAmount)
		.DurationType(Coupon.DurationTypeEnum.Forever)
		.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.Create(&coupon.CreateRequestParams{
        Id : "sample_offer",
        Name : "Sample Offer",
        DiscountType : couponEnum.DiscountTypeFixedAmount,
        DiscountAmount : chargebee.Int64(500),
        ApplyOn : couponEnum.ApplyOnInvoiceAmount,
        DurationType : couponEnum.DurationTypeForever,
    }).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.CouponCreateRequest{
    Id : "sample_offer",
    Name : "Sample Offer",
    DiscountType : chargebee.CouponDiscountTypeFixedAmount,
    DiscountAmount : chargebee.Int64(500),
    ApplyOn : chargebee.CouponApplyOnInvoiceAmount,
    DurationType : chargebee.CouponDurationTypeForever,
}
  res, err := client.Coupon.Create(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.create()
            .id("sample_offer")
            .name("Sample Offer")
            .discountType(Coupon.DiscountType.FIXED_AMOUNT)
            .discountAmount(500L)
            .applyOn(Coupon.ApplyOn.INVOICE_AMOUNT)
            .durationType(Coupon.DurationType.FOREVER)
            .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.CouponCreateParams;
import com.chargebee.v4.models.coupon.responses.CouponCreateResponse;

public class CouponCreate {

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

        CouponCreateParams params = CouponCreateParams.builder()
            .id("sample_offer")
            .name("Sample Offer")
            .discountType(CouponCreateParams.DiscountType.FIXED_AMOUNT)
            .discountAmount(500L)
            .applyOn(CouponCreateParams.ApplyOn.INVOICE_AMOUNT)
            .durationType(CouponCreateParams.DurationType.FOREVER)
            .build();

        CouponCreateResponse response = client.coupons().create(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.create({
        id: "sample_offer",
        name: "Sample Offer",
        discount_type: "fixed_amount",
        discount_amount: 500,
        apply_on: "invoice_amount",
        duration_type: "forever"
    });

    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()->create([
    "id" => "sample_offer",
    "name" => "Sample Offer",
    "discount_type" => "fixed_amount",
    "discount_amount" => 500,
    "apply_on" => "invoice_amount",
    "duration_type" => "forever"
]);
$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.create(
    cb_client.Coupon.CreateParams(
        id="sample_offer",
        name="Sample Offer",
        discount_type=chargebee.Coupon.DiscountType.FIXED_AMOUNT,
        discount_amount=500,
        apply_on=chargebee.Coupon.ApplyOn.INVOICE_AMOUNT,
        duration_type=chargebee.Coupon.DurationType.FOREVER
    )
)
coupon = response.coupon
```

#### Ruby

```ruby
require 'chargebee'

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

result = ChargeBee::Coupon.create({
  :id => "sample_offer",
  :name => "Sample Offer",
  :discount_type => "FIXED_AMOUNT",
  :discount_amount => 500,
  :apply_on => "INVOICE_AMOUNT",
  :duration_type => "FOREVER"
})

coupon = result.coupon
```

## Sample Response

```json
{
  "coupon": {
    "addon_constraint": "not_applicable",
    "apply_discount_on": "not_applicable",
    "apply_on": "invoice_amount",
    "created_at": 1517505786,
    "currency_code": "USD",
    "discount_amount": 500,
    "discount_type": "fixed_amount",
    "duration_type": "forever",
    "id": "sample_offer",
    "name": "Sample Offer",
    "object": "coupon",
    "plan_constraint": "not_applicable",
    "redemptions": 0,
    "resource_version": 1517505786000,
    "status": "active",
    "updated_at": 1517505786
  }
}
```

## URL Format

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

## Input Parameters

- `id` (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](https://www.urlencoder.org/) 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](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` (required, 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.

- `status` (optional, enumerated string, default=active)
  Status of the coupon.
  Possible enum values:
    - `active`
      Can be applied to a subscription.
    - `archived`
      Cannot be applied to a subscription. Existing associations remain unaffected.

## Returns

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