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": 1000, "quantity": 1, "discount_amount": 0, "description": "No Trial", "date_to": 1508509618, "unit_amount": 1000, "entity_id": "no_trial", "currency_code": "USD", "subscription_id": "3Nl8KfcQVm8rFB6x", "deleted": false, "entity_type": "plan", "is_voided": false, "id": "li_3Nl8KVeQVm8rHiD", "customer_id": "3Nl8KfcQVm8rFB6x", "date_from": 1505917618, "object": "unbilled_charge" }

API Index URL GET

https://{site}.chargebee.com/api/v2/unbilled_charges
id
Uniquely identifies an unbilled charge.
optional, string, max chars=50
customer_id
A unique identifier for the customer being charged.
optional, string, max chars=50
subscription_id
A unique identifier for the subscription this charge belongs to.
optional, string, max chars=50
date_from
Start date of this charge.
optional, timestamp(UTC) in seconds
date_to
Start date of this charge.
optional, timestamp(UTC) in seconds
unit_amount
Unit amount of the charge item.
optional, in cents, min=0
quantity
Quantity of the item which is represented by this charge.
optional, integer, min=0
amount
Total amount of this charge. Typically equals to unit amount x quantity.
optional, in cents, min=0
currency_code
The currency code (ISO 4217 format) for the charge.
string, max chars=3
discount_amount
Total discounts for this charge.
optional, in cents, min=0
description
Detailed description about this charge.
optional, string, max chars=250
entity_type
Specifies the modelled entity (plan / addon etc) this lineitem is based on.
enumerated string
Possible values are
plan_setupIndicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id.planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.
entity_id
The identifier of the modelled entity this charge is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100
is_voided
Will be true if the charge has been voided. Usually the unbilled charge will be voided and revised to different charges(s) during proration.
boolean, default=false
voided_at
Timestamp indicating the date and time this charge got voided.
optional, timestamp(UTC) in seconds
deleted
Indicates that this resource has been deleted.
boolean

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}:
copy
curl  https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_unbilled_charges \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"invoices": [ { "id": "41", "customer_id": "super_saver", "subscription_id": "super_saver", "recurring": true, "status": "payment_due", "price_type": "tax_exclusive", "date": 1505917716, "due_date": 1505917716, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 1000, "updated_at": 1505917716, "resource_version": 1505917716000, "deleted": false, "object": "invoice", "first_invoice": true, "amount_to_collect": 1000, "new_sales_amount": 1000, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_3Nl8KVeQVm9ECt2Y", "date_from": 1505917706, "date_to": 1508509706, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "subscription_id": "super_saver", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "sub_total": 1000, "linked_payments": [], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Rudolf", "last_name": "Bob", "validation_status": "not_validated", "object": "billing_address" } }, {..} ]}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_unbilled_charges
subscription_id
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
customer_id
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. .
optional, string, max chars=50
Resource object representing invoice.
always returned
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/li3Nl8KioQFWSaBM6/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/unbilled_charges/li3Nl8KioQFWSaBM6/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"unbilled_charge": { "id": "li_3Nl8KVeQVm9GvQ3a", "customer_id": "3Nl8KfcQVm9Gl57L", "subscription_id": "3Nl8KfcQVm9Gl57L", "date_from": 1505917717, "date_to": 1505917717, "unit_amount": 1000, "quantity": 1, "amount": 1000, "discount_amount": 0, "description": "Trainer", "is_voided": false, "deleted": false, "object": "unbilled_charge", "entity_type": "adhoc", "currency_code": "USD" }}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges/{unbilled_charge_id}/delete
Resource object representing unbilled_charge.
always returned
Lists all the unbilled charges.
Sample Request
curl  https://{site}.chargebee.com/api/v2/unbilled_charges \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v2/unbilled_charges \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"unbilled_charge": { "id": "li_3Nl8KVeQVm9EGP2d", "customer_id": "addams", "subscription_id": "addams", "date_from": 1505917706, "date_to": 1508509706, "unit_amount": 1000, "quantity": 1, "amount": 1000, "discount_amount": 0, "description": "No Trial", "entity_id": "no_trial", "is_voided": false, "deleted": false, "object": "unbilled_charge", "entity_type": "plan", "currency_code": "USD" }}, {..} ], "next_offset": "[\"1505917706000\",\"158000000233\"]" }

URL Format GET

https://{site}.chargebee.com/api/v2/unbilled_charges
limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
include_deleted
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
Filter Params
For operator usages, see the Pagination and Filtering section.
subscription_id[<operator>]
To filter based on UnbilledCharge Subscription Id.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example subscription_id[is] = "5hjdk8nOpd0b12"
optional, string filter
customer_id[<operator>]
To filter based on UnbilledCharge Customer Id.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example customer_id[is] = "5hjdk8nOpd0b12"
optional, string filter
Resource object representing unbilled_charge.
always returned
next_offset
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”.
optional, string, max chars=1000

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}:
copy
curl  https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_now_estimate \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"estimate": { "created_at": 1505917717, "object": "estimate", "invoice_estimates": [ { "recurring": true, "price_type": "tax_exclusive", "sub_total": 1000, "total": 1000, "credits_applied": 0, "amount_paid": 0, "amount_due": 1000, "object": "invoice_estimate", "line_items": [ { "id": "li_3Nl8KVeQVm9EGP2d", "date_from": 1505917706, "date_to": 1508509706, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "subscription_id": "addams", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "taxes": [], "line_item_taxes": [], "currency_code": "USD", "line_item_discounts": [] }, {..} ] }}

URL Format POST

https://{site}.chargebee.com/api/v2/unbilled_charges/invoice_now_estimate
subscription_id
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
customer_id
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.
optional, string, max chars=50
Resource object representing estimate.
always returned