Invoices are statements containing charges, adjustments and any discounts for a subscription specific to a term. For every subscription a draft invoice (upcoming invoice) is used to track all the charges, credits and adjustments for the current term.
Generally, an invoice is closed at start of the next term. However, cancellation and other such operations on subscription may trigger premature closing. While closing the invoice, in addition to recurring charges, credits and coupons are applied to calculate the final amount that is due.
When invoice is closed, an attempt to charge the credit card is made. If the payment succeeds, it is marked as paid. If the payment fails, the invoice is marked as payment_due and retry settings are taken into account. If no retry attempts are configured, the invoice is marked as not_paid. If the amount due is zero or negative, the invoice is immediately marked as paid and the balance if any is carried forward to the next term of the invoice.
Note: If consolidated invoicing is enabled, the attribute invoice.subscription_id should not be used (as it will not be present if the invoice has lines from multiple subscriptions). Instead to know the related subscriptions, their line_items' subscription_id attribute should be referred.
{
"amount": 200,
"amount_adjusted": 0,
"amount_due": 0,
"amount_paid": 200,
"billing_address": {
"first_name": "John",
"last_name": "Mathew",
"object": "billing_address"
},
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__3Nl7obaRNQyaXr1S",
"end_date": 1517492040,
"first_invoice": true,
"id": "__demo_inv__13",
"line_items": [
{
"amount": 200,
"date_from": 1517492040,
"date_to": 1517492040,
"description": "non_recurring_addon",
"entity_id": "non_recurring_addon",
"entity_type": "addon",
"is_taxed": false,
"object": "line_item",
"quantity": 2,
"tax": 0,
"type": "charge",
"unit_amount": 100
}
],
"linked_orders": [],
"linked_transactions": [
{
"applied_amount": 200,
"applied_at": 1517492041,
"txn_amount": 200,
"txn_date": 1517492041,
"txn_id": "txn___test__3Nl7obaRNQyacB1a",
"txn_status": "success",
"txn_type": "payment"
}
],
"object": "invoice",
"paid_on": 1517492041,
"price_type": "tax_exclusive",
"recurring": false,
"start_date": 1517492040,
"status": "paid",
"sub_total": 200,
"tax": 0
}
subscription_id
to identify the subscriptions associated with this invoice. However, it is important to avoid using this attribute if the invoice includes charges from multiple subscriptions, as it will be null in such cases. pending
, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date. linked_payments[].txn_amount
for all linked_payments[]
that have txn_status
as success
. total
- amount_paid
- sum of applied_credits.applied_amount
- sum of adjustment_credit_notes.cn_total
- sum of linked_taxes_withheld.amount
. line_items[].amount
- the sum of all line_item_discounts[].discount_amount
. entity_type
and entity_id
defined. There can be up to two notes in this array for which entity_type
and entity_id
are not defined:
invoice_note
parameter for various endpoints in the API that also create invoices. For example, creating a subscription, creating an invoice, and closing a pending invoice.Creates a one-off invoice for multiple 'Non Recurring' addon & ad-hoc charges for a customer. If the 'auto collection' has been turned 'on' for that customer then payment will be immediately collected using the payment method associated with the customer. The invoice will be generated only upon successful collection of payments. However if the 'auto collection' is turned 'off', no collection attempt will be made and the invoice generated would have a “Payment Due” status.
The Shipping Address can be passed, which will then be attached to the generated invoice.
A 'One Time' coupon can be explicitly specified while creating this invoice.
# creates an invoice for 'Non Recurring' addon for a customer. curl https://{site}.chargebee.com/api/v1/invoices \ -u {site_api_key}:\ -d customer_id="__test__3Nl7obaRNQyaXr1S" \ -d shipping_address[first_name]="John" \ -d shipping_address[last_name]="Mathew" \ -d shipping_address[city]="Walnut" \ -d shipping_address[state]="California" \ -d shipping_address[zip]="91789" \ -d shipping_address[country]="US" -d addons[id][0]="non_recurring_addon" \ -d addons[quantity][0]=2
curl https://{site}.chargebee.com/api/v1/invoices/charge \ -u {site_api_key}:\ -d subscription_id="__test__3Nl7obaRNQyaqJ24" \ -d amount=1000 \ -d description="Support Charge"
curl https://{site}.chargebee.com/api/v1/invoices/charge_addon \ -u {site_api_key}:\ -d subscription_id="__test__3Nl7obaRNQyagm1k" \ -d addon_id="non_recurring_addon" \ -d addon_quantity=2
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__36/stop_dunning \ -X POST \ -u {site_api_key}:
Lists all the Invoices.
curl https://{site}.chargebee.com/api/v1/invoices \ -G \ -u {site_api_key}:\ --data-urlencode limit=3
curl https://{site}.chargebee.com/api/v1/customers/__test__3Nl7obaRNQybMo2n/invoices \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
curl https://{site}.chargebee.com/api/v1/subscriptions/__test__3Nl7obaRNQybUb35/invoices \ -G \ -u {site_api_key}:\ --data-urlencode limit=2
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__33 \ -u {site_api_key}:
Gets the invoice as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__34/pdf \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__4/add_charge \ -u {site_api_key}:\ -d amount=150 \ -d description="$0.05 each for 30 messages"
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/add_addon_charge \ -u {site_api_key}:\ -d addon_id="non_recurring_addon" \ -d addon_quantity=2
This API closes the 'pending' invoice. If "metered billing" is used, please ensure that the usage charges are added before invoking this API.
If the ‘Auto-Collection' is turned ‘ON' for the particular customer, the payment for this invoice will be automatically collected.
While closing the pending invoice, the invoice number will be assigned based on the current invoice number sequence. The invoice end date will also be updated with the date of closure.
Available Credits and Excess Payments will automatically be applied while closing the pending invoice.
Closing a pending invoice would be allowed only if the invoice consists of atleast one line-item. Invoices without line-items cannot be closed. However, they can be deleted using the Delete Invoice API.
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/collect \ -X POST \ -u {site_api_key}:
This API can be used to collect the payments for payment_due and not_paid invoices. If no payment method is present for the customer or if the payment is unsuccessful, the corresponding error will be thrown.
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__12/collect_payment \ -X POST \ -u {site_api_key}:
A refund returns money to a customer. The refund request is processed via the payment gateway that was used to charge the customer.
You can choose to either make a full refund for the entire amount or you can do as many partial refunds until you reach the total amount charged for the invoice.
Read more on refunds in our docs.
Error will be thrown if you attempt to:
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__28/refund \ -u {site_api_key}:\ -d refund_amount=1000
transaction
s, and not already refunded.
Note: Any linked_taxes_withheld
associated with the invoice cannot be refunded via this operation. Offline refunds can be recorded for invoices that have been paid via card payments, Amazon Payments, Paypal Express Checkout, as well as offline payments.
Read more on refunds in our docs.
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__27/record_refund \ -u {site_api_key}:\ -d memo="Refunding as customer cancelled the order." \ -d transaction[amount]=100 \ -d transaction[payment_method]="BANK_TRANSFER" \ -d transaction[date]=1517492046
This API voids the specified invoice. If the invoice has been successfully voided using this API, the response will contain the voided 'invoice' object and 'Invoice Updated' event will be triggered. If the void has not been successful, a corresponding error message would be returned.
Voiding an invoice is not possible
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__40/void \ -X POST \ -u {site_api_key}:
This API deletes the specified invoice. If the invoice has been successfully deleted using this API, the response will contain the deleted 'invoice' object. If the deletion has not been successful, a corresponding error message would be returned.
Deleting an invoice is not possible
curl https://{site}.chargebee.com/api/v1/invoices/__demo_inv__19/delete \ -X POST \ -u {site_api_key}: