Charge invoices encompass subscription purchases, renewals, immediate subscription changes, final usage invoices, or one-off invoices. When the Credit Invoices feature is enabled on your Recurly site, Recurly will fire webhooks for each stage of the charge invoice lifecycle to keep your systems in sync.

Prerequisites and limitations

Credit Invoices feature must be enabled on your site.
Sites created after May 8, 2018 UTC (May 7, 2018 5 pm PT) have this feature by default.
If not enabled, no charge invoice webhooks will be sent.
Learn More

Key details

Only sent once the Credit Invoices feature is enabled on your Recurly site. Recurly sites created after May 8, 2018 UTC (May 7, 2018 5 pm PT) automatically have the Credit Invoices feature. Learn More

JSON	XML	Description
`charge_invoice.created`	`new_charge_invoice_notification`	Sent when a charge invoice is created. This could be a subscription purchase, renewal, immediate subscription change, final usage invoice, or one-off invoice.
`charge_invoice.processing`	`processing_charge_invoice_notification`	Sent when a charge invoice moves into a processing state due to a processing bank account (ACH) payment.
`charge_invoice.past_due`	`past_due_charge_invoice_notification`	Sent when a charge invoice moves into a past due state due to a transaction decline or reaching the manual net-terms.
`charge_invoice.paid`	`paid_charge_invoice_notification`	Sent when a charge invoice moves to a paid state due to payment by transactions and/or credit payments, or forced paid without a transaction.
`charge_invoice.failed`	`failed_charge_invoice_notification`	Sent when a charge invoice moves to a failed state due to being failed directly or at the end of the dunning cycle.
`charge_invoice.reopened`	`reopened_charge_invoice_notification`	Sent when a charge invoice is reopened. Only manual collection charge invoices can be reopened; with Credit Invoices, only paid manual collection invoices can be reopened.
`charge_invoice.updated`	`updated_charge_invoice_notification`	Sent when a charge invoice is edited.

Charge invoice schema

{
  "id": "ra8fzs41jdxd",
  "object_type": "charge_invoice",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-26T22:03:39Z",
  "invoice_number": 1031
}

<?xml version="1.0" encoding="UTF-8"?>
<new_charge_invoice_notification>
  <account>
    <account_code>1234</account_code>
    <username></username>
    <email></email>
    <first_name></first_name>
    <last_name></last_name>
    <company_name></company_name>
    <phone></phone>
  </account>
  <invoice>
    <uuid>42feb03ce368c0e1ead35d4bfa89b82e</uuid>
    <state>pending</state>
    <origin>renewal</origin>
    <invoice_number_prefix></invoice_number_prefix>
    <invoice_number type="integer">2405</invoice_number>
    <address>
      <address1></address1>
      <address2></address2>
      <city></city>
      <state></state>
      <zip></zip>
      <country></country>
      <phone></phone>
    </address>
    <vat_number></vat_number>
    <currency>USD</currency>
    <balance_in_cents type="integer">100000</balance_in_cents>
    <total_in_cents type="integer">100000</total_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <subtotal_in_cents type="integer">100000</subtotal_in_cents>
    <subtotal_before_discount_in_cents type="integer">100000</subtotal_before_discount_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <subscription_ids type="array">
      <subscription_id>40b8f5e99df03b8684b99d4993b6e089</subscription_id>
    </subscription_ids>
    <customer_notes>Thanks for your business!</customer_notes>
    <created_at type="datetime">2018-02-13T16:00:04Z</created_at>
    <updated_at type="datetime">2018-02-13T16:00:04Z</updated_at>
    <closed_at type="datetime" nil="true"></closed_at>
    <po_number></po_number>
    <terms_and_conditions>Payment can be made out to Acme, Co.</terms_and_conditions>
    <due_on type="dateTime">2018-03-16T15:00:04Z</due_on>
    <net_terms type="integer">30</net_terms>
    <collection_method>manual</collection_method>
  </invoice>
</new_charge_invoice_notification>