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 ]
{
"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
}
API Index URL GET
https://{site}.chargebee.com/api/v2/unbilled_charges
optional, string, max chars=40
Uniquely identifies an unbilled charge.
optional, string, max chars=50
A unique identifier for the customer being charged.
optional, string, max chars=50
A unique identifier for the subscription this charge belongs to.
optional, timestamp(UTC) in seconds
Start date of this charge.
optional, timestamp(UTC) in seconds
End date of this charge.
optional, in cents, min=0
Unit amount of the charge item.
optional, enumerated stringThe 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.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
optional, integer, min=0
Quantity of the item which is represented by this charge.
optional, in cents, min=0
Total amount of this charge. Typically equals to unit amount x quantity.
string, max chars=3
The currency code (ISO 4217 format) for the charge.
optional, in cents, min=0
Total discounts for this charge.
optional, string, max chars=250
Detailed description about this charge.
enumerated stringSpecifies 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 case.plan_item_priceIndicates that this line item is based on plan Item Price.addon_item_priceIndicates that this line item is based on addon Item Price.charge_item_priceIndicates that this line item is based on charge Item Price.
optional, string, max chars=100
The identifier of the modelled entity this charge is based on. Will be null for 'adhoc' entity type.
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.
optional, timestamp(UTC) in seconds
Timestamp indicating the date and time this charge got voided.
optional, string, max chars=39The 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.
optional, string, max chars=33The decimal representation of the quantity of this entity. Returned when the entity is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=39The 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.
timestamp(UTC) in seconds
Timestamp indicating when the unbilled charge was last updated
optional, boolean, default=false
The value of this parameter will be true if it is a recurring unbilled charge for a future term.
boolean
Indicates that this resource has been deleted.
optional, list of line_item_tier
The list of tiers applicable for this line item
integer, min=0
The lower limit of a range of units for the tier
optional, integer
The upper limit of a range of units for the tier
integer, min=0
The number of units purchased in a range.
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.
optional, string, max chars=33The 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 is enabled.
optional, string, max chars=33The 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 is enabled.
optional, string, max chars=33The decimal representation of the quantity purchased from this tier. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=40The 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 is enabled.
This endpoint creates unbilled charges for a subscription.
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"
copy
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"
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
},
{..}
]}
Show more...
{"unbilled_charges": [
{
"amount": 100,
"currency_code": "USD",
"customer_id": "__test__5SK2lmRmS627B6q5i",
"date_from": 1517483457,
"date_to": 1517483457,
"deleted": false,
"description": "Implementation charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__5SK2lmRmS627BGu5q",
"is_voided": false,
"object": "unbilled_charge",
"pricing_model": "flat_fee",
"quantity": 1,
"subscription_id": "__test__5SK2lmRmS627BA25k",
"unit_amount": 100
},
{..}
]}
URL Format POST
https://{site}.chargebee.com/api/v2/unbilled_charges
required, string, max chars=50
Identifier of the subscription for which this unbilled charges needs to be created.
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the unbilled_charge.
Parameters for item_prices. Multiple item_prices can be passed by specifying unique indices.
pass parameters as item_prices[<param name>][<idx:0..n>]
item_prices[item_price_id][0..n]
optional, string, max chars=100
A unique ID for your system to identify the item price.
item_prices[quantity][0..n]
optional, integer, min=1
Item price quantity
item_prices[quantity_in_decimal][0..n]
optional, string, max chars=33The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when
multi-decimal pricing is enabled.
item_prices[unit_price][0..n]
optional, in cents, min=0The price or per-unit-price of the item price. By default, it is the
value set for the
item_price
. This is only applicable when the
pricing_model
of the
item_price
is
flat_fee
or
per_unit
. The value depends on the
type of currency.
item_prices[unit_price_in_decimal][0..n]
optional, string, max chars=39The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when
multi-decimal pricing is enabled.
item_prices[date_from][0..n]
optional, timestamp(UTC) in seconds
The time when the service period for the item starts.
item_prices[date_to][0..n]
optional, timestamp(UTC) in seconds
The time when the service period for the item ends.
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[item_price_id][0..n]
optional, string, max chars=100
The id of the item price to which this tier belongs.
item_tiers[starting_unit][0..n]
optional, integer, min=1
The lowest value in the quantity tier.
item_tiers[ending_unit][0..n]
optional, integer
The highest value in the quantity tier.
optional, in cents, default=0, min=0
The per-unit price for the tier when the pricing_model
is tiered
or volume
. The total cost for the item price when the pricing_model
is stairstep
. The value is in the minor unit of the currency.
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33The 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 pricing_model is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33The 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 pricing_model is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
item_tiers[price_in_decimal][0..n]
optional, string, max chars=39The 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 the item. The value is in major units of the currency. Returned when the plan is quantity-based and
multi-decimal pricing is enabled.
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
optional, in cents, min=1The amount to be charged. The unit depends on the
type of currency.
charges[amount_in_decimal][0..n]
optional, string, max chars=39The decimal representation of the amount for the
one-time charge. Provide the value in major units of the currency. Can be provided only when
multi-decimal pricing is enabled.
charges[description][0..n]
optional, string, max chars=250
Description for this charge
optional, boolean, default=true
The amount to be charged is taxable or not.
charges[tax_profile_id][0..n]
optional, string, max chars=50
Tax profile of the charge.
charges[avalara_tax_code][0..n]
optional, string, max chars=50The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=50The
HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
charges[taxjar_product_code][0..n]
optional, string, max chars=50The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
TaxJar integration.
charges[avalara_sale_type][0..n]
optional, enumerated stringIndicates the type of sale carried out. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
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
charges[avalara_transaction_type][0..n]
optional, integerIndicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
charges[avalara_service_type][0..n]
optional, integerIndicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, timestamp(UTC) in seconds
The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
always returned
Resource object representing unbilled_charge
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
Sample Request
curl https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_unbilled_charges \
-X POST \
-u {site_api_key}:\
-d subscription_id="__test__8aszcSOcqxg162"
copy
curl https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_unbilled_charges \
-X POST \
-u {site_api_key}:\
-d subscription_id="__test__8aszcSOcqxg162"
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
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.
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. .
always returned
Resource object representing invoice
Use this API to delete an unbilled charge by specifying the id of the charge.
Sample Request
curl https://{site}.chargebee.com/api/v2/unbilled_charges/li___test__8aszcSOcqxX05r/delete \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/unbilled_charges/li___test__8aszcSOcqxX05r/delete \
-X POST \
-u {site_api_key}:
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
always returned
Resource object representing unbilled_charge
This endpoint lists all the unbilled charges.
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
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"
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
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
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.
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'.
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.
subscription_id[<operator>]
optional, string filter
A unique identifier for the subscription this charge belongs to.
Supported operators : is, is_not, starts_with, is_present, in, not_in
Example → subscription_id[is] = "5hjdk8nOpd0b12"
optional, string filter
A unique identifier for the customer being charged.
Supported operators : is, is_not, starts_with, is_present, in, not_in
Example → customer_id[is] = "5hjdk8nOpd0b12"
always returned
Resource object representing unbilled_charge
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”.
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.
Sample Request
curl https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_now_estimate \
-X POST \
-u {site_api_key}:\
-d customer_id="__test__8aszcSOcqyER6Q"
copy
curl https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_now_estimate \
-X POST \
-u {site_api_key}:\
-d customer_id="__test__8aszcSOcqyER6Q"
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
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.
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.
always returned
Resource object representing estimate