API Version
Product Catalog
Library

Unbilled charge represents the charges that are held by passing invoice_later in various operations such as update subscription, add charge, create subscription, etc. Learn more.

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": 500, "currency_code": "USD", "customer_id": "__test__5SK2lmRmS627Arv5X", "date_from": 1517483456, "date_to": 1517483456, "deleted": false, "description": "SSL Charge USD Monthly", "discount_amount": 0, "entity_id": "ssl-charge-USD", "entity_type": "charge_item_price", "id": "li___test__5SK2lmRmS627B3A5f", "is_voided": false, "object": "unbilled_charge", "pricing_model": "flat_fee", "quantity": 1, "subscription_id": "__test__5SK2lmRmS627AvF5Z", "unit_amount": 500 } ] }

API Index URL GET

https://{site}.chargebee.com/api/v2/unbilled_charges

Model Class

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 values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.
Show all values[+]
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
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
enumerated string
Specifies the modelled entity this line item is based on.
Possible values are
adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this caseplan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
Show all values[+]
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
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 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 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 is enabled.
updated_at
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.
deleted
boolean
Indicates that this resource has been deleted.
optional, list of line_item_tier
The list of tiers applicable for this line item
id id
optional, string, max chars=40
Uniquely identifies an unbilled charge.
customer_id customer_id
optional, string, max chars=50
A unique identifier for the customer being charged.
subscription_id subscription_id
optional, string, max chars=50
A unique identifier for the subscription this charge belongs to.
date_from date_from
optional, timestamp(UTC) in seconds
Start date of this charge.
date_to date_to
optional, timestamp(UTC) in seconds
End date of this charge.
unit_amount unit_amount
optional, in cents, min=0
Unit amount of the charge item.
pricing_model pricing_model
optional, enumerated string
The pricing scheme for this line item.
quantity quantity
optional, integer, min=0
Quantity of the item which is represented by this charge.
amount amount
optional, in cents, min=0
Total amount of this charge. Typically equals to unit amount x quantity.
currency_code currency_code
string, max chars=3
The currency code (ISO 4217 format) for the charge.
discount_amount discount_amount
optional, in cents, min=0
Total discounts for this charge.
description description
optional, string, max chars=250
Detailed description about this charge.
entity_type entity_type
enumerated string
Specifies the modelled entity this line item is based on.
entity_id 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 is_voided
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 voided_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date and time this charge got voided.
unit_amount_in_decimal 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 is enabled.
quantity_in_decimal 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 is enabled.
amount_in_decimal 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 is enabled.
updated_at updated_at
timestamp(UTC) in seconds
Timestamp indicating when the unbilled charge was last updated
is_advance_charge 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.
deleted deleted
boolean
Indicates that this resource has been deleted.
tiers
optional, list of line_item_tier
The list of tiers applicable for this line item
This endpoint creates unbilled charges for a subscription.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/unbilled_charges \
     -u {site_api_key}:\
     -d subscription_id="__test__5SK2lmRmS627AvF5Z" \
     -d item_prices[item_price_id][0]="ssl-charge-USD" 
curl  https://{site}.chargebee.com/api/v2/unbilled_charges \
     -u {site_api_key}:\
     -d subscription_id="__test__5SK2lmRmS627BA25k" \
     -d currency_code="usd" \
     -d charges[amount][1]=100 \
     -d charges[description][1]="Implementation charge" 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "unbilled_charges": [
        {
            "amount": 500,
            "currency_code": "USD",
            "customer_id": "__test__5SK2lmRmS627Arv5X",
            "date_from": 1517483456,
            "date_to": 1517483456,
            "deleted": false,
            "description": "SSL Charge USD Monthly",
            "discount_amount": 0,
            "entity_id": "ssl-charge-USD",
            "entity_type": "charge_item_price",
            "id": "li___test__5SK2lmRmS627B3A5f",
            "is_voided": false,
            "object": "unbilled_charge",
            "pricing_model": "flat_fee",
            "quantity": 1,
            "subscription_id": "__test__5SK2lmRmS627AvF5Z",
            "unit_amount": 500
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges

Method

subscription_id[]
required, string, max chars=50
Identifier of the subscription for which this unbilled charges needs to be created.
currency_code[]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the unbilled_charge.
item_prices[item_price_id][0..n]
optional, string, max chars=100
item_prices[quantity][0..n]
optional, integer, min=1
item_prices[quantity_in_decimal][0..n]
optional, string, max chars=33
item_prices[unit_price][0..n]
optional, in cents, min=0
item_prices[unit_price_in_decimal][0..n]
optional, string, max chars=39
item_prices[date_from][0..n]
optional, timestamp(UTC) in seconds
item_prices[date_to][0..n]
optional, timestamp(UTC) in seconds
item_tiers[item_price_id][0..n]
optional, string, max chars=100
item_tiers[starting_unit][0..n]
optional, integer, min=1
item_tiers[ending_unit][0..n]
optional, integer
item_tiers[price][0..n]
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
optional, string, max chars=39
charges[amount][0..n]
optional, in cents, min=1
charges[amount_in_decimal][0..n]
optional, string, max chars=39
charges[description][0..n]
optional, string, max chars=250
charges[taxable][0..n]
optional, boolean, default=true
charges[tax_profile_id][0..n]
optional, string, max chars=50
charges[avalara_tax_code][0..n]
optional, string, max chars=50
charges[hsn_code][0..n]
optional, string, max chars=50
charges[taxjar_product_code][0..n]
optional, string, max chars=50
charges[avalara_sale_type][0..n]
optional, enumerated string
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
Show all values[+]
charges[avalara_transaction_type][0..n]
optional, integer
charges[avalara_service_type][0..n]
optional, integer
charges[date_from][0..n]
optional, timestamp(UTC) in seconds
charges[date_to][0..n]
optional, timestamp(UTC) in seconds
unbilled_charges unbilled_charges
always returned
Resource object representing unbilled_charges

Sample admin console URL

https://{site}.chargebee.com/admin-console/unbilled_charges/123x

Use this API to bill the unbilled charges. Available Credits and Excess Payments will automatically be applied while creating the invoice.

If the Auto Collection is turned on for the particular customer, the invoice will be created in payment_due state and the payment collection will be scheduled immediately.

During invoice creation, the PO number for the line items will be filled from the subscription’s current PO number, if available.

If no recurring item is present in the created invoice, the invoice will be marked as recurring=false.

If consolidated invoicing is enabled and the parameter ‘customer_id’ is passed, multiple invoices can be created based on the following factors.

  • Currency
  • PO number if ‘Group by PO number’ is enabled
  • Shipping address
  • Auto Collection
  • Payment method

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_unbilled_charges \
     -u {site_api_key}:\
     -d subscription_id="__test__8aszcSOcqxg162"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoices": [
        {
            "adjustment_credit_notes": [],
            "amount_adjusted": 0,
            "amount_due": 1100,
            "amount_paid": 0,
            "amount_to_collect": 1100,
            "applied_credits": [],
            "base_currency_code": "USD",
            "billing_address": {
                "first_name": "John",
                "last_name": "Doe",
                "object": "billing_address",
                "validation_status": "not_validated"
            },
            "credits_applied": 0,
            "currency_code": "USD",
            "customer_id": "__test__8aszcSOcqxbQ5z",
            "date": 1517495908,
            "deleted": false,
            "due_date": 1517495908,
            "dunning_attempts": [],
            "exchange_rate": 1,
            "first_invoice": true,
            "has_advance_charges": false,
            "id": "__demo_inv__1",
            "is_gifted": false,
            "issued_credit_notes": [],
            "line_items": [
                {
                    "amount": 1000,
                    "customer_id": "__test__8aszcSOcqxbQ5z",
                    "date_from": 1517495907,
                    "date_to": 1519915107,
                    "description": "basic USD",
                    "discount_amount": 0,
                    "entity_id": "basic-USD",
                    "entity_type": "plan_item_price",
                    "id": "li___test__8aszcSOcqxjI64",
                    "is_taxed": false,
                    "item_level_discount_amount": 0,
                    "object": "line_item",
                    "pricing_model": "per_unit",
                    "quantity": 1,
                    "subscription_id": "__test__8aszcSOcqxg162",
                    "tax_amount": 0,
                    "tax_exempt_reason": "tax_not_configured",
                    "unit_amount": 1000
                },
                {..}
            ],
            "linked_orders": [],
            "linked_payments": [],
            "net_term_days": 0,
            "new_sales_amount": 1100,
            "object": "invoice",
            "price_type": "tax_exclusive",
            "recurring": true,
            "resource_version": 1517495908473,
            "round_off_amount": 0,
            "status": "payment_due",
            "sub_total": 1100,
            "subscription_id": "__test__8aszcSOcqxg162",
            "tax": 0,
            "term_finalized": true,
            "total": 1100,
            "updated_at": 1517495908,
            "write_off_amount": 0
        },
        {..}
    ]
}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_unbilled_charges

Method

subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.
customer_id[]
optional, string, max chars=50
Identifier of the customer for whom this invoice needs to be created. Should be specified if 'subscription_id' is not specified. Applicable only if the consolidated invoicing is enabled. .
invoices invoices
always returned
Resource object representing invoices

Sample admin console URL

https://{site}.chargebee.com/admin-console/unbilled_charges/123x
Use this API to delete an unbilled charge by specifying the id of the charge.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/unbilled_charges/li___test__8aszcSOcqxX05r/delete \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "unbilled_charge": {
        "amount": 100,
        "currency_code": "USD",
        "customer_id": "__test__8aszcSOcqxML5l",
        "date_from": 1517495906,
        "date_to": 1519915106,
        "deleted": false,
        "description": "Day Pass USD Monthly",
        "discount_amount": 0,
        "entity_id": "day-pass-USD",
        "entity_type": "addon_item_price",
        "id": "li___test__8aszcSOcqxX05r",
        "is_voided": false,
        "object": "unbilled_charge",
        "pricing_model": "flat_fee",
        "quantity": 1,
        "subscription_id": "__test__8aszcSOcqxTF5o",
        "unit_amount": 100
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges/{unbilled-charge-id}/delete

Method

unbilled_charge unbilled_charge
always returned
Resource object representing unbilled_charge

Sample admin console URL

https://{site}.chargebee.com/admin-console/unbilled_charges/123x
This endpoint lists all the unbilled charges.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/unbilled_charges \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2 \
     --data-urlencode customer_id[is]="__test__8aszcSOcqy1i6F"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "unbilled_charge": {
                "amount": 100,
                "currency_code": "USD",
                "customer_id": "__test__8aszcSOcqy1i6F",
                "date_from": 1517495909,
                "date_to": 1519915109,
                "deleted": false,
                "description": "Day Pass USD Monthly",
                "discount_amount": 0,
                "entity_id": "day-pass-USD",
                "entity_type": "addon_item_price",
                "id": "li___test__8aszcSOcqyBc6L",
                "is_voided": false,
                "object": "unbilled_charge",
                "pricing_model": "flat_fee",
                "quantity": 1,
                "subscription_id": "__test__8aszcSOcqy6V6I",
                "unit_amount": 100
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/unbilled_charges

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
include_deleted[]
optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
is_voided[]
optional, 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.
Filter Params
For operator usages, see the Pagination and Filtering section.
subscription_id[<operator>]
optional, string filter
A unique identifier for the subscription this charge belongs to. Possible values are :
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example subscription_id[is] = "5hjdk8nOpd0b12"
subscription_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
subscription_id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
subscription_id[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
customer_id[<operator>]
optional, string filter
A unique identifier for the customer being charged. Possible values are :
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example customer_id[is] = "5hjdk8nOpd0b12"
customer_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
customer_id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
customer_id[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
unbilled_charge unbilled_charge
always returned
Resource object representing unbilled_charge
next_offset next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/unbilled_charges/123x

This is similar to the "Create an invoice for unbilled charges" API but no invoice will be created, only an estimate for this operation is created.

In the estimate response,

  • estimate.invoice_estimates is an array of estimate.invoice_estimate. This has the details of the invoices that will be generated now.

Note:

  • This API when invoked does not perform the actual operation. It just generates an estimate.
  • Both subscription_id and customer_id parameters should not be given at the same time.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_now_estimate \
     -u {site_api_key}:\
     -d customer_id="__test__8aszcSOcqyER6Q"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "estimate": {
        "created_at": 1517495910,
        "invoice_estimates": [
            {
                "amount_due": 1100,
                "amount_paid": 0,
                "credits_applied": 0,
                "currency_code": "USD",
                "customer_id": "__test__8aszcSOcqyER6Q",
                "date": 1517495910,
                "line_item_discounts": [],
                "line_item_taxes": [],
                "line_items": [
                    {
                        "amount": 1000,
                        "customer_id": "__test__8aszcSOcqyER6Q",
                        "date_from": 1517495909,
                        "date_to": 1519915109,
                        "description": "basic USD",
                        "discount_amount": 0,
                        "entity_id": "basic-USD",
                        "entity_type": "plan_item_price",
                        "id": "li___test__8aszcSOcqyMd6V",
                        "is_taxed": false,
                        "item_level_discount_amount": 0,
                        "object": "line_item",
                        "pricing_model": "per_unit",
                        "quantity": 1,
                        "subscription_id": "__test__8aszcSOcqyJP6T",
                        "tax_amount": 0,
                        "unit_amount": 1000
                    },
                    {..}
                ],
                "object": "invoice_estimate",
                "price_type": "tax_exclusive",
                "recurring": true,
                "round_off_amount": 0,
                "sub_total": 1100,
                "taxes": [],
                "total": 1100
            },
            {..}
        ],
        "object": "estimate"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_now_estimate

Method

subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this estimate needs to be created. Should be given if 'customer_id' is not specified.
customer_id[]
optional, string, max chars=50
Identifier of the customer for whom this estimate is created. Is given if 'subscription_id' is not specified. Applicable only if the 'Consolidated Invoicing' is enabled. If 'Consolidated Invoicing' is not enabled, an invoice will be generated for every subscription.
estimate estimate
always returned
Resource object representing estimate

Sample admin console URL

https://{site}.chargebee.com/admin-console/unbilled_charges/123x