Dunning Event Notifications fire according to your site’s dunning configuration whenever an invoice enters or remains in dunning. Use these webhooks to trigger custom customer outreach—via email, SMS, Slack, or other channels—to improve recovery and reduce churn.

Prerequisites and limitations

Your Recurly site must have dunning configured under Dunning settings.
Notifications are sent regardless of whether you use Recurly’s built-in customer communications.
Payload schema varies based on whether your site has the Credit Invoices feature enabled.

Key details

Sites with the Credit Invoices feature enabled will see the below schema:

{
  "id": "radnhqhipxkw",
  "object_type": "dunning_event",
  "site_id": "radmlv3z8vl6",
  "event_type": "created",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}

<?xml version="1.0" encoding="UTF-8"?>
<new_dunning_event_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>424a9d4a2174b4f39bc776426aa19c32</uuid>
    <state>past_due</state>
    <origin>renewal</origin>
    <invoice_number_prefix></invoice_number_prefix>
    <invoice_number type="integer">1813</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">4000</balance_in_cents>
    <total_in_cents type="integer">4500</total_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <subtotal_in_cents type="integer">4500</subtotal_in_cents>
    <subtotal_before_discount_in_cents type="integer">4500</subtotal_before_discount_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <subscription_ids type="array">
      <subscription_id>4110792b3b01967d854f674b7282f542</subscription_id>
    </subscription_ids>
    <customer_notes>Thanks for your business!</customer_notes>
    <created_at type="datetime">2018-01-09T16:47:43Z</created_at>
    <updated_at type="datetime">2018-02-12T16:50:23Z</updated_at>
    <closed_at type="datetime" nil="true"></closed_at>
    <po_number></po_number>
    <terms_and_conditions></terms_and_conditions>
    <due_on type="datetime">2018-02-09T16:47:43Z</due_on>
    <dunning_events_count type="integer">2</dunning_events_count>
    <final_dunning_event type="boolean">false</final_dunning_event>
    <dunning_campaign_name>Dunning</dunning_campaign_name>
    <dunning_campaign_code>dunning</dunning_campaign_code>
    <dunning_campaign_id>4997ace0f57341adb3e857f9f7d15de8</dunning_campaign_id>
    <net_terms type="integer">30</net_terms>
    <collection_method>manual</collection_method>
  </invoice>
  <subscription>
    <plan>
      <plan_code>gold</plan_code>
      <name>Gold</name>
    </plan>
    <uuid>4110792b3b01967d854f674b7282f542</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">4500</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>training_classes</add_on_code>
        <name>Training Classes</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents type="integer">700</unit_amount_in_cents>
        <add_on_type>fixed</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id nil="true"></measured_unit_id>
      </subscription_add_on>
      <subscription_add_on>
        <add_on_code>executive-brief</add_on_code>
        <name>Executive Brief</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents type="integer">2300</unit_amount_in_cents>
        <add_on_type>fixed</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id nil="true"></measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2017-11-09T16:47:30Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-02-09T16:47:30Z</current_period_started_at>
    <current_period_ends_at type="datetime">2018-03-09T16:47:30Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
  </subscription>
</new_dunning_event_notification>

Sites that do not have the Credit Invoices feature enabled will see the below schema:

{
  "id": "r3oplsj3zo7a",
  "object_type": "account",
  "site_id": "r23khg9b5kyb",
  "event_type": "closed",
  "event_time": "2022-06-24T19:55:25Z"
  "account_code": "verena"
}

<?xml version="1.0" encoding="UTF-8"?>
<new_dunning_event_notification>
  <account>
    <account_code>09f299492d21</account_code>
    <username nil="true"></username>
    <email>[email protected]</email>
    <first_name>Joseph</first_name>
    <last_name>Smith</last_name>
    <company_name nil="true"></company_name>
    <phone>3235626924</phone>
  </account>
  <invoice>
    <uuid>inv-7wr0r2xuawwCjO</uuid>
    <subscription_id>396e4e17640ca516c2f3a84e47ae91dd</subscription_id>
    <state>failed</state>
    <invoice_number_prefix></invoice_number_prefix>
    <invoice_number type="integer">781002</invoice_number>
    <po_number></po_number>
    <vat_number nil="true"></vat_number>
    <total_in_cents type="integer">2499</total_in_cents>
    <currency>USD</currency>
    <date type="datetime">2016-10-26T16:00:12Z</date>
    <closed_at type="datetime">2016-10-27T16:00:26Z</closed_at>
    <net_terms type="integer">0</net_terms>
    <collection_method>automatic</collection_method>
    <due_at type="datetime">2016-10-26T16:00:12Z</due_at>
    <dunning_events_count type="integer">2</dunning_events_count>
    <final_dunning_event type="boolean">false</final_dunning_event>
  </invoice>
  <subscription>
    <plan>
      <plan_code>28a3ae1fc5c00d123429</plan_code>
      <name>41c36e04f2d7bebc</name>
    </plan>
    <uuid>396e4e17640ca516c2f3a84e47ae91dd</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">2499</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2016-10-26T05:42:27Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2016-10-26T16:00:00Z</current_period_started_at>
    <current_period_ends_at type="datetime">2016-11-26T16:00:00Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
  </subscription>
  <transaction>
    <id>397083a9a871b53a3d5a4c469fa1216a</id>
    <invoice_id>397083a76356802de2f5474d299475d8</invoice_id>
    <invoice_number_prefix></invoice_number_prefix>
    <invoice_number type="integer">1002</invoice_number>
    <subscription_id>396e4e17640ca516c2f3a84e47ae91dd</subscription_id>
    <action>purchase</action>
    <date type="datetime">2016-10-26T16:00:12Z</date>
    <gateway>payeezy</gateway>
    <payment_method>credit_card</payment_method>
    <amount_in_cents type="integer">2499</amount_in_cents>
    <status>declined</status>
    <message>Transaction Normal</message>
    <gateway_error_codes>00</gateway_error_codes>
    <failure_type>invalid_data</failure_type>
    <reference>115948823</reference>
    <source>subscription</source>
    <cvv_result code="I">Failed data validation check</cvv_result>
    <avs_result code="1"></avs_result>
    <avs_result_street nil="true"></avs_result_street>
    <avs_result_postal nil="true"></avs_result_postal>
    <billing_phone nil="true"></billing_phone>
    <billing_postal>94605</billing_postal>
    <billing_country>US</billing_country>
    <test type="boolean">true</test>
    <voidable type="boolean">false</voidable>
    <refundable type="boolean">false</refundable>
  </transaction>
</new_dunning_event_notification>