Chargebee Site Name

Chargebee

_objects

_pull_events

Overview {#overview}
--------------------

Coupons are deductions applied to invoices or invoice line items. They're designed to be consumed by your customers directly. A coupon deduction can either be for a fixed amount or for a percentage of the amount of the invoice or line item.  
**Note:**

If you wish to provide discounts to your customers via API or the Chargebee app, see [Discounts API](/docs/api/discounts)

Order of application of coupons and discounts {#precedence}
-----------------------------------------------------------

When both <coupons> and <discounts> are applied simultaneously to a [subscription](subscriptions) or [one-time invoice](invoices?prod_cat_ver=2#create_invoice_for_items_and_one-time_charges), they're applied in the following order:  
{#c8112732-82d8-406d-adad-a832fcb071a5}

|---|---------------------------------------|--------------------------------------------------------------------------------------------------------------------|
|   | **Summary**                           | **Description**                                                                                                    |
| 1 | Line-level, fixed amount coupons      | `coupon` with apply_on{#a9499b7a-8534-4a0c-b4d4-e66ab1dc88d9} = `each_specified_item` and `discount_type` = `flat` |
| 2 | Line-level, fixed amount discounts    | `discount` with `apply_on` = `specific_item_price` and `type` = `fixed_amount`                                     |
| 3 | Line-level, percentage coupons        | `coupon` with `apply_on` = `each_specified_item` and `discount_type` = `percentage`                                |
| 4 | Line-level, percentage discounts      | `discount` with `apply_on` = `specific_item_price` and `type` = `percentage`                                       |
| 5 | Invoice-level, fixed amount coupons   | `coupon` with `apply_on` = `invoice_amount` and `discount_type` = `flat`                                           |
| 6 | Invoice-level, fixed amount discounts | `discount` with `apply_on` = `invoice_amount` and `type` = `fixed_amount`                                          |
| 7 | Invoice-level, percentage coupons     | `coupon` with `apply_on` = `invoice_amount` and `discount_type` = `percentage`                                     |
| 8 | Invoice-level, percentage discounts   | `discount` with `apply_on` = `invoice_amount` and `type` = `percentage`                                            |



For example, consider the following scenario:

A subscription is created with:

* a plan price of $200 per month
* an addon price of $20 per month
* a flat $5 invoice discount
* a 1% off coupon on the addon
* a flat $2 coupon on the invoice

The above coupons and discount are applied in the following order:  

|---|---------------------------------------------|-----------------------------------------------|
|   | **Discount or coupon applied**              | **Subtotal at each step**                     |
| 1 | Initial subtotal (plan price + addon price) | $200 + $20 = $220                             |
| 2 | 1% off coupon on the addon                  | $200 + $(20 - 0.02) = $200 + $19.98 = $219.98 |
| 3 | Flat $2 coupon on the invoice               | $219.98 - $2 = $217.98                        |
| 4 | Flat $5 invoice discount                    | $217.98 - $5 = **$212.98**                    |



The amount on the invoice to which the coupon is applied. \* 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 item price specified by `item_price_id`.


Timestamp indicating when this coupon was archived.


List of constraints applicable on the redemption of this coupon.


The resource type for the constraint. This, along with `type` and `value`, helps define the specific rule applied. \* customer - The constraint is based on `customer` records.


Type of coupon constraints \* 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. \* 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.


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.



Timestamp indicating when this coupon is created.


The currency code ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html)) of the coupon. Applicable for *fixed_amount* coupons alone.


The value of the deduction. The format of this value depends on the [kind of currency](/docs/api#currencies).


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


The type of deduction \* percentage - The specified percentage will be deducted. \* fixed_amount - The specified amount will be deducted.


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`.


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.


Display name used in invoice. If it is not configured then name is used in invoice.


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_notes) displayed on the invoice PDF.


List of currencies ([ISO 4217 format](https://www.chargebee.com/docs/supported-currencies.html)) for which this coupon is applicable.


List of families for which this coupon is applicable.


List of frequencies for which this coupon is applicable. Allowed frequencies are \[day, week, month, year\].


Item type for which this criteria is applicable for. \* charge - Charge is a type of item \* plan - Plan is a type of item \* addon - Addon is a type of item


Constraint applicable for the item \* specific - Coupon applicable to specific items. \* all - Coupon applicable to all items. \* criteria - Coupon applicable based on criteria. \* none - Coupon not applicable to any items.


List of item price ids for which this coupon is applicable.


Item type for which this criteria is applicable for. \* charge - Charge \* plan - Plan \* addon - Addon


Maximum number of times this coupon can be redeemed.  
**Note:**


If not specified, the coupon can be redeemed an indefinite number of times.


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.


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_duration_type) is [limited_period](/docs/api/coupons?#coupon_duration_type).


The unit of time for period. Applicable only when [duration_type](/docs/api/coupons?#coupon_duration_type) is [limited_period](/docs/api/coupons?#coupon_duration_type). \* 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.


The number of times this coupon has been redeemed.


The version number of this resource. For every change made to the resource, `resource_version` is updated with a new timestamp in milliseconds.


Status of the coupon. \* expired - Cannot be applied to a subscription. A coupon may expire due to exceeding [max_redemptions](/docs/api/coupons?#coupon_max_redemptions) or [valid_till](/docs/api/coupons?#coupon_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.


Timestamp indicating when this coupon was last updated.   
Note that this does not change when the [redemptions](/docs/api/coupons?#coupon_redemptions) attribute is changed. This attribute will be present only if the resource has been updated after 2016-11-09.


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


Coupons

A [Credit Note](https://www.chargebee.com/docs/credit-notes.html) is a document that specifies the money owed by a business to its customer. The seller usually issues a Credit Note for the same or lower amount than the invoice, and then repays the money to the customer or set it off against other 'due' invoices.

Chargebee supports two types of Credit Notes - [Adjustment Credit Note](https://www.chargebee.com/docs/credit-notes.html#adjustment-credit-note) and [Refundable Credit Note](https://www.chargebee.com/docs/credit-notes.html#refundable-credit-note).

* Adjustment Credit Notes are created for the 'unpaid' component of the invoice and it can have [statuses](https://www.chargebee.com/docs/credit-notes.html#statuses-of-a-credit-note) - *Adjusted* and *Voided*.
* Refundable Credit Notes are created for 'paid' component of the invoice and it can have [statuses](https://www.chargebee.com/docs/credit-notes.html#statuses-of-a-credit-note) - *Refunded* , *Refund Due* and *Voided*.



The credits available in the Refundable Credit Notes will be automatically applied when a new invoice gets generated for the customer.

**Note:** If you have enabled *consolidated invoicing* , to know the subscriptions attached with a credit note you have to refer [line_item's](/docs/api/credit_notes#credit_note_line_items) *subscription_id* . The credit note's *subscription_id* should **not** be used (which will be *null* if the credit note has lines from multiple subscriptions).


Invoice allocations made from this Credit Note.


Closing date of the invoice. Typically this is the date on which invoice is generated


Current status of the invoice. \* not_paid - Indicates the payment is not made and all attempts to collect is failed. \* paid - Indicates a paid invoice. \* voided - Indicates a voided invoice. \* posted - Indicates the payment is not yet collected and will be in this state till the due date to indicate the due period \* pending -  
The [invoice](/docs/api/invoices?prod_cat_ver=2#invoice_status) is yet to be closed (sent for payment collection). An invoice is generated with this `status` when it has line items that belong to items that are `metered` or when the `subscription.create_pending_invoices`attribute is set to `true`.  
The [invoice](/docs/api/invoices?prod_cat_ver=1#invoice_status) is yet to be closed (sent for payment collection). All invoices are generated with this `status` when [Metered Billing](https://www.chargebee.com/docs/1.0/metered_billing.html) is enabled for the site. \* payment_due - Indicates the payment is not yet collected and is being retried as per retry settings.


The yet to be used credits of this Credit Note.


The refunds issued from this Credit Note.


The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html).   

**Note** : If you enter an invalid country code, the system will return an error.  

**Brexit**


If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom -- Northern Ireland**) is available as an option.


The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search) without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set `state_code` as `AZ` (not `US-AZ`). For Tamil Nadu (India), set as `TN` (not `IN-TN`). For British Columbia (Canada), set as `BC` (not `CA-BC`).


The address verification status. \* valid - Address was validated successfully. \* partially_valid - The address is valid for taxability but has not been validated for shipping. \* invalid - Address is invalid. \* not_validated - Address is not yet validated.


Zip or postal code. The number of characters is validated according to the rules [specified here](https://i18napis.appspot.com/address).


The unique ID of the [business entity](/docs/api/advanced-features?prod_cat_ver=2#mbe) of this credit_note. This is always the same as the business entity of the invoice referred to by [reference_invoice_id](/docs/api/credit_notes?prod_cat_ver=2#credit_note_reference_invoice_id).


The subscription channel this object originated from and is maintained in. \* play_store - The object data is synchronized with data from [in-app subscription(s)](https://apidocs.chargebee.com/docs/api/in_app_subscriptions) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.  

In-App Subscriptions is currently in early access. Contact [eap@chargebee.com](mailto:eap@chargebee.com) for more information.
\* web - The object was created (and is maintained) for the web channel directly in Chargebee via API or UI. \* app_store - The object data is synchronized with data from [in-app subscription(s)](https://apidocs.chargebee.com/docs/api/in_app_subscriptions) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.


Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in **Settings \> Configure Chargebee \> Reason Codes \> Credit Notes \> Create Credit Note**. Must be passed if set as mandatory in the app. The codes are case-sensitive


The currency code (ISO 4217 format) for the credit note


The identifier of the customer this Credit Note belongs to.


Indicates that this resource has been deleted.


The list of discounts applied to this Credit Note


The amount deducted. The format of this value depends on the [kind of currency](/docs/api?prod_cat_ver=2#currencies).


The [coupon code](/docs/api/coupon_codes#coupon_code_code), if applicable, used to provide the discount. The [coupon.id](/docs/api/coupons#coupon_id) is available in `entity_id`.


The type of discount that is applied to the line item. Relevant only when `discounts[entity_type]` is one of `item_level_discount` , `item_level_coupon`, `document_level_discount`, or `document_level_coupon` \* percentage - when percentage is applied as discount \* fixed_amount - when amount is applied as discount


When the deduction is due to a `coupon` or a [discount](discounts), then this is the `id` of the coupon or discount.


The type of deduction and the amount to which it is applied. \* prorated_credits - The deduction is due to a legacy adjustment credit applied to the invoice. The `entity_id` is `null` in this case. The legacy credits feature is superseded by [adjustment_credit_notes](/docs/api/invoices?prod_cat_ver=2#invoice_adjustment_credit_notes). \* item_level_coupon - The deduction is due to a coupon applied to line item. The coupon `id` is passed as `entity_id`. \* item_level_discount - The deduction is due to a [discount](/docs/api/discounts?prod_cat_ver=2) applied to a line item of the invoice. The discount `id` is available as the `entity_id`. \* document_level_coupon - The deduction is due to a coupon applied to the invoice `sub_total`. The coupon id is passed as `entity_id`. \* promotional_credits - The deduction is due to a [promotional credit](/docs/api/promotional_credits?prod_cat_ver=2) applied to the invoice. \* document_level_discount - The deduction is due to a [discount](/docs/api/discounts?prod_cat_ver=2) applied to the invoice `sub_total`. The discount `id` is available as the `entity_id`.


The unique id of the line item that this deduction is for. Is required when `discounts[entity_type]` is `item_level_coupon` or `document_level_coupon`.


An e-invoice or electronic invoice is a structured representation of an invoice that is interoperable between computerized invoicing systems. Depending on the country, e-invoicing can be necessary to meet financial/taxation authority regulations.


The unique `id` for the e-invoice. This is auto-generated by Chargebee.


Detailed information about the status of the e-invoice. When `status` is `skipped` or `failed`, this contains the reason or error details. The following are some valid examples:

* Invoice successfully sent to customer via the e-invoicing network 9090:123456
* Invoice successfully sent to customer via email id abc@acme.com


This attribute is used to populate the unique reference number assigned to an invoice on the Invoice Registration Portal (IRP) network. It is essential for identifying and tracking invoices that are processed through the IRP network. In the future, this field may be used to store similar reference numbers for other networks.


The status of processing the e-invoice. To obtain detailed information about the current `status`, see `message`. \* scheduled - Sending the e-invoice to the customer has been scheduled. \* skipped - The e-invoice was not sent. This could be due to missing information or because the `entity_identifier` is not registered on the e-invoicing network. \* success - The e-invoice has been successfully delivered to the customer. \* failed - The e-invoice was sent and there was an error due to which it was not delivered. \* in_progress - The e-invoice has been sent and Chargebee is waiting for confirmation from the receiving entity. \* registered - The e-invoice was sent and there was an error due to which it was not delivered but got cleared in the IRP.


Indicates the fractional correction amount.


The date/time when the credit note was raised. This date/time can be backdated, which means that the date/time can be earlier than the date/time the credit note was created.


The list of discount(s) applied for each line item of this invoice.


The amount deducted. The format of this value depends on the [kind of currency](/docs/api#currencies).


The type of deduction and the amount to which it is applied. \* prorated_credits - The deduction is due to a legacy adjustment credit applied to the invoice. The `entity_id` is `null` in this case. The legacy credits feature is superseded by [adjustment_credit_notes](/docs/api/invoices?prod_cat_ver=2#invoice_adjustment_credit_notes). \* document_level_coupon - The deduction is due to a coupon applied to the invoice `sub_total`. The coupon `id` is available as `entity_id`. \* promotional_credits - The deduction is due to a [promotional credit](/docs/api/promotional_credits) applied to the invoice. The `entity_id` is `null` in this case. \* item_level_coupon - The deduction is due to a coupon applied to a line item of the invoice. The coupon `id` is available as `entity_id`. \* document_level_discount - The deduction is due to a [discount](/docs/api/discounts?prod_cat_ver=2) applied to the invoice `sub_total`. The discount `id` is available as the `entity_id`. \* item_level_discount - The deduction is due to a [discount](/docs/api/discounts?prod_cat_ver=2) applied to a line item of the invoice. The discount `id` is available as the `entity_id`.


The unique id of the line item that this deduction is for.


Indicates the service period start of the tax rate for the line item.


Indicates the service period end of the tax rate for the line item.


Indicates the non-compliance tax that should not be reported to the jurisdiction.


Indicates if tax is applied only on a portion of the line item amount.


The unique reference id of the line item for which the tax is applicable


The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.


Indicates the prorated line item amount in cents.


Total tax amount in the currency of the place of supply. This is applicable only for Invoice and Credit Notes API.


The type of tax jurisdiction \* federal - The tax jurisdiction is a federal \* state - The tax jurisdiction is a state \* county - The tax jurisdiction is a county \* country - The tax jurisdiction is a country \* city - The tax jurisdiction is a city \* special - Special tax jurisdiction. \* unincorporated - Combined tax of state and county. \* other - Jurisdictions other than the ones listed above.


The rate of tax used to calculate tax amount


Indicates the actual portion of the line item amount that is taxable.


The list of tiers applicable for this line item


The upper limit of a range of units for the tier


The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the `starting_unit_in_decimal` of the next higher tier. Returned only when the `line_items.pricing_model` is `tiered`, `volume` or stairstep and [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


The number of units purchased in a range.


The decimal representation of the quantity purchased from this tier. Returned when the `line_item` is quantity-based and [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


The lower limit of a range of units for the tier


The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as `ending_unit_in_decimal` of the next lower tier. Returned only when the `line_items.pricing_model` is `tiered`, `volume` or `stairstep` and [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


The price of the tier if the charge model is a `stairtstep` pricing , or the price of each unit in the tier if the charge model is `tiered`/`volume` pricing.


The decimal representation of the per-unit price for the tier when the `pricing_model` is `tiered` or `volume`. When the `pricing_model` is `stairstep`, it is the decimal representation of the total price for `line_item`. The value is in major units of the currency. Returned when the `line_item` is quantity-based and [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


Total amount of this line item. Typically equals to unit amount x quantity


The decimal representation of the amount for the `line_item`, in major units of the currency. Typically equals to `unit_amount_in_decimal` x `quantity_in_decimal`. Returned when [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


A unique identifier for the customer this line item belongs to


Detailed description about this line item.


The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type


Specifies the modelled entity this line item is based on. \* addon - Indicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the [addon](/docs/api/addons#addon_attributes) id \* plan - Indicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the [plan](/docs/api/plans#plan_attributes) id \* plan_item_price - Indicates that this line item is based on plan Item Price \* addon_item_price - Indicates that this line item is based on addon Item Price \* charge_item_price - Indicates that this line item is based on charge Item Price \* adhoc - Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case \* plan_setup - Indicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the [plan](/docs/api/plans#plan_attributes) id


Specifies whether this line item is taxed or not


Line Item-level discounts for this line.


The [pricing scheme](https://www.chargebee.com/docs/2.0/plans.html#pricing-models) for this item price. \* stairstep - A quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in. \* flat_fee - A fixed price that is not quantity-based. \* tiered - The per unit price is based on the tier that the total quantity falls in. \* per_unit - A fixed price per unit quantity. \* volume - There are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.


[Quantity of the recurring item](/docs/api/invoices?prod_cat_ver=2#invoice_line_items_quantity) which is represented by this line item. For `metered` line items, this value is updated from [usages](/docs/api/usages) once when the invoice is generated as `pending` and finally when the invoice is [closed](/docs/api/invoices#close_a_pending_invoice).


The decimal representation of the quantity of this line_item. Returned when the `line_item` is quantity-based and [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


A unique identifier for the subscription this line item belongs to.


The reason due to which the line item price/amount is exempted from tax. \* zero_value_item - If the total invoice value/amount is equal to zero. E.g., If the total order value is $10 and a $10 coupon has been applied against that order, the total order value becomes $0. Hence the invoice value also becomes $0. \* reverse_charge - If the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU only \* tax_not_configured - If tax is not enabled for the site \* high_value_physical_goods - If physical goods are sold from outside Australia to customers in Australia, and the price of all the physical good line items is greater than AUD 1000, then tax will not be applied \* customer_exempt - If the Customer is marked as Tax exempt \* region_non_taxable - If the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdiction \* product_exempt - If the Plan or Addon is marked as Tax exempt \* zero_rated - If the rate of tax is 0% and no Sales/ GST tax is collectable for that line item \* export - You are not registered for tax in the customer's region. This is also the reason code when both `billing_address` and `shipping_address` have not been provided for the customer and subscription respectively


Rate of tax used to calculate tax for this lineitem


The decimal representation of the unit amount of the `line_item`. The value is in major units of the currency. Returned when the `line_item` is quantity-based and [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units ) is enabled.


Payment Refunds issued from this Credit Note


The transaction amount applied to this invoice


Time when the transaction amount applied to this invoice.


Reason code for the refund. Must be one from a list of reason codes set in the Chargebee app in **Settings \> Configure Chargebee \> Reason Codes \> Credit Notes \> Refund Credit Note**. Must be passed if set as mandatory in the app. The codes are case-sensitive


Indicates when this transaction occurred.


The status of this transaction. \* needs_attention - Connection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually \* voided - The transaction got voided or authorization expired at gateway. \* timeout - Transaction failed because of Gateway not accepting the connection. \* success - The transaction is successful. \* failure - Transaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure \* in_progress - Transaction is being processed by the gateway. This typically happens for [direct debit transactions](https://www.chargebee.com/docs/direct-debit-payments.html) or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.


The details of refunds recorded against the [invoice.linked_taxes_withheld](/docs/api/invoices#invoice_linked_taxes_withheld) component of the `invoice` [associated](/docs/api/credit_notes#credit_note_reference_invoice_id) with this `credit_note`.


The amount withheld by the customer as tax from the invoice. The unit depends on the [type of currency](/docs/api#md_disabled).


Date or time associated with the tax withheld.


An auto-generated unique identifier for the tax withheld. The value starts with the prefix `tax_wh_`. For example, `tax_wh_16BdDXSlbu4uV1Ee6`.


A unique external reference number for the tax withheld. Typically, this is the reference number used by the system you are integrating the API with. Depending on your integration, this could be the reference number issued by the taxation authority to identify the customer or the specific tax transaction.


The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.


This parameter represents the exchange rate as a relative price of the base currency that appears as local currency in invoices and credit notes. The local currency exchange rate specifically refers to the exchange rate of a country's currency when converting it to another currency. For example, if you want to convert US dollars to euros, the local currency exchange rate would be the rate at which you can convert US dollars to euros.


The price type of the Credit Note. \* tax_inclusive - All amounts in the document are inclusive of tax. \* tax_exclusive - All amounts in the document are exclusive of tax.


The reason for issuing this Credit Note. The following reason codes are supported now\[Deprecated; use the [create_reason_code](/docs/api/credit_notes#credit_note_create_reason_code) parameter instead\] \* subscription_change - This reason will be set automatically for Credit Notes created during Change Subscription operation when [proration](https://www.chargebee.com/docs/proration.html) is enabled \* order_change - Order Change \* other - Can be set when none of the above reason codes are applicable \* fraudulent - FRAUDULENT \* chargeback - Can be set when you are recording your customer Chargebacks \* subscription_pause - This reason will be automatically set to credit notes created during pause/resume subscription operation. \* waiver - Waiver \* subscription_cancellation - This reason will be set automatically for Credit Notes created during cancel subscription operation \* product_unsatisfactory - Product Unsatisfactory \* order_cancellation - Order Cancellation \* write_off - This reason will be set automatically for the Credit Notes created during invoice [Write Off](https://www.chargebee.com/docs/invoice-operations.html#write-off) operation. \* service_unsatisfactory - Service Unsatisfactory


The identifier of the invoice against which this Credit Note is issued


The time this Credit Note gets fully used. Please note that this field is not present when partial refunds are issued.


Version number of this resource. The `resource_version` is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.


Indicates the rounded-off amount. For example, if your invoice amount is $99.99, and the amount is rounded off to $100.00, in this case, $100.00 is your invoice amount, $0.01 is the `round_off_amount`. If there is no `round-off amount`, it will display `0`.


The index number of the subscription/one-time group to which the item price is added. Provide a unique number between `0` and `9` (inclusive) for each group that is to be created. To increase this limit, contact Chargebee Support


The address verification status. \* not_validated - Address is not yet validated. \* valid - Address was validated successfully. \* partially_valid - The address is valid for taxability but has not been validated for shipping. \* invalid - Address is invalid.


The credit note status. \* voided - When the Credit Note has been cancelled. \* refund_due - When the credits are yet to be used, or have been partially used. \* refunded - When the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded). \* adjusted - When the Credit Note has been adjusted against an invoice.


Invoice subtotal in the currency of the place of supply.


The identifier of the subscription this Credit Note belongs to.   
**Note:** If *consolidated invoicing* is enabled, to know the subscriptions attached with this Credit Note you have to refer [line_item's](/docs/api/credit_notes#credit_note_line_items) *subscription_id* . This attribute should **not** be used (which will be *null* if this credit note has lines from multiple subscriptions).


Specifies the customer's category for the Goods and Services Tax (GST). This field is returned only if you've configured GST for the India region.


Total invoice amount in the currency of the place of supply.


The credit note type. \* refundable - Refundable Credit Note \* adjustment - Adjustment Credit Note


Timestamp indicating when this Credit Note was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.


VAT number of the customer for whom this Credit Note is raised.


An overridden value for the first two characters of the [full VAT
number](https://en.wikipedia.org/wiki/VAT_identification_number). Only applicable specifically for customers with [billing_address](customers#customer_billing_address) `country` as `XI` (which is **United Kingdom - Northern Ireland** ).  

When you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or have [manually
enabled](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, you have the option of setting [billing_address](customers#customer_billing_address) `country` as `XI`. That's the code for **United Kingdom - Northern
Ireland** . The first two characters of the VAT number in such a case is `XI` by default. However, if the VAT number was registered in UK, the value should be `GB`. Set `vat_number_prefix` to `GB` for such cases.


Timestamp indicating the date and time this Credit Note gets voided.


Credit Notes

This attribute represents the identifier of the most recent version of the customers resource. When interacting with our API, the active_id ensures you're always referencing the current and most up-to-date version of the customers resource.

Whether the customer can pay via Direct Debit

Override for this customer, the site-level setting for auto-closing invoices. Only applicable when auto-closing invoices has been enabled for the site. This attribute is also available at the subscription level which takes precedence.

When the customer has a payment_method of type card, this attribute determines whether to automatically charge the card whenever an invoice status is payment_due.

The identifier of the customer's backup payment source.

Country of the billing contact. Must be one of ISO 3166 alpha-2 country code.

Email of the billing contact. Configured email notifications will be sent to this email.

The validation status of the billing address. This attribute is applicable only if you have configured EU, UK or Australian taxes and the address validation is enabled.

Applicable only when Calendar Billing with support for customer-specific billing date is enabled and billing_date_mode is manually_set.

Applicable when calendar billing (with customer specific billing date support) is enabled. When set, renewals of all the weekly subscriptions of this customer will be aligned to this week day.

Indicates whether this customer's billing_day_of_week value is derived as per configurations or its specifically set (overriden).

Confirms that a customer is a valid business without an EU/UK VAT number.

The unique ID of the business entity of this subscription. This is always the same as the business entity of the customer.

The subscription channel this object originated from and is maintained in.

When the customer is part of an account hierarchy, this attribute defines the level of access that the customer has to its own information.

The Avalara client profile ID assigned to the customer.

Indicates whether invoices raised on the same day for the customer are consolidated. When present, this value overrides the default configuration at the site-level. This attribute is applicable only when Consolidated Invoicing is enabled.

Timestamp indicating when this customer resource is created.

The IP address of the customer when this customer record was created. It’s mainly used for referral integrations and validating VAT if the customer is in the EU or UK.

Indicates that this resource has been deleted.

Determines whether to send e-invoice manually or automatic.

Email of the customer. Configured email notifications will be sent to this email.

The exemption category of the customer, for USA and Canada. Applicable if you use Chargebee's AvaTax for Sales integration.

The Peppol BIS scheme associated with the vat_number of the customer. This helps identify the specific type of customer entity. For example, DE:VAT is used for a German business entity while DE:LWID45 is used for a German government entity. The value must be from the list of possible values and must correspond to the country provided under billing_address.country. See list of possible values.

The standard used for specifying the entity_identifier_scheme. Currently only iso6523-actorid-upis is supported and is used by default when not provided.

Each element of the entity_identifiers[] array identifies a specific customer entity with the e-invoicing system. If the customer has only one entity identifier whose value is the vat_number, then this array is not needed as the scheme can be provided via entity_identifier_scheme. This array holds any additional entity identifiers that the customer may have.

Total unused payments associated with the customer

Any string value that will cause the sale to be exempted. Use this if your finance team manually verifies and tracks exemption certificates. Applicable if you use Chargebee's AvaTax for Sales integration.

Indicates the exemption information. You can customize customer exemption based on specific Location, Tax level (Federal, State, County and Local), Category of Tax or specific Tax Name. This is applicable only if you use Chargebee’s AvaTax for Communications integration.

Indicates whether or not the customer has been identified as fraudulent.

A note for the customer that appears on all their invoice PDFs. This is one of several notes displayed on the invoice PDF.

Determines whether the customer is e-invoiced. When set to true or not set to any value, the customer is e-invoiced so long as e-invoicing is enabled for their country (billing_address.country). When set to false, the customer is not e-invoiced even if e-invoicing is enabled for their country.

Applicable only when the customer’s billing_address.country is New Zealand, Australia, or in the EU.

The number of days within which the customer has to make payment for the invoice.

When the customer is part of an account hierarchy, this attribute defines the level of access that the parent account has to the customer's information.

The reference ID of the payment method. This is used to identify the payment method in the gateway.

Indicates whether this customer's personal information has been cleared

Specifies the customer's preferred currency in ISO 4217 format.

The identifier of the customer's primary payment source

The balance of promotional credits available to the customer.

List of referral urls for the customer (if applicable)

Refundable credits balance of this customer

Confirms that a customer is registered under GST. If set to true then the Reverse Charge Mechanism is applicable. This field is applicable only when Australian GST is configured for your site.

The account hierarchy relationship that the customer is part of.

Version number of this resource. The resource_version is updated with a new timestamp in milliseconds for every change made to the resource. This attribute will be present only if the resource has been updated after 2016-09-28.

Specifies if the customer is liable for tax

Timestamp indicating when this customer was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.

Indicates whether the site-default settings are being used for controlling access to the customer’s information.

The VAT/tax registration number for the customer. For customers with billing_address country as XI (which is United Kingdom - Northern Ireland), the first two characters of the full VAT number can be overridden by setting vat_number_prefix.

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

Represents the VAT validation status. This is applicable if you have configured EU, UK or Australian taxes and the VAT number validation is enabled.

Returns the recent VAT number validation time.

Customers

The entitlement resource establishes a connection between a [feature](features?prod_cat_ver=2) and an [item](items?prod_cat_ver=2) or an [item_price](item_prices?prod_cat_ver=2) in Chargebee Billing. By defining this relationship, it specifies the scope of access or rights the item or item price has in relation to that particular feature.


The unique identifier of the entity being granted entitlement to a specific `feature`.


The type of the entity that holds this entitlement. \* plan -

Indicates that the entity is an `item` with [type](items?prod_cat_ver=2#item_type) set to `plan`.
\* addon -

Indicates that the entity is an `item` with [type](items?prod_cat_ver=2#item_type) set to `addon`.
\* addon_price -

Indicates that the entity is an `item_price` associated with an `item` with [type](items?prod_cat_ver=2#item_type) set to `addon`.
\* charge -

Indicates that the entity is an `item` with [type](items?prod_cat_ver=2#item_type) set to `charge`.
\* plan_price -

Indicates that the entity is an `item_price` associated with an `item` of [type](items?prod_cat_ver=2#item_type) `plan`.


The unique identifier of the `feature` to which the entity gains entitlement.


The `name` of the feature associated with this entitlement.


A unique identifier for the entitlement. This is auto-generated.


The display name for the entitlement level. The value is automatically generated based on `feature.type`:

* When `feature.type` is `quantity` or `range`, the `name` is the space-separated concatenation of `value` and the plural form of `feature.unit`. For instance, if `value` is `20` and `feature.unit` is `user`, the `name` will be `20 users`.
* When `feature.type` is `custom`, the `name` matches the `value`.


The level of entitlement that the entity has towards the feature. The possible values depend on the value of `feature.type`:

* When `feature.type` is `quantity` and:
  * If `feature.levels[is_unlimited]` is not `true` for any one of `feature.levels[]`, then the value can be any one of `feature.levels[value][]`.
  * If `feature.levels[is_unlimited]` is `true` for one of the `feature.levels[]`, then the value can be:
    * any one of `feature.levels[value][]`
    * or it can be `unlimited` (case-insensitive), indicating unlimited entitlement.
* When `type` is `range` and:
  * If `feature.levels[is_unlimited]` is not `true` for any one of `feature.levels[]`, then the value can be any whole number between `levels[value][0]` and `levels[value][1]` (inclusive).
  * If `feature.levels[is_unlimited]` is `true` for one of the `feature.levels[]`, then the value can be:
    * any whole number equal to or greater than `levels[value][0]`
    * or it can be `unlimited` (case-insensitive), indicating unlimited entitlement.
* When `type` is `custom`, then the value can be any one of `feature.levels[value][]`.
* When `type` is `switch`, then the value is set as `available` or `true`.


Entitlements

Subscriptions are created in Chargebee using items. Items represent the products or services that you offer to your customers. Items often differ in the number of product features that are available to them. The Features API helps you define the various features offered as part of your product line. It also defines the entitlements that items and subscriptions can have towards said features.  
**Note**

The maximum number of features a site can have is 400.

Features of this API {#features}
--------------------------------

The Features API enables you to:

* Define the set of features provided by your product.
* Specify the entitlements that items have towards said features.
* For a given subscription, modify the entitlements inherited from items in the subscription.
* Offer additional feature entitlements to subscriptions than those inherited from items in the subscription.
* Serve as a source of truth to your provisioning systems for subscription entitlements.
* Use entitlement information to understand which features drive value and revenue.



**See also**

* [Entitlements](/docs/api/entitlements)
* [Subscription Entitlements](/docs/api/subscription_entitlements)
* [Entitlement Overrides](/docs/api/entitlement_overrides)


	List	Find by ID	Match	Create	Update	Delete
_objects	✅	✅	✅	✅	✅	➖
Coupons	✅	✅	✅	✅	✅	➖
Credit Notes	✅	✅	✅	✅	✅	➖
Customers	✅	✅	✅	✅	✅	➖
Features	✅	✅	✅	✅	✅	➖
Invoices	✅	✅	✅	✅	✅	➖

	Products automatically maps to	Invoices automatically maps to	Orders automatically maps to	Payments automatically maps to	Customers automatically maps to
Xero	Items	Invoices	Purchase Orders	Payments	Contacts
Quickbooks	—	Invoices	Purchaseorders	Payments	Customers
Stripe	Products	—	—	Charges	Customers
Sage Accounting	Products	Purchase Invoices	—	Contact Payments	—
Woocommerce	Products	—	Orders	—	Customers
Zoho Books	Items	Invoices	—	Vendor Payments	—
Freshbooks	—	Invoices	—	Payments	Clients
Exact Online	—	Purchase Invoices	Purchase Orders	—	—
Shopify	Products	—	Orders	—	—
Salesforce	Products	—	Orders	—	—

Chargebee integration connector

Managed authentication

Work with Chargebee data collections

Trigger integrations on Chargebee events

Data Record Created

Data Record Updated

Data Record Deleted

Use the same code to integrate with Chargebee and 100+ other applications

Products

Invoices

Orders

Payments

Customers

Try our AI-powered integration development environment for free

Chargebee integration connector

Managed authentication

Work with Chargebee data collectionsself.__wrap_n!=1&&self.__wrap_b(":Rb556:",1)

Trigger integrations on Chargebee eventsself.__wrap_n!=1&&self.__wrap_b(":Rbd56:",1)

Data Record Created

Data Record Updated

Data Record Deleted

Use the same code to integrate with Chargebee and 100+ other applicationsself.__wrap_n!=1&&self.__wrap_b(":Rbl56:",1)

Products

Invoices

Orders

Payments

Customers

Try our AI-powered integration development environment for free

Work with Chargebee data collections

Trigger integrations on Chargebee events

Use the same code to integrate with Chargebee and 100+ other applications