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


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.


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.


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


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 list of tiers applicable for this line item


Payment Refunds issued from this Credit Note


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


A brief description of the feature. For example: `Access to 10TB cloud storage`.


A unique and immutable identifier for the feature. You can set it yourself, in which case it is recommended that a human-readable format (or slug) be used. For example, `number-of-users-ccjht01`. When not provided, a random value is automatically set.


An ordered list of entitlement levels available for the feature. This is only applicable when `type` is other than `switch`.  
**Note:** When the `type` of the feature is `switch`, this is not applicable. This is because any given entity can be either fully entitled to a `switch` feature or not entitled at all; there are no intermediate entitlement levels.


A case-sensitive unique name for the feature. For example: `user license`, `data storage`, `Salesforce Integration`, `devices`, `UHD Streaming`, and so on.   
**Note:** This name is not displayed on any customer-facing documents or pages such as [invoice PDFs](invoices#retrieve_invoice_as_pdf) or [hosted pages](hosted_pages). However, in the future, it is likely to be introduced on the [Self-Serve Portal](portal_sessions).


The current status of the feature. \* active - A `draft` or an `archived` feature can be changed to `active`. Any <entitlements> or [subscription entitlements](subscription_entitlements) defined for the feature take effect immediately. \* draft - The feature is in an unpublished state. [Entitlements](entitlements) and [subscription entitlements](subscription_entitlements) can be created for a draft feature but they are not effective until the feature is active. A feature `status` cannot be changed back to `draft` once it is in `active` or `archived` `status`. \* archived - An `active` feature can be changed to `archived`. Once `archived`, no **new** <entitlements> or [subscription entitlements](subscription_entitlements) can be created for the feature. However, any pre-existing item or subscription entitlements from the time that the feature was `active`, remain effective.


The type of feature. \* quantity - The feature is quantity-based and entitlement levels available for it are a set of predefined number of quantity units. For example, a feature with `name` such as `number of users` can have entitlement levels of say, `5`, `20`, `50`, and `100`. `levels[is_unlimited]` is used for specifying the "unlimited" entitlement level. \* range - The feature is quantity-based and the entitlement levels available for it are the set of whole numbers within a range. The range is defined by a minimum and a maximum value. For example, a feature such as `number of users` can have entitlement levels starting at `5` users and go up to `50000`. `levels[is_unlimited]` is used for specifying the "unlimited" entitlement level. \* switch - A switch or toggle is a feature that an item or subscription can be either fully entitled to or not entitled to at all. \* custom - The entitlement levels available for this feature are defined as a set of custom values. For example, a feature `Email Support` can have entitlement levels as `24×7` and `24×5`.


For features of `type` `quantity` or `range`, this specifies the unit of measure. The value is expected in the singular form and when used by the system, it is pluralized automatically as needed. For example, for a feature such as `user licenses`, the `unit` can be `license`.


Features

Total adjustments made against this invoice

The unpaid amount that is due on the invoice

Payments collected successfully for the invoice

Payments that are yet to be collected for the invoice

The unique ID of the business entity of this invoice. Depending on whether the invoice was created directly for a customer or for a subscription, this is the business entity of the customer or the subscription respectively.

Total credits applied against this invoice

The currency code (ISO 4217 format) for the invoice

The identifier of the customer this invoice belongs to.

The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions.

Indicates that this resource has been deleted

Exchange rate used for base currency conversion

Expected payment date recorded for this invoice

Boolean indicating the first invoice raised for the subscription. In the case of a non-recurring invoice, it indicates the first invoice raised for the customer

The date when the invoice is finalized. This is the date in the invoice lifecycle when its status becomes any one of the following for the first time: payment_due, posted, or paid. For an invoice with status as pending, this happens when it gets closed

Boolean indicating any advance charge is present in this invoice

The invoice number. Acts as a identifier for invoice and typically generated sequentially.

Boolean indicating this invoice is gifted or not

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

Number of days within which the invoice has to be paid

The share of the invoice total due to new sales

Timestamp indicating when will the next attempt to collect payment for this invoice occur

Timestamp indicating the date & time this invoice got paid

Boolean indicating whether this invoice belongs to a subscription

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

The sum of all the line item amounts minus the sum of all line item discounts

Invoice subtotal in the currency of the place of supply

The identifier of the subscription this invoice belongs to

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

Boolean indicating this invoice line_items terms are finalized or not

Total invoice amount in the currency of the place of supply

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

VAT/ Tax registration number of the customer.

Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive

Timestamp indicating the date & time this invoice got voided

Invoices

An item price is a price point for an item. It defines the currency, pricing model, price, billing period and other attributes for an [item](./items?prod_cat_ver=2). For example, consider a cloud storage service as an item. Then each of the following defines an item price:

* The cloud storage sold at USD 10 per month.
* The same service sold at AUD 100 per year.
* The service sold at a monthly rate determined by the following [stairstep](https://www.chargebee.com/docs/2.0/plans.html#pricing-models) pricing model:
  * 1--10 users for EUR 10
  * 11--25 users for EUR 20
  * 26--50 users for EUR 45
  * 51 and above for EUR 100

The **billing period** of an item price (only applies to plan-item prices and addon-item prices), is the `period` of the item price in `period_unit`s. An item can have only one item price for a given currency and billing period.

Types of item prices {#types}
-----------------------------

The type of an item price corresponds to the [type of the item](./items?prod_cat_ver=2) that the item price belongs to. In other words, item prices can be of the following types:

* Plan-item prices
* Addon-item prices
* Charge-item prices


Accounting integration details. The values are typically dependent on the \[accounting integration\](https://www.chargebee.com/docs/finance-integration-index.html) used.


Used exclusively with the following [accounting integrations](https://www.chargebee.com/docs/2.0/finance-integration-index.html )

* [**Xero:**](https://www.chargebee.com/docs/2.0/xero.html )If you've categorized your products in Xero, provide the category name and option. Use the format: `<category-name>: <option>`. For example:`Location: Singapore.`
* [**QuickBooks:**](https://www.chargebee.com/docs/2.0/quickbooks.html )If you've categorized your product sales in QuickBooks according to Classes, provide the class name here. Use the following format: `<parent class>:<sub-class-1>:<sub-class-2>...`
* [**NetSuite:**](https://www.chargebee.com/docs/2.0/netsuite.html )If you've categorized your products in NetSuite under Classes, provide the class name here. Use the following format: `<parent class>: <sub-class-1>: <sub-class2>....` For example: `Services: Plan.`
* [**Intacct:**](https://www.chargebee.com/docs/2.0/intacct.html )If you've classified your products in Intacct under Locations, provide the name of the Location here.



Used exclusively with the following [accounting integrations](https://www.chargebee.com/docs/2.0/finance-integration-index.html )

* [**Xero:**](https://www.chargebee.com/docs/2.0/xero.html )If you've categorized your products in Xero, then provide the second category name and option here. Use the format: `<category-name>: <option>....` For example, `Region: South`
* [**QuickBooks:**](https://www.chargebee.com/docs/2.0/quickbooks.html )If you've categorized your product sales in QuickBooks according to Location, provide the Location name here. Use the following format: `<parent-location>:<sub-location-1>:<sub-location-2>....` For example: `Location: North America: Canada`
* [**NetSuite:**](https://www.chargebee.com/docs/2.0/netsuite.html )If you've categorized your products in NetSuite under Locations, provide the location name here. Use the following format `<parent-location> : <sub-location-1>: <sub-location-2>....` For example: `NA:US:CA`
* [**Intacct:**](https://www.chargebee.com/docs/2.0/intacct.html )If you've classified your products in Intacct under Dimensions, provide the value of the Dimension here.



Used exclusively with the following [accounting integrations](https://www.chargebee.com/docs/2.0/finance-integration-index.html )

* [**NetSuite:**](https://www.chargebee.com/docs/2.0/netsuite.html )If you've categorized your products in NetSuite under Departments, pass the department name here. Use the following format: `<parent-department> : <sub-department-1>: <sub-department-2>....` For example: `Production: Assembly.`
* [**Intacct:**](https://www.chargebee.com/docs/2.0/intacct.html )If you've classified your products in Intacct under multiple Dimensions, provide the value of the second Dimension here.


Used exclusively with the following [accounting integrations](https://www.chargebee.com/docs/1.0/finance-integration-index.html )

* [**NetSuite:**](https://www.chargebee.com/docs/2.0/netsuite.html )Provide the "Revenue Recognition Rule Id" for the product from NetSuite.
* [**Intacct:**](https://www.chargebee.com/docs/2.0/intacct.html )If you have configured "Revenue Recognition Templates" for products in Intacct, provide the template ID for the product.


The identifier of the chart of accounts under which the item price falls in the accounting system.


This maps to the sku or product name in the accounting integration.


Timestamp indicating when this item price was archived.


The default number of billing cycles a subscription to the plan must run. Can be [overridden](./subscriptions?prod_cat_ver=2) for a subscription.

Addons can also [have billing cycles](https://www.chargebee.com/docs/2.0/addons-billingcycle.html). However, you must contact [Support](https://chargebee.freshdesk.com/support/home) to enable that. Also, for addons, you can [override this](./attached_items?prod_cat_ver=2) while attaching it to a plan. However, if you provide the value while [applying the addon to a subscription](./subscriptions?prod_cat_ver=2#subscription_subscription_items_item_type), then that value takes still higher precedence.
If subscriptions, invoices or [differential prices](./differential_prices?prod_cat_ver=2) exist for this item price, `billing_cycles` cannot be changed.


The subscription channel this object originated from and is maintained in. \* 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. \* web - The object was created (and is maintained) for the web channel directly in Chargebee via API or UI. \* 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.


Timestamp indicating when this item price was created


The currency code ([ISO 4217 format](https://www.chargebee.com/docs/2.0/supported-currencies.html)) for the item price. If subscriptions, invoices or [differential prices](./differential_prices?prod_cat_ver=2) exist for this item price, `currency_code` cannot be changed.


Description of the item price.   
**Note:**   
If your input contains characters that are subjected to sanitization (like incomplete HTML tags), the sanitization process might increase the length of your input. If the sanitized input exceeds the limit, your request will be rejected.


The name of the item price used in customer-facing pages and documents. These include [invoices](./invoices?prod_cat_ver=2) and [hosted pages](hosted_pages?prod_cat_ver=2). If not provided, then `name` is used


Free quantity the subscriptions of this item_price will have. Only the quantity more than this will be charged for the subscription.


The quantity of the item that is available free-of-charge, represented in decimal. When a subscription is created for this plan or when the plan of a subscription is changed to this one, only the quantity above this number is charged for. Applicable for quantity-based plans and only when [multi-decimal pricing](https://apidocs.chargebee.com/docs/api#handling_currency_units) is enabled.


The identifier for the item price. It is unique and immutable.


Specifies whether taxes apply to this item price. This value is set and returned even if [Taxes](https://www.chargebee.com/docs/tax.html) have been disabled in Chargebee. However, the value is effective only while Taxes are enabled.


The id of the item that the item price belongs to.


Type of item. \* addon - A recurring component that can be added to a subscription in addition to its plan. \* charge - A non-recurring component that can be added to a subscription in addition to its plan. An charge can also be applied to a customer [directly](./invoices?prod_cat_ver=2#create_invoice_for_a_charge-item) without being applied to a subscription. \* plan - An essential component of a subscription. Every subscription has exactly one plan. It has a recurring charge and its period defines the billing period of the subscription.


A unique display name for the item price in the Chargebee UI. If `external_name` is not provided, this is also used in customer-facing pages and documents such as [invoices](./invoices?prod_cat_ver=2) and [hosted pages](hosted_pages?prod_cat_ver=2).




* When the item `type` is `plan`: The billing period of the plan in `period_unit`s. For example, create a 6 month plan by providing `period` as 6 and `period_unit` as month.
* When item `type` is `addon`: The period of the addon in `period_unit`s. For example, create an addon with a 2 month `period` by providing period as 2 and `period_unit` as `month`. The period of an addon is the duration for which its `price` applies. When attached to a plan, the addon is billed for the billing period of the plan. [Learn more.](https://www.chargebee.com/docs/2.0/addons-billingcycle.html)



If subscriptions or invoices exist for this item price, `period` cannot be changed. The `period` is mandatory when the item `type` is `plan` or `addon`


Chargebee API Integration Profile

Create Invoice

Continuously Import Products to my App

Delete Order

Delete Customer

Update Invoice

Continuously Enrich Customers

Continuously Import Invoices to my App

Get all Customers

Two-way realtime sync of Payments

Two-way realtime sync of Invoices

Build every single integration your customers need with AI