# Unbilled charges

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


Unbilled charge represents the charges that are held by passing `invoice_immediately` in various operations such as update subscription, add charge, create subscription, etc. [Learn more.](https://www.chargebee.com/docs/unbilled-charges.html)

If any invoice is to be created for a subscription all the unbilled charges associated with the subscription will be included in that invoice.

If any invoice is to be created for a customer, all the unbilled charges associated with its subscriptions will be included in that invoice.

Any automatic invoice creation like renewal, activation, etc., will include the unbilled charges.

Subscriptions are invoiced at the start of every term based on the recurring items and charged immediately against the customer's credit card if 'auto\_collection' is turned 'on', otherwise the resulting invoice will be created as 'Payment Due'.

If consolidated invoicing is enabled, the charges during the subscription renewals/activations will be held and consolidated at the last renewal/activation that takes place on that particular day.

## Sample Unbilled charge

```json
{
  "unbilled_charges": [
    {
      "amount": 200,
      "currency_code": "USD",
      "customer_id": "__test__8asyaSyvdsRW9",
      "date_from": 1517490343,
      "date_to": 1517490343,
      "deleted": false,
      "description": "non_recurring_addon",
      "discount_amount": 0,
      "entity_id": "non_recurring_addon",
      "entity_type": "addon",
      "id": "li___test__8asyaSyvdyLvK",
      "is_voided": false,
      "object": "unbilled_charge",
      "pricing_model": "per_unit",
      "quantity": 2,
      "subscription_id": "__test__8asyaSyvdtlIC",
      "unit_amount": 100
    },
    {..}
  ]
}
```

## Unbilled charges attributes

## Input Parameters

- `id` (optional, string, max chars=40)
  Uniquely identifies an unbilled charge.

- `customer_id` (optional, string, max chars=50)
  A unique identifier for the customer being charged.

- `subscription_id` (optional, string, max chars=50)
  A unique identifier for the subscription this charge belongs to.

- `date_from` (optional, timestamp(UTC) in seconds)
  Start date of this charge.

- `date_to` (optional, timestamp(UTC) in seconds)
  End date of this charge.

- `unit_amount` (optional, in cents, min=0)
  Unit amount of the charge item.

- `pricing_model` (optional, enumerated string)
  The pricing scheme for this line item.
  Possible enum values:
    - `flat_fee`
      A fixed price that is not quantity-based.
    - `per_unit`
      A fixed price per unit quantity.
    - `tiered`
      There are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.
    - `volume`
      The per unit price is based on the tier that the total quantity falls in.
    - `stairstep`
      A quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.

- `quantity` (optional, integer, min=0)
  Quantity of the item which is represented by this charge.

- `amount` (optional, in cents, min=0)
  Total amount of this charge. Typically equals to unit amount x quantity.

- `currency_code` (required, string, max chars=3)
  The currency code (ISO 4217 format) for the charge.

- `discount_amount` (optional, in cents, min=0)
  Total discounts for this charge.

- `description` (optional, string, max chars=250)
  Detailed description about this charge.

- `entity_type` (required, enumerated string)
  Specifies the modelled entity this line item is based on.
  Possible enum values:
    - `plan_setup`
      Indicates that this lineitem is based on 'Plan Setup' charge. The 'entity\_id' attribute specifies the [plan](/docs/api/v2/pcv-1/plans/plan-object) id
    - `plan`
      Indicates that this lineitem is based on 'Plan' entity. The 'entity\_id' attribute specifies the [plan](/docs/api/v2/pcv-1/plans/plan-object) id
    - `addon`
      Indicates that this lineitem is based on 'Addon' entity. The 'entity\_id' attribute specifies the [addon](/docs/api/v2/pcv-1/addons/addon-object) id
    - `adhoc`
      Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity\_id' attribute will be null in this case

- `entity_id` (optional, string, max chars=100)
  The identifier of the modelled entity this charge is based on. Will be null for 'adhoc' entity type.

- `is_voided` (required, boolean, default=false)
  Will be true if the charge has been voided. Usually the unbilled charge will be voided and revised to different charges(s) during proration.

- `voided_at` (optional, timestamp(UTC) in seconds)
  Timestamp indicating the date and time this charge got voided.

- `unit_amount_in_decimal` (optional, string, max chars=39)
  The decimal representation of the amount for the charge, in major units of the currency. Typically equals to `unit_amount_in_decimal` x `quantity_in_decimal`. Returned when [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.

- `quantity_in_decimal` (optional, string, max chars=33)
  The decimal representation of the quantity of this entity. Returned when the entity is quantity-based and [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.

- `amount_in_decimal` (optional, string, max chars=39)
  The decimal representation of the unit amount for the entity. The value is in major units of the currency. Returned when the entity is quantity-based and [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.

- `created_at` (optional, timestamp(UTC) in seconds)
  Timestamp indicating when the unbilled charge was created.

- `updated_at` (required, timestamp(UTC) in seconds)
  Timestamp indicating when the unbilled charge was last updated

- `is_advance_charge` (optional, boolean, default=false)
  The value of this parameter will be true if it is a recurring unbilled charge for a future term.

- `business_entity_id` (optional, string, max chars=50)
  The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.
  
  **Note**
  
  [Multiple Business Entities](/docs/api/getting-started) is a feature available only on Product Catalog 2.0.

- `deleted` (required, boolean)
  Indicates that this resource has been deleted.

- `tiers` (optional, list of line_item_tier)
  The list of tiers applicable for this line item
  - `starting_unit` (required, integer, min=0)
    The lower limit of a range of units for the tier
  - `ending_unit` (optional, integer)
    The upper limit of a range of units for the tier
  - `quantity_used` (required, integer, min=0)
    The number of units purchased in a range.
  - `unit_amount` (required, in cents, min=0)
    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.
  - `starting_unit_in_decimal` (optional, string, max chars=33)
    The decimal representation of 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](/docs/api/v2/pcv-1/currencies) is enabled.
  - `ending_unit_in_decimal` (optional, string, max chars=33)
    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](/docs/api/v2/pcv-1/currencies) is enabled.
  - `quantity_used_in_decimal` (optional, string, max chars=33)
    The decimal representation of the quantity purchased from this tier. Returned when the `line_item` is quantity-based and [multi-decimal pricing](/docs/api/v2/pcv-1/currencies) is enabled.
  - `unit_amount_in_decimal` (optional, string, max chars=40)
    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](/docs/api/v2/pcv-1/currencies) is enabled.