# 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": [
    {
      "id": "li___dev__XpbJ77CVDP7eWz3a",
      "customer_id": "_cb_test_demo_",
      "subscription_id": "__dev__XpbJ77CVDP3zQI38",
      "date_from": 1773088261,
      "date_to": 1773088261,
      "unit_amount": 50000,
      "pricing_model": "flat_fee",
      "quantity": 1,
      "amount": 50000,
      "discount_amount": 0,
      "description": "One-Time Setup Fee",
      "entity_id": "cbdemo_one-time-setup-fee",
      "is_voided": false,
      "created_at": 1773088262,
      "updated_at": 1773088262,
      "deleted": false,
      "object": "unbilled_charge",
      "entity_type": "charge_item_price",
      "currency_code": "USD"
    },
    {..}
  ]
}
```

## 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:
    - `adhoc`
      Indicates that this lineitem is not modelled. i.e created adhoc. So the 'entity\_id' attribute will be null in this case
    - `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

- `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 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/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/currencies) is enabled.

- `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/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 unique ID of the [business entity](/docs/api/advanced-features) of this unbilled charge. This is always the same as the [business entity](/docs/api/unbilled_charges/unbilled_charge-object#customer_id) of the customer.

- `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/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/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/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/currencies) is enabled.
  - `pricing_type` (optional, enumerated string)
    Pricing type for the tier.
    Possible enum values:
      - `per_unit`
        Indicates that the tier pricing is based on individual units. Customers are charged a fixed price per unit. For example, if the price per unit is $2 and the customer consumes 150 units, they will be charged $300 (150 × $2).
      - `flat_fee`
        Indicates that the tier pricing is a flat fee, applied to the entire tier regardless of the number of units consumed. For the **stairstep** pricing model, `pricing_type` will be set to `flat_fee` by default. For example, if the flat fee for a tier is $100, the customer pays $100 whether they consume 1 unit or the maximum number of units within that tier.
      - `package`
        Indicates that the tier pricing is based on a package of units. Customers are charged for each block or package of units. For example, if the package size is 100 units and the cost per block is $20 consuming 400 units will result in a charge of $80 (4 × $20).
  - `package_size` (optional, integer, min=1)
    Package size for the tier when pricing type is `package`. Specify the number of units that make up one package. For example, if 1000 API hits are grouped into a single package, set the package size to 1000.