Invoices

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.

Sample invoice [ JSON ]

API Index URL GET

Creates a one-off invoice for multiple 'Non Recurring' add-on & 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 upon successful collection of payments.

However, if the 'auto collection' is turned 'off', no collection attempt will be made and the invoice will be generated in the “Payment Due” status. Customer level auto collection property can be overridden by passing the auto_collection parameter.

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.

You can pass the authorization_transaction_id to capture the already blocked funds to collect the payment. The excess payments will be applied to the invoice followed by the captured authorization payment.

If capturing authorization fails, the invoice will not be created. The invoice creation can be retried by passing the auto-collection as OFF. If the invoice due amount is greater than the authorization & excess payment amount collectively, the invoice status will be returned as payment_due. Collect payment for invoice API can be used to collect the remaining amount due.

Notes

curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d charges[amount][1]="1000" \
     -d charges[description][1]="Support charge"

curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d charges[amount][1]="1000" \
     -d charges[description][1]="Support charge"

Sample Response [ JSON ]

URL Format POST

This API is used to create an invoice for a one-time charge. If Auto Collection is 'ON' (i.e., default payment method is card), a payment attempt will be made on the customer's card. An invoice will be created only if the payment is successful. If Auto Collection is 'OFF', then a 'Payment Due' invoice will be created.

This one-off invoice can be associated with either a Customer or a Subscription. A coupon can be applied while creating this invoice only if it is associated with a customer. As it is a one-off invoice, coupons with "Duration Type" property set as "One Time" and "Apply on" property set as "Invoice Amount" can only be used.

To collect payment for the subscription at the end of the current term, use this API.

Notes

curl  https://{site}.chargebee.com/api/v2/invoices/charge \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d amount="1000" \
     -d description="Support charge"

curl  https://{site}.chargebee.com/api/v2/invoices/charge \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d amount="1000" \
     -d description="Support charge"

Sample Response [ JSON ]

URL Format POST

Creates a one-off invoice for a 'Non Recurring' addon. The charge will be collected immediately from the card on file if 'auto collection' is turned 'on'. The invoice will get created only if this collection attempt succeeds. However if the 'auto collection' is turned 'off', no collection attempt will be made and the invoice will be created as 'Payment Due'.

This one-off invoice can be associated with either a Customer or a Subscription. If associated with a Customer, a 'One Time' coupon applicable to this addon can be specified explictly while creating this invoice. This is not supported if the invoice is associated with a Subscription. However that Subscription's coupons applicable to this addon will get automatically applied during this invoice creation.

To collect payment for a 'Non Recurring' addon at the end of the current term, use this API.

Notes

curl  https://{site}.chargebee.com/api/v2/invoices/charge_addon \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d addon_id="ssl"

curl  https://{site}.chargebee.com/api/v2/invoices/charge_addon \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d addon_id="ssl"

Sample Response [ JSON ]

URL Format POST

curl  https://{site}.chargebee.com/api/v2/invoices/48/stop_dunning \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/48/stop_dunning \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}: \
     -d id="old_inv_001" \
     -d customer_id="8avVGOkx8U1MX" \
     -d subscription_id="8avVGOkx8U1MX" \
     -d date="1394532759" \
     -d total="4900" \
     -d status="payment_due" \
     -d line_items[date_from][1]="1394532759" \
     -d line_items[date_to][1]="1396832759" \
     -d line_items[description][1]="Support Charge" \
     -d line_items[unit_amount][1]="4900" \
     -d line_items[quantity][1]="1" \
     -d line_items[entity_type][1]="plan" \
     -d line_items[entity_id][1]="basic" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}: \
     -d id="old_inv_001" \
     -d customer_id="8avVGOkx8U1MX" \
     -d subscription_id="8avVGOkx8U1MX" \
     -d date="1394532759" \
     -d total="4900" \
     -d status="payment_due" \
     -d line_items[date_from][1]="1394532759" \
     -d line_items[date_to][1]="1396832759" \
     -d line_items[description][1]="Support Charge" \
     -d line_items[unit_amount][1]="4900" \
     -d line_items[quantity][1]="1" \
     -d line_items[entity_type][1]="plan" \
     -d line_items[entity_id][1]="basic" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

URL Format POST

The API will apply payments to an invoice. On applying payments, the invoice amount due will be recalculated. The invoice' status will change to PAID or PAYMENT DUE, depending on the amount of payments applied.

curl  https://{site}.chargebee.com/api/v2/invoices/1/apply_payments \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1/apply_payments \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

The API will apply available credits to an invoice. On applying credits, the invoice amount due will be recalculated. The invoice' status will change to PAID or PAYMENT DUE, depending on the amount of credits applied.

curl  https://{site}.chargebee.com/api/v2/invoices/1/apply_credits \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1/apply_credits \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

Lists all the Invoices.

curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode status[is]="paid" \
     --data-urlencode total[gte]="1000" \
     --data-urlencode sort_by[asc]="date"

curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5" \
     --data-urlencode status[is_not]="paid" \
     --data-urlencode total[gt]="1000" \
     --data-urlencode sort_by[asc]="date"

Sample Response [ JSON ]

URL Format GET

curl  https://{site}.chargebee.com/api/v2/invoices/1 \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1 \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format GET

Sample admin console URL

Gets the invoice as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.

Related Tutorial

• Check out customer portal tutorial on how to download invoice as PDF.

curl  https://{site}.chargebee.com/api/v2/invoices/1/pdf \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1/pdf \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

Adds charge for 'pending' invoice. This API can be used for metered billing. After invoking this API, call close the pending invoice API to collect the charges.

Related Tutorial

• Check out the tutorial on how to use this API

curl  https://{site}.chargebee.com/api/v2/invoices/12/add_charge \
     -u {site_api_key}: \
     -d amount="150" \
     -d description="$0.05 each for 30 messages"

curl  https://{site}.chargebee.com/api/v2/invoices/12/add_charge \
     -u {site_api_key}: \
     -d amount="150" \
     -d description="$0.05 each for 30 messages"

Sample Response [ JSON ]

URL Format POST

Adds non-recurring addon to the 'pending' invoice. This API can be used for metered billing. After invoking this API, call close the pending invoice API to collect the charges.

Related Tutorial

• Check out the tutorial on how to use this API.

curl  https://{site}.chargebee.com/api/v2/invoices/12/add_addon_charge \
     -u {site_api_key}: \
     -d addon_id="ssl"

curl  https://{site}.chargebee.com/api/v2/invoices/12/add_addon_charge \
     -u {site_api_key}: \
     -d addon_id="ssl"

Sample Response [ JSON ]

URL Format POST

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.

Related Tutorial

• Check out the tutorial on how to use metered / usage based billing.

curl  https://{site}.chargebee.com/api/v2/invoices/12/close \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/12/close \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

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.

Pass authorization_transaction_id to capture the already blocked funds to collect the payment. If the invoice due amount is greater than the authorization the invoice status will be returned as payment_due.

Notes

curl  https://{site}.chargebee.com/api/v2/invoices/12/collect_payment \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/12/collect_payment \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

To record a offline payment for an invoice.

The invoice status will be marked as 'paid' if its amount due becomes 0 because of this recorded payment.

Note: If the payment transaction amount is more than the invoice's due amoumt, the remaining transaction amount will be added to the customer's Excess Payments balance to be used against other invoices.

curl  https://{site}.chargebee.com/api/v2/invoices/8/record_payment \
     -u {site_api_key}: \
     -d transaction[amount]="200" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Check payment received for INV-001"

curl  https://{site}.chargebee.com/api/v2/invoices/8/record_payment \
     -u {site_api_key}: \
     -d transaction[amount]="200" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Check payment received for INV-001"

Sample Response [ JSON ]

URL Format POST

This API is used for issuing a automatic 'refund' from a invoice to a customer. The refund request will be processed via the payment gateway that was originally 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:

• refund an offline invoice. You can record refund for such invoices using our record refund API.
• refund a fully refunded invoice.

If the refund transaction succeeds, a Credit Note capturing this refund detail will be created for this invoice.

curl  https://{site}.chargebee.com/api/v2/invoices/1/refund \
     -u {site_api_key}: \
     -d refund_amount="200"

curl  https://{site}.chargebee.com/api/v2/invoices/1/refund \
     -u {site_api_key}: \
     -d refund_amount="200"

Sample Response [ JSON ]

URL Format POST

This API is used for recording offline refund for an invoice. Offline refunds can be recorded for invoices that have been paid via automatic payment methods(Card, Amazon Payments, Paypal Express Checkout etc), as well as offline payment methods.

Read more on refunds in our docs.

If the refund transaction is successfully recorded, a Credit Note capturing this refund detail will be created for this invoice.

curl  https://{site}.chargebee.com/api/v2/invoices/1/record_refund \
     -u {site_api_key}: \
     -d transaction[amount]="100" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Refunding as customer canceled the order."

curl  https://{site}.chargebee.com/api/v2/invoices/1/record_refund \
     -u {site_api_key}: \
     -d transaction[amount]="100" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Refunding as customer canceled the order."

Sample Response [ JSON ]

URL Format POST

This API removes payments applied to an invoice. Once payments applied are removed, the invoice’ status will return to NOT PAID or PAYMENT DUE. The removed payment will be added to customer's excess payment balance.

curl  https://{site}.chargebee.com/api/v2/invoices/1/remove_payment \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1/remove_payment \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

This API removes a credit note attached to an invoice. When you remove a credit note from an invoice, the invoice’ status returns to NOT PAID.

Note: You cannot remove a credit note from an invoice if it has already been refunded.

curl  https://{site}.chargebee.com/api/v2/invoices/1/remove_credit_note \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1/remove_credit_note \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

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 if it has successful payment(s) applied.

Notes

curl  https://{site}.chargebee.com/api/v2/invoices/13/void \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/13/void \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

curl  https://{site}.chargebee.com/api/v2/invoices/1/write_off \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/1/write_off \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

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 if it has successful payment(s) applied

Notes

curl  https://{site}.chargebee.com/api/v2/invoices/13/delete \
     -X POST  \
     -u {site_api_key}:

curl  https://{site}.chargebee.com/api/v2/invoices/13/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

URL Format POST

This API allows you to update the invoice Billing/Shipping address, VAT and PO number. During this operation if Billing Info (Billing Address, vat_number), Shipping info and PO number are not already present in the system the data will be added. If data is already present, the existing values will be replaced.If info is present in the system, but not passed as part of the request, the info will not be removed from the system.

Note: Incase, tax is already applied will now vary due to address change, you cannot update the address. You cannot update the VAT Number if the billing address is not present in the API request.This will update the invoice only, it won't change the corresponding customer/subscription details.

curl  https://{site}.chargebee.com/api/v2/invoices/1/update_details \
     -u {site_api_key}: \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

curl  https://{site}.chargebee.com/api/v2/invoices/1/update_details \
     -u {site_api_key}: \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"

Sample Response [ JSON ]

URL Format POST