{"__v":0,"_id":"5581fa2e8625220d00429f00","initVersion":{"_id":"555fbba928249c1900618a85","version":"1.0"},"project":"555fbba928249c1900618a82","user":{"_id":"55648cf93b87582b003ab8b1","username":"","name":"Chris Bunting"},"hidden":false,"createdAt":"2015-06-17T22:52:30.697Z","fullscreen":false,"htmlmode":false,"html":"","body":"[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Configuration\"\n}\n[/block]\nPlease see our [webhooks documentation](https://docs.recurly.com/push-notifications) for more information.\n\nThere is an example on how to use webhook in PHP available [here](https://github.com/mbeale/recurly-push-notification-example). This example is for educational purposes only and should not be used for mission critical information.\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Available webhooks\"\n}\n[/block]\n* [Account Notifications](https://dev.recurly.com/page/webhooks#account-notifications)\n * [New Account](https://dev.recurly.com/v2.4/page/webhooks#section-new-account)\n * [Closed Account](https://dev.recurly.com/v2.4/page/webhooks#section-closed-account)\n * [Updated Billing information](https://dev.recurly.com/v2.4/page/webhooks#section-updated-billing-information) \n * [Failed Billing Information Update](https://dev.recurly.com/v2.4/page/webhooks#section-failed-billing-information-update)\n * [Reactivated Account](https://dev.recurly.com/v2.4/page/webhooks#section-reactivated-account)\n * [New shipping address created](https://dev.recurly.com/v2.4/page/webhooks#section-a-new-shipping-address-is-created)\n * [Existing shipping address edited](https://dev.recurly.com/v2.4/page/webhooks#section-an-existing-shipping-address-is-edited)\n * [Existing shipping address deleted](https://dev.recurly.com/v2.4/page/webhooks#section-an-existing-shipping-address-is-deleted)\n\n\n* [Subscription Notifications](https://dev.recurly.com/page/webhooks#subscription-notifications)\n * [New Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-new-subscription)\n * [Updated Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-updated-subscription)\n * [Canceled Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-canceled-subscription)\n * [Expired Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-expired-subscription)\n * [Renewed Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-renewed-subscription)\n\n* [Usage Notifications](https://dev.recurly.com/page/webhooks#usage-notifications)\n * [New Usage](https://dev.recurly.com/v2.4/page/webhooks#section-new-usage)\n\n* [Gift Card Notifications](https://dev.recurly.com/page/webhooks#gift-card-notifications)\n * [Purchased Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-purchased-gift-card)\n * [Canceled Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-canceled-gift-card)\n * [Updated Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-updated-gift-card)\n * [Regenerated Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-regenerated-gift-card)\n * [Redeemed Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-redeemed-gift-card)\n * [Updated Balance Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-updated-balance-gift-card)\n\n* [Invoice Notifications](https://dev.recurly.com/page/webhooks#invoice-notifications)\n * [New Invoice](https://dev.recurly.com/v2.4/page/webhooks#section-new-invoice)\n * [New Invoice (Manual)](https://dev.recurly.com/v2.4/page/webhooks#section-new-invoice-manual-)\n * [Processing Invoice (Automatic - Only for ACH payments)](https://dev.recurly.com/v2.4/page/webhooks#section-processing-invoice-automatic-only-for-ach-payments-)\n * [Closed Invoice](https://dev.recurly.com/v2.4/page/webhooks#section-closed-invoice)\n * [Closed Invoice (Manual)](https://dev.recurly.com/v2.4/page/webhooks#section-closed-invoice-manual-) \n * [Past Due Invoice](https://dev.recurly.com/v2.4/page/webhooks#section-past-due-invoice)\n * [Past Due Invoice (Manual)](https://dev.recurly.com/v2.4/page/webhooks#section-past-due-invoice-manual-)\n\n* [Payment Notifications](https://dev.recurly.com/page/webhooks#payment-notifications) \n * [Scheduled Payment (Only for ACH payments)](https://dev.recurly.com/v2.4/page/webhooks#section-scheduled-payment-only-for-ach-payments-)\n * [Processing Payment (Only for ACH payments)](https://dev.recurly.com/v2.4/page/webhooks#section-processing-payment-only-for-ach-payments-)\n * [Successful Payment](https://dev.recurly.com/v2.4/page/webhooks#section-successful-payment)\n * [Manual Payment](https://dev.recurly.com/v2.4/page/webhooks#section-manual-payment)\n * [Failed Payment](https://dev.recurly.com/v2.4/page/webhooks#section-failed-payment)\n * [Successful Refund](https://dev.recurly.com/v2.4/page/webhooks#section-successful-refund)\n * [Void Payment](https://dev.recurly.com/v2.4/page/webhooks#section-void-payment)\n\n* [Dunning Event Notifications](https://dev.recurly.com/page/webhooks#dunning-event-notifications) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Account Notifications\"\n}\n[/block]\n### New Account\n\nSent when a new account is created.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_account_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n</new_account_notification>\n```\n\n### Closed Account\n\nSent when an account is closed.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<canceled_account_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n</canceled_account_notification>\n```\n\n### Updated Billing Information\n\nSent when billing information is successfully created or updated on an account.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<billing_info_updated_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n</billing_info_updated_notification>\n```\n\n### Failed Billing Information Update\n\nSent when an existing account unsuccessfully tries to update the billing information.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<billing_info_update_failed_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n</billing_info_update_failed_notification>\n```\n\n### Reactivated Account\n\nSent when an account subscription is reactivated after having been canceled.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<reactivated_account_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <subscription>\n    <plan>\n      <plan_code>bootstrap</plan_code>\n      <name>Bootstrap</name>\n    </plan>\n    <uuid>6ab458a887d38070807ebb3bed7ac1e5</uuid>\n    <state>active</state>\n    <quantity type=\"integer\">1</quantity>\n    <total_amount_in_cents type=\"integer\">9900</total_amount_in_cents>\n    <subscription_add_ons type=\"array\"/>\n    <activated_at type=\"datetime\">2010-07-22T20:42:05Z</activated_at>\n    <canceled_at nil=\"true\" type=\"datetime\"></canceled_at>\n    <expires_at nil=\"true\" type=\"datetime\"></expires_at>\n    <current_period_started_at type=\"datetime\">2010-09-22T20:42:05Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2010-10-22T20:42:05Z</current_period_ends_at>\n    <trial_started_at nil=\"true\" type=\"datetime\"></trial_started_at>\n    <trial_ends_at nil=\"true\" type=\"datetime\"></trial_ends_at>\n    <collection_method>automatic</collection_method>\n  </subscription>\n</reactivated_account_notification>\n```\n\n### A new shipping address is created\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_shipping_address_notification>\n  <account>\n    <account_code>SamSmith</account_code>\n    <username></username>\n    <email></email>\n    <first_name>Sam</first_name>\n    <last_name>Smith</last_name>\n    <company_name>Smith Co</company_name>\n    <phone></phone>\n  </account>\n  <shipping_address>\n    <id type=\"integer\">2019760742762202549</id>\n    <nickname>Steven</nickname>\n    <first_name>Steven</first_name>\n    <last_name>Smith</last_name>\n    <company_name></company_name>\n    <vat_number></vat_number>\n    <street1>231 Oregon Street</street1>\n    <street2></street2>\n    <city>Portland</city>\n    <state>OR</state>\n    <zip>97201</zip>\n    <country>US</country>\n    <email>stevensmith@example.com</email>\n    <phone></phone>\n  </shipping_address>\n</new_shipping_address_notification>\n```\n\n### An existing shipping address is edited\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n< updated_shipping_address_notification>\n  <account>\n    <account_code>SamSmith</account_code>\n    <username></username>\n    <email></email>\n    <first_name>Sam</first_name>\n    <last_name>Smith</last_name>\n    <company_name>Smith Co</company_name>\n    <phone></phone>\n  </account>\n  <shipping_address>\n    <id type=\"integer\">2019760742762202549</id>\n    <nickname>Steven</nickname>\n    <first_name>Steven</first_name>\n    <last_name>Smith</last_name>\n    <company_name></company_name>\n    <vat_number></vat_number>\n    <street1>231 Oregon Street</street1>\n    <street2></street2>\n    <city>Portland</city>\n    <state>OR</state>\n    <zip>97201</zip>\n    <country>US</country>\n    <email>stevensmith@example.com</email>\n    <phone></phone>\n  </shipping_address>\n</updated_shipping_address_notification>\n```\n\n### An existing shipping address is deleted\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n< deleted_shipping_address_notification>\n  <account>\n    <account_code>SamSmith</account_code>\n    <username></username>\n    <email></email>\n    <first_name>Sam</first_name>\n    <last_name>Smith</last_name>\n    <company_name>Smith Co</company_name>\n    <phone></phone>\n  </account>\n  <shipping_address>\n    <id type=\"integer\">2019760742762202549</id>\n    <nickname>Steven</nickname>\n    <first_name>Steven</first_name>\n    <last_name>Smith</last_name>\n    <company_name></company_name>\n    <vat_number></vat_number>\n    <street1>231 Oregon Street</street1>\n    <street2></street2>\n    <city>Portland</city>\n    <state>OR</state>\n    <zip>97201</zip>\n    <country>US</country>\n    <email>stevensmith@example.com</email>\n    <phone></phone>\n  </shipping_address>\n</deleted_shipping_address_notification>\n```\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Subscription Notifications\"\n}\n[/block]\nSubscriptions will return an array of add-ons if the subscription includes add-ons. If you have a plan on your site with a usage-based add-on, you will start seeing these additional add-on attributes when add-ons are returned:\n*  add_on_type\n*  usage_percentage\n*  measured_unit_id\n\nIn addition, Subscription notifications will include information about shipping addresses when applicable: \n* id\n* nickname\n* first_name\n* last_name\n* company_name\n* vat_number\n* street1\n* street2\n* city\n* state\n* zip\n* country\n* email\n* phone\n\n### New Subscription\n\nSent when a new subscription is created.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_subscription_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\">verena</username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\">Company, Inc.</company_name>\n  </account>\n  <subscription>\n    <plan>\n      <plan_code>bronze</plan_code>\n      <name>Bronze Plan</name>\n    </plan>\n    <uuid>8047cb4fd5f874b14d713d785436ebd3</uuid>\n    <state>active</state>\n    <quantity type=\"integer\">2</quantity>\n    <total_amount_in_cents type=\"integer\">17000</total_amount_in_cents>\n    <subscription_add_ons type=\"array\">\n      <subscription_add_on>\n        <add_on_code>premium_support</add_on_code>\n        <name>Premium Support</name>\n        <quantity type=\"integer\">1</quantity>\n        <unit_amount_in_cents type=\"integer\">15000</unit_amount_in_cents>\n        <add_on_type>fixed</add_on_type>\n        <usage_percentage nil=\"true\"></usage_percentage>\n        <measured_unit_id nil=\"true\"></measured_unit_id>\n      </subscription_add_on>\n      <subscription_add_on>\n        <add_on_code>email_blasts</add_on_code>\n        <name>Email Blasts</name>\n        <quantity type=\"integer\">1</quantity>\n        <unit_amount_in_cents type=\"integer\">50</unit_amount_in_cents>\n        <add_on_type>usage</add_on_type>\n        <usage_percentage nil=\"true\"></usage_percentage>\n        <measured_unit_id type=\"integer\">394681687402874853</measured_unit_id>\n      </subscription_add_on>\n      <subscription_add_on>\n        <add_on_code>donations</add_on_code>\n        <name>Donations</name>\n        <quantity type=\"integer\">1</quantity>\n        <unit_amount_in_cents nil=\"true\"></unit_amount_in_cents>\n        <add_on_type>usage</add_on_type>\n        <usage_percentage>0.6</usage_percentage>\n        <measured_unit_id type=\"integer\">394681920153192422</measured_unit_id>\n      </subscription_add_on>\n    </subscription_add_ons>\n    <activated_at type=\"datetime\">2009-11-22T13:10:38Z</activated_at>\n    <canceled_at type=\"datetime\"></canceled_at>\n    <expires_at type=\"datetime\"></expires_at>\n    <current_period_started_at type=\"datetime\">2009-11-22T13:10:38Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2009-11-29T13:10:38Z</current_period_ends_at>\n    <trial_started_at type=\"datetime\">2009-11-22T13:10:38Z</trial_started_at>\n    <trial_ends_at type=\"datetime\">2009-11-29T13:10:38Z</trial_ends_at>\n    <collection_method>automatic</collection_method>\n  </subscription>\n</new_subscription_notification>\n```\n\n### Updated Subscription\n\nWhen a subscription is upgraded or downgraded, Recurly will send an `updated_subscription_notification`. The notification is sent after the modification is performed. If you modify a subscription and it takes place immediately, the notification will also be sent immediately. If the subscription change takes effect at renewal, then the notification will be sent when the subscription renews. Therefore, if you receive an `updated_subscription_notification`, it contains the latest subscription information.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<updated_subscription_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <subscription>\n    <plan>\n      <plan_code>1dpt</plan_code>\n      <name>Subscription One</name>\n    </plan>\n    <uuid>292332928954ca62fa48048be5ac98ec</uuid>\n    <state>active</state>\n    <quantity type=\"integer\">1</quantity>\n    <total_amount_in_cents type=\"integer\">200</total_amount_in_cents>\n    <subscription_add_ons type=\"array\"/>\n    <activated_at type=\"datetime\">2010-09-23T22:12:39Z</activated_at>\n    <canceled_at nil=\"true\" type=\"datetime\"></canceled_at>\n    <expires_at nil=\"true\" type=\"datetime\"></expires_at>\n    <current_period_started_at type=\"datetime\">2010-09-23T22:03:30Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2010-09-24T22:03:30Z</current_period_ends_at>\n    <trial_started_at nil=\"true\" type=\"datetime\">\n    </trial_started_at>\n    <trial_ends_at nil=\"true\" type=\"datetime\">\n    </trial_ends_at>\n    <collection_method>automatic</collection_method>\n  </subscription>\n</updated_subscription_notification>\n```\n\n### Canceled Subscription\n\nThe `canceled_subscription_notification` is sent when a subscription is canceled.  This means the subscription will not renew. The subscription state is set to canceled but the subscription is still valid until the `expires_at` date. The next notification is sent when the subscription is completely terminated.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<canceled_subscription_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <subscription>\n    <plan>\n      <plan_code>1dpt</plan_code>\n      <name>Subscription One</name>\n    </plan>\n    <uuid>dccd742f4710e78515714d275839f891</uuid>\n    <state>canceled</state>\n    <quantity type=\"integer\">1</quantity>\n    <total_amount_in_cents type=\"integer\">200</total_amount_in_cents>\n    <subscription_add_ons type=\"array\"/>\n    <activated_at type=\"datetime\">2010-09-23T22:05:03Z</activated_at>\n    <canceled_at type=\"datetime\">2010-09-23T22:05:43Z</canceled_at>\n    <expires_at type=\"datetime\">2010-09-24T22:05:03Z</expires_at>\n    <current_period_started_at type=\"datetime\">2010-09-23T22:05:03Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2010-09-24T22:05:03Z</current_period_ends_at>\n    <trial_started_at nil=\"true\" type=\"datetime\"></trial_started_at>\n    <trial_ends_at nil=\"true\" type=\"datetime\"></trial_ends_at>\n    <collection_method>automatic</collection_method>\n  </subscription>\n</canceled_subscription_notification>\n```\n\n### Expired Subscription\n\nThe `expired_subscription_notification` is sent when a subscription is no longer valid. This can happen if a canceled subscription expires or if an active subscription is refunded (and terminated immediately). If you receive this message, the account no longer has a subscription.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<expired_subscription_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <subscription>\n    <plan>\n      <plan_code>1dpt</plan_code>\n      <name>Subscription One</name>\n    </plan>\n    <uuid>d1b6d359a01ded71caed78eaa0fedf8e</uuid>\n    <state>expired</state>\n    <quantity type=\"integer\">1</quantity>\n    <total_amount_in_cents type=\"integer\">200</total_amount_in_cents>\n    <subscription_add_ons type=\"array\"/>\n    <activated_at type=\"datetime\">2010-09-23T22:05:03Z</activated_at>\n    <canceled_at type=\"datetime\">2010-09-23T22:05:43Z</canceled_at>\n    <expires_at type=\"datetime\">2010-09-24T22:05:03Z</expires_at>\n    <current_period_started_at type=\"datetime\">2010-09-23T22:05:03Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2010-09-24T22:05:03Z</current_period_ends_at>\n    <trial_started_at nil=\"true\" type=\"datetime\">\n    </trial_started_at><trial_ends_at nil=\"true\" type=\"datetime\"></trial_ends_at>\n    <collection_method>automatic</collection_method>\n  </subscription>\n</expired_subscription_notification>\n```\n\n### Renewed Subscription\n\nThe `renewed_subscription_notification` is sent whenever a subscription renews. This notification is sent regardless of a successful payment being applied to the subscription---it indicates the previous term is over and the subscription is now in a new term. If you are performing metered or usage-based billing, use this notification to reset your usage stats for the current billing term.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<renewed_subscription_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <subscription>\n    <plan>\n      <plan_code>bootstrap</plan_code>\n      <name>Bootstrap</name>\n    </plan>\n    <uuid>6ab458a887d38070807ebb3bed7ac1e5</uuid>\n    <state>active</state>\n    <quantity type=\"integer\">1</quantity>\n    <total_amount_in_cents type=\"integer\">9900</total_amount_in_cents>\n    <subscription_add_ons type=\"array\"/>\n    <activated_at type=\"datetime\">2010-07-22T20:42:05Z</activated_at>\n    <canceled_at nil=\"true\" type=\"datetime\"></canceled_at>\n    <expires_at nil=\"true\" type=\"datetime\"></expires_at>\n    <current_period_started_at type=\"datetime\">2010-09-22T20:42:05Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2010-10-22T20:42:05Z</current_period_ends_at>\n    <trial_started_at nil=\"true\" type=\"datetime\"></trial_started_at>\n    <trial_ends_at nil=\"true\" type=\"datetime\"></trial_ends_at>\n    <collection_method>automatic</collection_method>\n  </subscription>\n</renewed_subscription_notification>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Usage Notifications\"\n}\n[/block]\n### New Usage\n\nA `new_usage_notification` is sent when we create a usage record on your behalf in a refund or terminate scenario.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_usage_notification>\n  <account>\n    <account_code>923845792374</account_code>\n    <username></username>\n    <email></email>\n    <first_name></first_name>\n    <last_name></last_name>\n    <company_name></company_name>\n  </account>\n  <usage>\n    <id type=\"integer\">394729929104688227</id>\n    <subscription_id>35cda8d4ae0a214f69779e4ddbbc2ebd</subscription_id>\n    <add_on_code>video_storage</add_on_code>\n    <measured_unit_id type=\"integer\">394681920153192422</measured_unit_id>\n    <amount type=\"integer\">-40</amount>\n    <merchant_tag nil=\"true\"></merchant_tag>\n    <recording_timestamp type=\"datetime\">2016-04-28T21:57:53+00:00</recording_timestamp>\n    <usage_timestamp type=\"datetime\">2016-04-28T21:57:53+00:00</usage_timestamp>\n    <created_at type=\"datetime\">2016-04-28T21:57:54+00:00</created_at>\n    <modified_at type=\"datetime\" nil=\"true\"></modified_at>\n    <billed_at type=\"datetime\">2016-04-28T21:57:54+00:00</billed_at>\n    <usage_type>PRICE</usage_type>\n    <unit_amount_in_cents nil=\"true\">50</unit_amount_in_cents>\n    <usage_percentage type=\"float\"></usage_percentage>\n  </usage>\n</new_usage_notification>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Gift Card Notifications\"\n}\n[/block]\n### Purchased Gift Card\n\nA `purchased_gift_card_notification` is sent when a gift card is purchased by a gifter.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<purchased_gift_card_notification>\n  <gift_card>\n    <redemption_code>1A5069E266AED435</redemption_code>\n    <id type=\"integer\">2008976331180115114</id>\n    <product_code>gift_card</product_code>\n    <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <gifter_account_code>84395</gifter_account_code>\n    <recipient_account_code nil=\"true\"></recipient_account_code>\n    <invoice_number type=\"integer\">1105</invoice_number>\n    <delivery>\n      <method>email</method>\n      <email_address>john@example.com</email_address>\n      <deliver_at nil=\"true\"></deliver_at>\n      <first_name>John</first_name>\n      <last_name>Smith</last_name>\n      <address>\n        <address1 nil=\"true\"></address1>\n        <address2 nil=\"true\"></address2>\n        <city nil=\"true\"></city>\n        <state nil=\"true\"></state>\n        <zip nil=\"true\"></zip>\n        <country nil=\"true\"></country>\n        <phone nil=\"true\"></phone>\n      </address>\n      <gifter_name>Sally</gifter_name>\n      <personal_message>\n        Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message>\n    </delivery>\n    <created_at type=\"datetime\">2016-08-03T20:37:21Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T20:37:21Z</updated_at>\n    <delivered_at type=\"datetime\" nil=\"true\"></delivered_at>\n    <redeemed_at type=\"datetime\" nil=\"true\"></redeemed_at>\n    <canceled_at type=\"datetime\" nil=\"true\"></canceled_at>\n  </gift_card>\n</purchased_gift_card_notification>\n```\n\n### Canceled Gift Card\n\nA `canceled_gift_card_notification` is sent when you cancel a gift card from the Admin Console.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<canceled_gift_card_notification>\n  <gift_card>\n    <redemption_code>1A5069E266AED435</redemption_code>\n    <id type=\"integer\">2008976331180115114</id>\n    <product_code>gift_card</product_code>\n    <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <gifter_account_code>84395</gifter_account_code>\n    <recipient_account_code nil=\"true\"></recipient_account_code>\n    <invoice_number type=\"integer\">1105</invoice_number>\n    <delivery>\n      <method>email</method>\n      <email_address>john@example.com</email_address>\n      <deliver_at nil=\"true\"></deliver_at>\n      <first_name>John</first_name>\n      <last_name>Smith</last_name>\n      <address>\n        <address1 nil=\"true\"></address1>\n        <address2 nil=\"true\"></address2>\n        <city nil=\"true\"></city>\n        <state nil=\"true\"></state>\n        <zip nil=\"true\"></zip>\n        <country nil=\"true\"></country>\n        <phone nil=\"true\"></phone>\n      </address>\n      <gifter_name>Sally</gifter_name>\n      <personal_message>\n        Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message>\n    </delivery>\n    <created_at type=\"datetime\">2016-08-03T20:37:21Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T22:00:00Z</updated_at>\n    <delivered_at type=\"datetime\">2016-08-03T20:37:22Z</delivered_at>\n    <redeemed_at type=\"datetime\" nil=\"true\"></redeemed_at>\n    <canceled_at type=\"datetime\">2016-08-04T20:30:22Z</canceled_at>\n  </gift_card>\n</canceled_gift_card_notification>\n```\n\n### Updated Gift Card\n\nAn `updated_gift_card_notification` is sent when you edit a gift card's delivery information from the Admin Console.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<updated_gift_card_notification>\n  <gift_card>\n    <redemption_code>1A5069E266AED435</redemption_code>\n    <id type=\"integer\">2008976331180115114</id>\n    <product_code>gift_card</product_code>\n    <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <gifter_account_code>84395</gifter_account_code>\n    <recipient_account_code nil=\"true\"></recipient_account_code>\n    <invoice_number type=\"integer\">1105</invoice_number>\n    <delivery>\n      <method>email</method>\n      <email_address>john@example.com</email_address>\n      <deliver_at nil=\"true\"></deliver_at>\n      <first_name>John</first_name>\n      <last_name>Smith</last_name>\n      <address>\n        <address1 nil=\"true\"></address1>\n        <address2 nil=\"true\"></address2>\n        <city nil=\"true\"></city>\n        <state nil=\"true\"></state>\n        <zip nil=\"true\"></zip>\n        <country nil=\"true\"></country>\n        <phone nil=\"true\"></phone>\n      </address>\n      <gifter_name>Sally</gifter_name>\n      <personal_message>\n        Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message>\n    </delivery>\n    <created_at type=\"datetime\">2016-08-03T20:37:21Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T22:00:00Z</updated_at>\n    <delivered_at type=\"datetime\">2016-08-03T20:37:22Z</delivered_at>\n    <redeemed_at type=\"datetime\" nil=\"true\"></redeemed_at>\n    <canceled_at type=\"datetime\" nil=\"true\"></canceled_at>\n  </gift_card>\n</updated_gift_card_notification>\n```\n\n### Regenerated Gift Card\n\nA `regenerated_gift_card_notification` is sent when you regenerate a gift card's redemption code from the Admin Console.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<regenerated_gift_card_notification>\n  <gift_card>\n    <redemption_code>1A5069E266AED435</redemption_code>\n    <id type=\"integer\">2008976331180115114</id>\n    <product_code>gift_card</product_code>\n    <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <gifter_account_code>84395</gifter_account_code>\n    <recipient_account_code nil=\"true\"></recipient_account_code>\n    <invoice_number type=\"integer\">1105</invoice_number>\n    <delivery>\n      <method>email</method>\n      <email_address>john@example.com</email_address>\n      <deliver_at nil=\"true\"></deliver_at>\n      <first_name>John</first_name>\n      <last_name>Smith</last_name>\n      <address>\n        <address1 nil=\"true\"></address1>\n        <address2 nil=\"true\"></address2>\n        <city nil=\"true\"></city>\n        <state nil=\"true\"></state>\n        <zip nil=\"true\"></zip>\n        <country nil=\"true\"></country>\n        <phone nil=\"true\"></phone>\n      </address>\n      <gifter_name>Sally</gifter_name>\n      <personal_message>\n        Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message>\n    </delivery>\n    <created_at type=\"datetime\">2016-08-03T20:37:21Z</created_at>\n    <updated_at type=\"datetime\">2016-08-03T22:00:00Z</updated_at>\n    <delivered_at type=\"datetime\">2016-08-03T20:37:22Z</delivered_at>\n    <redeemed_at type=\"datetime\" nil=\"true\"></redeemed_at>\n    <canceled_at type=\"datetime\" nil=\"true\"></canceled_at>\n  </gift_card>\n</regenerated_gift_card_notification>\n```\n\n### Redeemed Gift Card\n\nA `redeemed_gift_card_notification` is sent when a gift card is redeemed by a recipient.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<redeemed_gift_card_notification>\n  <gift_card>\n    <redemption_code>AB54200960E33C93</redemption_code>\n    <id type=\"integer\">2005384587788419212</id>\n    <product_code>gift_card</product_code>\n    <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <gifter_account_code>3543456</gifter_account_code>\n    <recipient_account_code>3547000</recipient_account_code>\n    <invoice_number type=\"integer\">1099</invoice_number>\n    <delivery>\n      <method>email</method>\n      <email_address nil=\"true\"></email_address>\n      <deliver_at nil=\"true\"></deliver_at>\n      <first_name>John</first_name>\n      <last_name>Smith</last_name>\n      <address>\n        <address1 nil=\"true\"></address1>\n        <address2 nil=\"true\"></address2>\n        <city nil=\"true\"></city>\n        <state nil=\"true\"></state>\n        <zip nil=\"true\"></zip>\n        <country nil=\"true\"></country>\n        <phone nil=\"true\"></phone>\n      </address>\n      <gifter_name>Sally</gifter_name>\n      <personal_message>\n        Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message>\n    </delivery>\n    <created_at type=\"datetime\">2016-07-29T21:41:11Z</created_at>\n    <updated_at type=\"datetime\">2016-07-29T21:50:38Z</updated_at>\n    <delivered_at type=\"datetime\">2016-07-29T21:50:38Z</delivered_at>\n    <redeemed_at type=\"datetime\">2016-07-29T21:50:38Z</redeemed_at>\n    <canceled_at type=\"datetime\" nil=\"true\"></canceled_at>\n  </gift_card>\n</redeemed_gift_card_notification>\n```\n\n### Updated Balance Gift Card\n\nAn `updated_balance_gift_card_notification` is sent when the gift card's balance decreases from use on an invoice or increases if credit is returned to the account from a failed invoice.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<updated_balance_gift_card_notification>\n  <gift_card>\n    <redemption_code>AB54200960E33C93</redemption_code>\n    <id type=\"integer\">2005384587788419212</id>\n    <product_code>gift_card</product_code>\n    <unit_amount_in_cents type=\"integer\">1000</unit_amount_in_cents>\n    <currency>USD</currency>\n    <gifter_account_code>3543456</gifter_account_code>\n    <recipient_account_code>3547000</recipient_account_code>\n    <invoice_number type=\"integer\">1099</invoice_number>\n    <delivery>\n      <method>email</method>\n      <email_address nil=\"true\"></email_address>\n      <deliver_at nil=\"true\"></deliver_at>\n      <first_name>John</first_name>\n      <last_name>Smith</last_name>\n      <address>\n        <address1 nil=\"true\"></address1>\n        <address2 nil=\"true\"></address2>\n        <city nil=\"true\"></city>\n        <state nil=\"true\"></state>\n        <zip nil=\"true\"></zip>\n        <country nil=\"true\"></country>\n        <phone nil=\"true\"></phone>\n      </address>\n      <gifter_name>Sally</gifter_name>\n      <personal_message>\n        Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message>\n    </delivery>\n    <created_at type=\"datetime\">2016-07-29T21:41:11Z</created_at>\n    <updated_at type=\"datetime\">2016-08-02T23:50:38Z</updated_at>\n    <delivered_at type=\"datetime\">2016-07-29T21:50:38Z</delivered_at>\n    <redeemed_at type=\"datetime\">2016-07-29T21:50:38Z</redeemed_at>\n    <canceled_at type=\"datetime\" nil=\"true\"></canceled_at>\n    <balance_in_cents type=\"integer\">200</balance_in_cents>\n  </gift_card>\n</updated_balance_gift_card_notification>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Invoice Notifications\"\n}\n[/block]\nAll invoice notifications contain the account and transaction as part of the XML body. The root attribute determines the notification type. In most applications, you can ignore these notifications. Recurly will send you the proper invoice notifications when your application creates or updates an invoice state.\n\n### New Invoice\n\nIf a new invoice is generated, a `new_invoice_notification` is sent.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>open</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1000</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:21:44Z</date>\n    <closed_at type=\"datetime\" nil=\"true\"></closed_at>\n  </invoice>\n</new_invoice_notification>\n```\n\n### New Invoice (Manual)\n\nIf a new manual invoice is generated, a `new_invoice_notification` is sent. For partially paid manual invoices, a `new_invoice_notification` will not be sent after each partial payment.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>open</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1000</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:21:44Z</date>\n    <closed_at type=\"datetime\" nil=\"true\"></closed_at>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>manual</collection_method>\n  </invoice>\n</new_invoice_notification>\n```\n\n### Processing Invoice (Automatic - Only for ACH payments)\n\nIf an invoice is paid with ACH, the invoice will move into a processing state. When the invoice state changes to processing, a `processing_invoice_notification` is sent.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<processing_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>processing</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1000</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:21:44Z</date>\n    <closed_at type=\"datetime\" nil=\"true\"></closed_at>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n  </invoice>\n</processing_invoice_notification>\n```\n\n### Closed Invoice\n\nIf an invoice is closed, a `closed_invoice_notification` is sent. A closed invoice can result from either a failed to collect invoice or fully paid invoice.\n\n```xml\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<closed_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>collected</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1100</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:20:29Z</date>\n    <closed_at type=\"datetime\">2014-01-01T20:24:02Z</closed_at>\n  </invoice>\n</closed_invoice_notification>\n```\n\n### Closed Invoice (Manual)\n\nIf a manual invoice is closed, a `closed_invoice_notification` is sent. A closed invoice can result from either a failed to collect invoice or fully paid invoice. A manual\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<closed_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>collected</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1100</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:20:29Z</date>\n    <closed_at type=\"datetime\">2014-01-01T20:24:02Z</closed_at>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>manual</collection_method>\n  </invoice>\n</closed_invoice_notification>\n```\n\n### Past Due Invoice\n\nIf an invoice is past due, a `past_due_invoice_notification` is sent. An invoice that is past due can result from a failure to collect by the due date.\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<past_due_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>past_due</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1100</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:20:29Z</date>\n    <closed_at type=\"datetime\">2014-01-01T20:24:02Z</closed_at>\n  </invoice>\n</past_due_invoice_notification>\n```\n\n### Past Due Invoice (Manual)\n\nIf a manual invoice is past due, a `past_due_invoice_notification` is sent. An invoice that is past due can result from a failure to collect by the due date.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<past_due_invoice_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verana</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <invoice>\n    <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid>\n    <subscription_id nil=\"true\"></subscription_id>\n    <state>past_due</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1000</invoice_number>\n    <po_number></po_number>\n    <vat_number></vat_number>\n    <total_in_cents type=\"integer\">1100</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2014-01-01T20:20:29Z</date>\n    <closed_at type=\"datetime\">2014-01-01T20:24:02Z</closed_at>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>manual</collection_method>\n  </invoice>\n</past_due_invoice_notification>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Payment Notifications\"\n}\n[/block]\nAll payment notifications contain the account and transaction as part of the XML body. The root attribute determines the notification type. In most applications, you can ignore these notifications. Recurly will send you the proper subscription notifications when your application needs to modify a user's account status. In the near future, Recurly will let you query for a user's transaction history using the API.\n\n### Scheduled Payment (Only for ACH payments)\n\nA `scheduled_payment_notification` is sent when Recurly initiates an ACH payment from a customer entering payment or the renewal procces.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<scheduled_payment_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\">verena</username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\">Company, Inc.</company_name>\n  </account>\n  <transaction>\n    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>\n    <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2009-11-22T13:10:38Z</date>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <status>scheduled</status>\n    <message>Bogus Gateway: Forced success</message>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"\"></cvv_result>\n    <avs_result code=\"\"></avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">true</refundable>\n  </transaction>\n</scheduled_payment_notification>\n```\n\n### Processing Payment (Only for ACH payments)\n\nA `processing_payment_notification` is sent when an ACH payment moves from the scheduled state to the processing state. An ACH payment enters a processing state when it has been submitted to the ACH bank network by Check Gateway.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<processing_payment_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\">verena</username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\">Company, Inc.</company_name>\n  </account>\n  <transaction>\n    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>\n    <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2009-11-22T13:10:38Z</date>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <status>processing</status>\n    <message>Bogus Gateway: Forced success</message>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"\"></cvv_result>\n    <avs_result code=\"\"></avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">true</refundable>\n  </transaction>\n</processing_payment_notification>\n```\n\n### Successful Payment\n\nA `successful_payment_notification` is sent when a payment is successfully captured.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<successful_payment_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\">verena</username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\">Company, Inc.</company_name>\n  </account>\n  <transaction>\n    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>\n    <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2009-11-22T13:10:38Z</date>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <status>success</status>\n    <message>Bogus Gateway: Forced success</message>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"\"></cvv_result>\n    <avs_result code=\"\"></avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">true</refundable>\n  </transaction>\n</successful_payment_notification>\n```\n\n### Manual Payment\n\nA `successful_payment_notification` is also sent when a manual offline payment is recorded.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<successful_payment_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\">verena</username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\">Company, Inc.</company_name>\n  </account>\n  <transaction>\n    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>\n    <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2009-11-22T13:10:38Z</date>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <status>success</status>\n    <message>Bogus Gateway: Forced success</message>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"\"></cvv_result>\n    <avs_result code=\"\"></avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">true</refundable>\n    <manually_entered type=\"boolean\">true</manually_entered>\n    <payment_method>credit_card</payment_method>\n  </transaction>\n</successful_payment_notification>\n```\n\n### Failed Payment\n\nA `failed_payment_notification` is sent when a payment attempt is declined by the payment gateway.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<failed_payment_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\">verena</username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\">Company, Inc.</company_name>\n  </account>\n  <transaction>\n    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>\n    <invoice_id>8fjk3sd7j90s0789dsf099798jkliy65</invoice_id>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2009-11-22T13:10:38Z</date>\n    <gateway>cybersource</gateway>\n    <amount_in_cents type=\"integer\">1000</amount_in_cents>\n    <status>Declined</status>\n    <message>This transaction has been declined</message>\n    <gateway_error_codes nil=\"true\"></gateway_error_codes>\n    <failure_type>Declined by the gateway</failure_type>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"\"></cvv_result>\n    <avs_result code=\"\"></avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">false</voidable>\n    <refundable type=\"boolean\">false</refundable>\n  </transaction>\n</failed_payment_notification>\n```\n\n### Successful Refund\n\nIf you refund an amount through the API or admin interface, a `successful_refund_notification` is sent. Failed refund attempts do not generate a notification.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<successful_refund_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <transaction>\n    <id>2c7a2e30547e49869efd4e8a44b2be34</id>\n    <invoice_id>ffc64d71d4b5404e93f13aac9c63b007</invoice_id>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>credit</action>\n    <date type=\"datetime\">2010-10-06T20:37:55Z</date>\n    <amount_in_cents type=\"integer\">235</amount_in_cents>\n    <status>success</status>\n    <message>Bogus Gateway: Forced success</message>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"\"></cvv_result>\n    <avs_result code=\"\"></avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">true</voidable>\n    <refundable type=\"boolean\">false</refundable>\n  </transaction>\n</successful_refund_notification>\n```\n\n### Void Payment\n\nIf you void a successfully captured payment before it settles, a `void_payment_notification` is sent. Payments can only be voided before the funds settle into your merchant account.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<void_payment_notification>\n  <account>\n    <account_code>1</account_code>\n    <username nil=\"true\"></username>\n    <email>verena@example.com</email>\n    <first_name>Verena</first_name>\n    <last_name>Example</last_name>\n    <company_name nil=\"true\"></company_name>\n  </account>\n  <transaction>\n    <id>4997ace0f57341adb3e857f9f7d15de8</id>\n    <invoice_id>ffc64d71d4b5404e93f13aac9c63b007</invoice_id>\n    <invoice_number type=\"integer\">2059</invoice_number>\n    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2010-10-05T23:00:50Z</date>\n    <amount_in_cents type=\"integer\">235</amount_in_cents>\n    <status>void</status>\n    <message>Test Gateway: Successful test transaction</message>\n    <reference></reference>\n    <source>subscription</source>\n    <cvv_result code=\"M\">Match</cvv_result>\n    <avs_result code=\"D\">Street address and postal code match.</avs_result>\n    <avs_result_street></avs_result_street>\n    <avs_result_postal></avs_result_postal>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">false</voidable>\n    <refundable type=\"boolean\">false</refundable>\n  </transaction>\n</void_payment_notification>\n```\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"Dunning Event Notifications\"\n}\n[/block]\nA `new_dunning_event_notification` is sent when an invoice enters and remains in dunning. This notification will be sent according to your dunning configuration in Recurly. Please note that these are delivered regardless of whether or not you use Recurly to send customer communication. Recurly merchants use this push notification to customize customer email for each dunning step or to reach customers using different communication channels (email, SMS, Slack channel etc) or to reduce customer churn by offering discounts proactively.\n\n```\n<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n<new_dunning_event_notification>\n  <account>\n    <account_code>09f299492d21</account_code>\n    <username nil=\"true\"></username>\n    <email>joseph.smith@gmail.com</email>\n    <first_name>Joseph</first_name>\n    <last_name>Smith</last_name>\n    <company_name nil=\"true\"></company_name>\n    <phone>3235626924</phone>\n  </account>\n  <invoice>\n    <uuid>inv-7wr0r2xuawwCjO</uuid>\n    <subscription_id>396e4e17640ca516c2f3a84e47ae91dd</subscription_id>\n    <state>failed</state>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">781002</invoice_number>\n    <po_number></po_number>\n    <vat_number nil=\"true\"></vat_number>\n    <total_in_cents type=\"integer\">2499</total_in_cents>\n    <currency>USD</currency>\n    <date type=\"datetime\">2016-10-26T16:00:12Z</date>\n    <closed_at type=\"datetime\">2016-10-27T16:00:26Z</closed_at>\n    <net_terms type=\"integer\">0</net_terms>\n    <collection_method>automatic</collection_method>\n    <due_at type=\"datetime\">2016-10-26T16:00:12Z</due_at>\n    <dunning_events_count type=\"integer\">2</dunning_events_count>\n    <final_dunning_event type=\"boolean\">false</final_dunning_event>\n  </invoice>\n  <subscription>\n    <plan>\n      <plan_code>28a3ae1fc5c00d123429</plan_code>\n      <name>41c36e04f2d7bebc</name>\n    </plan>\n    <uuid>396e4e17640ca516c2f3a84e47ae91dd</uuid>\n    <state>active</state>\n    <quantity type=\"integer\">1</quantity>\n    <total_amount_in_cents type=\"integer\">2499</total_amount_in_cents>\n    <subscription_add_ons type=\"array\"/>\n    <activated_at type=\"datetime\">2016-10-26T05:42:27Z</activated_at>\n    <canceled_at type=\"datetime\" nil=\"true\"></canceled_at>\n    <expires_at type=\"datetime\" nil=\"true\"></expires_at>\n    <current_period_started_at type=\"datetime\">2016-10-26T16:00:00Z</current_period_started_at>\n    <current_period_ends_at type=\"datetime\">2016-11-26T16:00:00Z</current_period_ends_at>\n    <trial_started_at type=\"datetime\" nil=\"true\"></trial_started_at>\n    <trial_ends_at type=\"datetime\" nil=\"true\"></trial_ends_at>\n  </subscription>\n  <transaction>\n    <id>397083a9a871b53a3d5a4c469fa1216a</id>\n    <invoice_id>397083a76356802de2f5474d299475d8</invoice_id>\n    <invoice_number_prefix></invoice_number_prefix>\n    <invoice_number type=\"integer\">1002</invoice_number>\n    <subscription_id>396e4e17640ca516c2f3a84e47ae91dd</subscription_id>\n    <action>purchase</action>\n    <date type=\"datetime\">2016-10-26T16:00:12Z</date>\n    <gateway>payeezy</gateway>\n    <payment_method>credit_card</payment_method>\n    <amount_in_cents type=\"integer\">2499</amount_in_cents>\n    <status>declined</status>\n    <message>Transaction Normal</message>\n    <gateway_error_codes>00</gateway_error_codes>\n    <failure_type>invalid_data</failure_type>\n    <reference>115948823</reference>\n    <source>subscription</source>\n    <cvv_result code=\"I\">Failed data validation check</cvv_result>\n    <avs_result code=\"1\"></avs_result>\n    <avs_result_street nil=\"true\"></avs_result_street>\n    <avs_result_postal nil=\"true\"></avs_result_postal>\n    <billing_phone nil=\"true\"></billing_phone>\n    <billing_postal>94605</billing_postal>\n    <billing_country>US</billing_country>\n    <test type=\"boolean\">true</test>\n    <voidable type=\"boolean\">false</voidable>\n    <refundable type=\"boolean\">false</refundable>\n  </transaction>\n</new_dunning_event_notification>\n```","slug":"webhooks","title":"Webhooks"}

Webhooks


[block:api-header] { "type": "basic", "title": "Configuration" } [/block] Please see our [webhooks documentation](https://docs.recurly.com/push-notifications) for more information. There is an example on how to use webhook in PHP available [here](https://github.com/mbeale/recurly-push-notification-example). This example is for educational purposes only and should not be used for mission critical information. [block:api-header] { "type": "basic", "title": "Available webhooks" } [/block] * [Account Notifications](https://dev.recurly.com/page/webhooks#account-notifications) * [New Account](https://dev.recurly.com/v2.4/page/webhooks#section-new-account) * [Closed Account](https://dev.recurly.com/v2.4/page/webhooks#section-closed-account) * [Updated Billing information](https://dev.recurly.com/v2.4/page/webhooks#section-updated-billing-information) * [Failed Billing Information Update](https://dev.recurly.com/v2.4/page/webhooks#section-failed-billing-information-update) * [Reactivated Account](https://dev.recurly.com/v2.4/page/webhooks#section-reactivated-account) * [New shipping address created](https://dev.recurly.com/v2.4/page/webhooks#section-a-new-shipping-address-is-created) * [Existing shipping address edited](https://dev.recurly.com/v2.4/page/webhooks#section-an-existing-shipping-address-is-edited) * [Existing shipping address deleted](https://dev.recurly.com/v2.4/page/webhooks#section-an-existing-shipping-address-is-deleted) * [Subscription Notifications](https://dev.recurly.com/page/webhooks#subscription-notifications) * [New Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-new-subscription) * [Updated Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-updated-subscription) * [Canceled Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-canceled-subscription) * [Expired Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-expired-subscription) * [Renewed Subscription](https://dev.recurly.com/v2.4/page/webhooks#section-renewed-subscription) * [Usage Notifications](https://dev.recurly.com/page/webhooks#usage-notifications) * [New Usage](https://dev.recurly.com/v2.4/page/webhooks#section-new-usage) * [Gift Card Notifications](https://dev.recurly.com/page/webhooks#gift-card-notifications) * [Purchased Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-purchased-gift-card) * [Canceled Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-canceled-gift-card) * [Updated Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-updated-gift-card) * [Regenerated Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-regenerated-gift-card) * [Redeemed Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-redeemed-gift-card) * [Updated Balance Gift Card](https://dev.recurly.com/v2.4/page/webhooks#section-updated-balance-gift-card) * [Invoice Notifications](https://dev.recurly.com/page/webhooks#invoice-notifications) * [New Invoice](https://dev.recurly.com/v2.4/page/webhooks#section-new-invoice) * [New Invoice (Manual)](https://dev.recurly.com/v2.4/page/webhooks#section-new-invoice-manual-) * [Processing Invoice (Automatic - Only for ACH payments)](https://dev.recurly.com/v2.4/page/webhooks#section-processing-invoice-automatic-only-for-ach-payments-) * [Closed Invoice](https://dev.recurly.com/v2.4/page/webhooks#section-closed-invoice) * [Closed Invoice (Manual)](https://dev.recurly.com/v2.4/page/webhooks#section-closed-invoice-manual-) * [Past Due Invoice](https://dev.recurly.com/v2.4/page/webhooks#section-past-due-invoice) * [Past Due Invoice (Manual)](https://dev.recurly.com/v2.4/page/webhooks#section-past-due-invoice-manual-) * [Payment Notifications](https://dev.recurly.com/page/webhooks#payment-notifications) * [Scheduled Payment (Only for ACH payments)](https://dev.recurly.com/v2.4/page/webhooks#section-scheduled-payment-only-for-ach-payments-) * [Processing Payment (Only for ACH payments)](https://dev.recurly.com/v2.4/page/webhooks#section-processing-payment-only-for-ach-payments-) * [Successful Payment](https://dev.recurly.com/v2.4/page/webhooks#section-successful-payment) * [Manual Payment](https://dev.recurly.com/v2.4/page/webhooks#section-manual-payment) * [Failed Payment](https://dev.recurly.com/v2.4/page/webhooks#section-failed-payment) * [Successful Refund](https://dev.recurly.com/v2.4/page/webhooks#section-successful-refund) * [Void Payment](https://dev.recurly.com/v2.4/page/webhooks#section-void-payment) * [Dunning Event Notifications](https://dev.recurly.com/page/webhooks#dunning-event-notifications) [block:api-header] { "type": "basic", "title": "Account Notifications" } [/block] ### New Account Sent when a new account is created. ```xml <?xml version="1.0" encoding="UTF-8"?> <new_account_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> </new_account_notification> ``` ### Closed Account Sent when an account is closed. ```xml <?xml version="1.0" encoding="UTF-8"?> <canceled_account_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> </canceled_account_notification> ``` ### Updated Billing Information Sent when billing information is successfully created or updated on an account. ```xml <?xml version="1.0" encoding="UTF-8"?> <billing_info_updated_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> </billing_info_updated_notification> ``` ### Failed Billing Information Update Sent when an existing account unsuccessfully tries to update the billing information. ```xml <?xml version="1.0" encoding="UTF-8"?> <billing_info_update_failed_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> </billing_info_update_failed_notification> ``` ### Reactivated Account Sent when an account subscription is reactivated after having been canceled. ```xml <?xml version="1.0" encoding="UTF-8"?> <reactivated_account_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <subscription> <plan> <plan_code>bootstrap</plan_code> <name>Bootstrap</name> </plan> <uuid>6ab458a887d38070807ebb3bed7ac1e5</uuid> <state>active</state> <quantity type="integer">1</quantity> <total_amount_in_cents type="integer">9900</total_amount_in_cents> <subscription_add_ons type="array"/> <activated_at type="datetime">2010-07-22T20:42:05Z</activated_at> <canceled_at nil="true" type="datetime"></canceled_at> <expires_at nil="true" type="datetime"></expires_at> <current_period_started_at type="datetime">2010-09-22T20:42:05Z</current_period_started_at> <current_period_ends_at type="datetime">2010-10-22T20:42:05Z</current_period_ends_at> <trial_started_at nil="true" type="datetime"></trial_started_at> <trial_ends_at nil="true" type="datetime"></trial_ends_at> <collection_method>automatic</collection_method> </subscription> </reactivated_account_notification> ``` ### A new shipping address is created ```xml <?xml version="1.0" encoding="UTF-8"?> <new_shipping_address_notification> <account> <account_code>SamSmith</account_code> <username></username> <email></email> <first_name>Sam</first_name> <last_name>Smith</last_name> <company_name>Smith Co</company_name> <phone></phone> </account> <shipping_address> <id type="integer">2019760742762202549</id> <nickname>Steven</nickname> <first_name>Steven</first_name> <last_name>Smith</last_name> <company_name></company_name> <vat_number></vat_number> <street1>231 Oregon Street</street1> <street2></street2> <city>Portland</city> <state>OR</state> <zip>97201</zip> <country>US</country> <email>stevensmith@example.com</email> <phone></phone> </shipping_address> </new_shipping_address_notification> ``` ### An existing shipping address is edited ```xml <?xml version="1.0" encoding="UTF-8"?> < updated_shipping_address_notification> <account> <account_code>SamSmith</account_code> <username></username> <email></email> <first_name>Sam</first_name> <last_name>Smith</last_name> <company_name>Smith Co</company_name> <phone></phone> </account> <shipping_address> <id type="integer">2019760742762202549</id> <nickname>Steven</nickname> <first_name>Steven</first_name> <last_name>Smith</last_name> <company_name></company_name> <vat_number></vat_number> <street1>231 Oregon Street</street1> <street2></street2> <city>Portland</city> <state>OR</state> <zip>97201</zip> <country>US</country> <email>stevensmith@example.com</email> <phone></phone> </shipping_address> </updated_shipping_address_notification> ``` ### An existing shipping address is deleted ```xml <?xml version="1.0" encoding="UTF-8"?> < deleted_shipping_address_notification> <account> <account_code>SamSmith</account_code> <username></username> <email></email> <first_name>Sam</first_name> <last_name>Smith</last_name> <company_name>Smith Co</company_name> <phone></phone> </account> <shipping_address> <id type="integer">2019760742762202549</id> <nickname>Steven</nickname> <first_name>Steven</first_name> <last_name>Smith</last_name> <company_name></company_name> <vat_number></vat_number> <street1>231 Oregon Street</street1> <street2></street2> <city>Portland</city> <state>OR</state> <zip>97201</zip> <country>US</country> <email>stevensmith@example.com</email> <phone></phone> </shipping_address> </deleted_shipping_address_notification> ``` [block:api-header] { "type": "basic", "title": "Subscription Notifications" } [/block] Subscriptions will return an array of add-ons if the subscription includes add-ons. If you have a plan on your site with a usage-based add-on, you will start seeing these additional add-on attributes when add-ons are returned: * add_on_type * usage_percentage * measured_unit_id In addition, Subscription notifications will include information about shipping addresses when applicable: * id * nickname * first_name * last_name * company_name * vat_number * street1 * street2 * city * state * zip * country * email * phone ### New Subscription Sent when a new subscription is created. ``` <?xml version="1.0" encoding="UTF-8"?> <new_subscription_notification> <account> <account_code>1</account_code> <username nil="true">verena</username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true">Company, Inc.</company_name> </account> <subscription> <plan> <plan_code>bronze</plan_code> <name>Bronze Plan</name> </plan> <uuid>8047cb4fd5f874b14d713d785436ebd3</uuid> <state>active</state> <quantity type="integer">2</quantity> <total_amount_in_cents type="integer">17000</total_amount_in_cents> <subscription_add_ons type="array"> <subscription_add_on> <add_on_code>premium_support</add_on_code> <name>Premium Support</name> <quantity type="integer">1</quantity> <unit_amount_in_cents type="integer">15000</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>email_blasts</add_on_code> <name>Email Blasts</name> <quantity type="integer">1</quantity> <unit_amount_in_cents type="integer">50</unit_amount_in_cents> <add_on_type>usage</add_on_type> <usage_percentage nil="true"></usage_percentage> <measured_unit_id type="integer">394681687402874853</measured_unit_id> </subscription_add_on> <subscription_add_on> <add_on_code>donations</add_on_code> <name>Donations</name> <quantity type="integer">1</quantity> <unit_amount_in_cents nil="true"></unit_amount_in_cents> <add_on_type>usage</add_on_type> <usage_percentage>0.6</usage_percentage> <measured_unit_id type="integer">394681920153192422</measured_unit_id> </subscription_add_on> </subscription_add_ons> <activated_at type="datetime">2009-11-22T13:10:38Z</activated_at> <canceled_at type="datetime"></canceled_at> <expires_at type="datetime"></expires_at> <current_period_started_at type="datetime">2009-11-22T13:10:38Z</current_period_started_at> <current_period_ends_at type="datetime">2009-11-29T13:10:38Z</current_period_ends_at> <trial_started_at type="datetime">2009-11-22T13:10:38Z</trial_started_at> <trial_ends_at type="datetime">2009-11-29T13:10:38Z</trial_ends_at> <collection_method>automatic</collection_method> </subscription> </new_subscription_notification> ``` ### Updated Subscription When a subscription is upgraded or downgraded, Recurly will send an `updated_subscription_notification`. The notification is sent after the modification is performed. If you modify a subscription and it takes place immediately, the notification will also be sent immediately. If the subscription change takes effect at renewal, then the notification will be sent when the subscription renews. Therefore, if you receive an `updated_subscription_notification`, it contains the latest subscription information. ``` <?xml version="1.0" encoding="UTF-8"?> <updated_subscription_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <subscription> <plan> <plan_code>1dpt</plan_code> <name>Subscription One</name> </plan> <uuid>292332928954ca62fa48048be5ac98ec</uuid> <state>active</state> <quantity type="integer">1</quantity> <total_amount_in_cents type="integer">200</total_amount_in_cents> <subscription_add_ons type="array"/> <activated_at type="datetime">2010-09-23T22:12:39Z</activated_at> <canceled_at nil="true" type="datetime"></canceled_at> <expires_at nil="true" type="datetime"></expires_at> <current_period_started_at type="datetime">2010-09-23T22:03:30Z</current_period_started_at> <current_period_ends_at type="datetime">2010-09-24T22:03:30Z</current_period_ends_at> <trial_started_at nil="true" type="datetime"> </trial_started_at> <trial_ends_at nil="true" type="datetime"> </trial_ends_at> <collection_method>automatic</collection_method> </subscription> </updated_subscription_notification> ``` ### Canceled Subscription The `canceled_subscription_notification` is sent when a subscription is canceled. This means the subscription will not renew. The subscription state is set to canceled but the subscription is still valid until the `expires_at` date. The next notification is sent when the subscription is completely terminated. ``` <?xml version="1.0" encoding="UTF-8"?> <canceled_subscription_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <subscription> <plan> <plan_code>1dpt</plan_code> <name>Subscription One</name> </plan> <uuid>dccd742f4710e78515714d275839f891</uuid> <state>canceled</state> <quantity type="integer">1</quantity> <total_amount_in_cents type="integer">200</total_amount_in_cents> <subscription_add_ons type="array"/> <activated_at type="datetime">2010-09-23T22:05:03Z</activated_at> <canceled_at type="datetime">2010-09-23T22:05:43Z</canceled_at> <expires_at type="datetime">2010-09-24T22:05:03Z</expires_at> <current_period_started_at type="datetime">2010-09-23T22:05:03Z</current_period_started_at> <current_period_ends_at type="datetime">2010-09-24T22:05:03Z</current_period_ends_at> <trial_started_at nil="true" type="datetime"></trial_started_at> <trial_ends_at nil="true" type="datetime"></trial_ends_at> <collection_method>automatic</collection_method> </subscription> </canceled_subscription_notification> ``` ### Expired Subscription The `expired_subscription_notification` is sent when a subscription is no longer valid. This can happen if a canceled subscription expires or if an active subscription is refunded (and terminated immediately). If you receive this message, the account no longer has a subscription. ``` <?xml version="1.0" encoding="UTF-8"?> <expired_subscription_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <subscription> <plan> <plan_code>1dpt</plan_code> <name>Subscription One</name> </plan> <uuid>d1b6d359a01ded71caed78eaa0fedf8e</uuid> <state>expired</state> <quantity type="integer">1</quantity> <total_amount_in_cents type="integer">200</total_amount_in_cents> <subscription_add_ons type="array"/> <activated_at type="datetime">2010-09-23T22:05:03Z</activated_at> <canceled_at type="datetime">2010-09-23T22:05:43Z</canceled_at> <expires_at type="datetime">2010-09-24T22:05:03Z</expires_at> <current_period_started_at type="datetime">2010-09-23T22:05:03Z</current_period_started_at> <current_period_ends_at type="datetime">2010-09-24T22:05:03Z</current_period_ends_at> <trial_started_at nil="true" type="datetime"> </trial_started_at><trial_ends_at nil="true" type="datetime"></trial_ends_at> <collection_method>automatic</collection_method> </subscription> </expired_subscription_notification> ``` ### Renewed Subscription The `renewed_subscription_notification` is sent whenever a subscription renews. This notification is sent regardless of a successful payment being applied to the subscription---it indicates the previous term is over and the subscription is now in a new term. If you are performing metered or usage-based billing, use this notification to reset your usage stats for the current billing term. ``` <?xml version="1.0" encoding="UTF-8"?> <renewed_subscription_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <subscription> <plan> <plan_code>bootstrap</plan_code> <name>Bootstrap</name> </plan> <uuid>6ab458a887d38070807ebb3bed7ac1e5</uuid> <state>active</state> <quantity type="integer">1</quantity> <total_amount_in_cents type="integer">9900</total_amount_in_cents> <subscription_add_ons type="array"/> <activated_at type="datetime">2010-07-22T20:42:05Z</activated_at> <canceled_at nil="true" type="datetime"></canceled_at> <expires_at nil="true" type="datetime"></expires_at> <current_period_started_at type="datetime">2010-09-22T20:42:05Z</current_period_started_at> <current_period_ends_at type="datetime">2010-10-22T20:42:05Z</current_period_ends_at> <trial_started_at nil="true" type="datetime"></trial_started_at> <trial_ends_at nil="true" type="datetime"></trial_ends_at> <collection_method>automatic</collection_method> </subscription> </renewed_subscription_notification> ``` [block:api-header] { "type": "basic", "title": "Usage Notifications" } [/block] ### New Usage A `new_usage_notification` is sent when we create a usage record on your behalf in a refund or terminate scenario. ``` <?xml version="1.0" encoding="UTF-8"?> <new_usage_notification> <account> <account_code>923845792374</account_code> <username></username> <email></email> <first_name></first_name> <last_name></last_name> <company_name></company_name> </account> <usage> <id type="integer">394729929104688227</id> <subscription_id>35cda8d4ae0a214f69779e4ddbbc2ebd</subscription_id> <add_on_code>video_storage</add_on_code> <measured_unit_id type="integer">394681920153192422</measured_unit_id> <amount type="integer">-40</amount> <merchant_tag nil="true"></merchant_tag> <recording_timestamp type="datetime">2016-04-28T21:57:53+00:00</recording_timestamp> <usage_timestamp type="datetime">2016-04-28T21:57:53+00:00</usage_timestamp> <created_at type="datetime">2016-04-28T21:57:54+00:00</created_at> <modified_at type="datetime" nil="true"></modified_at> <billed_at type="datetime">2016-04-28T21:57:54+00:00</billed_at> <usage_type>PRICE</usage_type> <unit_amount_in_cents nil="true">50</unit_amount_in_cents> <usage_percentage type="float"></usage_percentage> </usage> </new_usage_notification> ``` [block:api-header] { "type": "basic", "title": "Gift Card Notifications" } [/block] ### Purchased Gift Card A `purchased_gift_card_notification` is sent when a gift card is purchased by a gifter. ``` <?xml version="1.0" encoding="UTF-8"?> <purchased_gift_card_notification> <gift_card> <redemption_code>1A5069E266AED435</redemption_code> <id type="integer">2008976331180115114</id> <product_code>gift_card</product_code> <unit_amount_in_cents type="integer">1000</unit_amount_in_cents> <currency>USD</currency> <gifter_account_code>84395</gifter_account_code> <recipient_account_code nil="true"></recipient_account_code> <invoice_number type="integer">1105</invoice_number> <delivery> <method>email</method> <email_address>john@example.com</email_address> <deliver_at nil="true"></deliver_at> <first_name>John</first_name> <last_name>Smith</last_name> <address> <address1 nil="true"></address1> <address2 nil="true"></address2> <city nil="true"></city> <state nil="true"></state> <zip nil="true"></zip> <country nil="true"></country> <phone nil="true"></phone> </address> <gifter_name>Sally</gifter_name> <personal_message> Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message> </delivery> <created_at type="datetime">2016-08-03T20:37:21Z</created_at> <updated_at type="datetime">2016-08-03T20:37:21Z</updated_at> <delivered_at type="datetime" nil="true"></delivered_at> <redeemed_at type="datetime" nil="true"></redeemed_at> <canceled_at type="datetime" nil="true"></canceled_at> </gift_card> </purchased_gift_card_notification> ``` ### Canceled Gift Card A `canceled_gift_card_notification` is sent when you cancel a gift card from the Admin Console. ``` <?xml version="1.0" encoding="UTF-8"?> <canceled_gift_card_notification> <gift_card> <redemption_code>1A5069E266AED435</redemption_code> <id type="integer">2008976331180115114</id> <product_code>gift_card</product_code> <unit_amount_in_cents type="integer">1000</unit_amount_in_cents> <currency>USD</currency> <gifter_account_code>84395</gifter_account_code> <recipient_account_code nil="true"></recipient_account_code> <invoice_number type="integer">1105</invoice_number> <delivery> <method>email</method> <email_address>john@example.com</email_address> <deliver_at nil="true"></deliver_at> <first_name>John</first_name> <last_name>Smith</last_name> <address> <address1 nil="true"></address1> <address2 nil="true"></address2> <city nil="true"></city> <state nil="true"></state> <zip nil="true"></zip> <country nil="true"></country> <phone nil="true"></phone> </address> <gifter_name>Sally</gifter_name> <personal_message> Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message> </delivery> <created_at type="datetime">2016-08-03T20:37:21Z</created_at> <updated_at type="datetime">2016-08-03T22:00:00Z</updated_at> <delivered_at type="datetime">2016-08-03T20:37:22Z</delivered_at> <redeemed_at type="datetime" nil="true"></redeemed_at> <canceled_at type="datetime">2016-08-04T20:30:22Z</canceled_at> </gift_card> </canceled_gift_card_notification> ``` ### Updated Gift Card An `updated_gift_card_notification` is sent when you edit a gift card's delivery information from the Admin Console. ``` <?xml version="1.0" encoding="UTF-8"?> <updated_gift_card_notification> <gift_card> <redemption_code>1A5069E266AED435</redemption_code> <id type="integer">2008976331180115114</id> <product_code>gift_card</product_code> <unit_amount_in_cents type="integer">1000</unit_amount_in_cents> <currency>USD</currency> <gifter_account_code>84395</gifter_account_code> <recipient_account_code nil="true"></recipient_account_code> <invoice_number type="integer">1105</invoice_number> <delivery> <method>email</method> <email_address>john@example.com</email_address> <deliver_at nil="true"></deliver_at> <first_name>John</first_name> <last_name>Smith</last_name> <address> <address1 nil="true"></address1> <address2 nil="true"></address2> <city nil="true"></city> <state nil="true"></state> <zip nil="true"></zip> <country nil="true"></country> <phone nil="true"></phone> </address> <gifter_name>Sally</gifter_name> <personal_message> Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message> </delivery> <created_at type="datetime">2016-08-03T20:37:21Z</created_at> <updated_at type="datetime">2016-08-03T22:00:00Z</updated_at> <delivered_at type="datetime">2016-08-03T20:37:22Z</delivered_at> <redeemed_at type="datetime" nil="true"></redeemed_at> <canceled_at type="datetime" nil="true"></canceled_at> </gift_card> </updated_gift_card_notification> ``` ### Regenerated Gift Card A `regenerated_gift_card_notification` is sent when you regenerate a gift card's redemption code from the Admin Console. ``` <?xml version="1.0" encoding="UTF-8"?> <regenerated_gift_card_notification> <gift_card> <redemption_code>1A5069E266AED435</redemption_code> <id type="integer">2008976331180115114</id> <product_code>gift_card</product_code> <unit_amount_in_cents type="integer">1000</unit_amount_in_cents> <currency>USD</currency> <gifter_account_code>84395</gifter_account_code> <recipient_account_code nil="true"></recipient_account_code> <invoice_number type="integer">1105</invoice_number> <delivery> <method>email</method> <email_address>john@example.com</email_address> <deliver_at nil="true"></deliver_at> <first_name>John</first_name> <last_name>Smith</last_name> <address> <address1 nil="true"></address1> <address2 nil="true"></address2> <city nil="true"></city> <state nil="true"></state> <zip nil="true"></zip> <country nil="true"></country> <phone nil="true"></phone> </address> <gifter_name>Sally</gifter_name> <personal_message> Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message> </delivery> <created_at type="datetime">2016-08-03T20:37:21Z</created_at> <updated_at type="datetime">2016-08-03T22:00:00Z</updated_at> <delivered_at type="datetime">2016-08-03T20:37:22Z</delivered_at> <redeemed_at type="datetime" nil="true"></redeemed_at> <canceled_at type="datetime" nil="true"></canceled_at> </gift_card> </regenerated_gift_card_notification> ``` ### Redeemed Gift Card A `redeemed_gift_card_notification` is sent when a gift card is redeemed by a recipient. ``` <?xml version="1.0" encoding="UTF-8"?> <redeemed_gift_card_notification> <gift_card> <redemption_code>AB54200960E33C93</redemption_code> <id type="integer">2005384587788419212</id> <product_code>gift_card</product_code> <unit_amount_in_cents type="integer">1000</unit_amount_in_cents> <currency>USD</currency> <gifter_account_code>3543456</gifter_account_code> <recipient_account_code>3547000</recipient_account_code> <invoice_number type="integer">1099</invoice_number> <delivery> <method>email</method> <email_address nil="true"></email_address> <deliver_at nil="true"></deliver_at> <first_name>John</first_name> <last_name>Smith</last_name> <address> <address1 nil="true"></address1> <address2 nil="true"></address2> <city nil="true"></city> <state nil="true"></state> <zip nil="true"></zip> <country nil="true"></country> <phone nil="true"></phone> </address> <gifter_name>Sally</gifter_name> <personal_message> Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message> </delivery> <created_at type="datetime">2016-07-29T21:41:11Z</created_at> <updated_at type="datetime">2016-07-29T21:50:38Z</updated_at> <delivered_at type="datetime">2016-07-29T21:50:38Z</delivered_at> <redeemed_at type="datetime">2016-07-29T21:50:38Z</redeemed_at> <canceled_at type="datetime" nil="true"></canceled_at> </gift_card> </redeemed_gift_card_notification> ``` ### Updated Balance Gift Card An `updated_balance_gift_card_notification` is sent when the gift card's balance decreases from use on an invoice or increases if credit is returned to the account from a failed invoice. ``` <?xml version="1.0" encoding="UTF-8"?> <updated_balance_gift_card_notification> <gift_card> <redemption_code>AB54200960E33C93</redemption_code> <id type="integer">2005384587788419212</id> <product_code>gift_card</product_code> <unit_amount_in_cents type="integer">1000</unit_amount_in_cents> <currency>USD</currency> <gifter_account_code>3543456</gifter_account_code> <recipient_account_code>3547000</recipient_account_code> <invoice_number type="integer">1099</invoice_number> <delivery> <method>email</method> <email_address nil="true"></email_address> <deliver_at nil="true"></deliver_at> <first_name>John</first_name> <last_name>Smith</last_name> <address> <address1 nil="true"></address1> <address2 nil="true"></address2> <city nil="true"></city> <state nil="true"></state> <zip nil="true"></zip> <country nil="true"></country> <phone nil="true"></phone> </address> <gifter_name>Sally</gifter_name> <personal_message> Hi John, Happy Birthday! I hope you have a great day! Love, Sally</personal_message> </delivery> <created_at type="datetime">2016-07-29T21:41:11Z</created_at> <updated_at type="datetime">2016-08-02T23:50:38Z</updated_at> <delivered_at type="datetime">2016-07-29T21:50:38Z</delivered_at> <redeemed_at type="datetime">2016-07-29T21:50:38Z</redeemed_at> <canceled_at type="datetime" nil="true"></canceled_at> <balance_in_cents type="integer">200</balance_in_cents> </gift_card> </updated_balance_gift_card_notification> ``` [block:api-header] { "type": "basic", "title": "Invoice Notifications" } [/block] All invoice notifications contain the account and transaction as part of the XML body. The root attribute determines the notification type. In most applications, you can ignore these notifications. Recurly will send you the proper invoice notifications when your application creates or updates an invoice state. ### New Invoice If a new invoice is generated, a `new_invoice_notification` is sent. ```xml <?xml version="1.0" encoding="UTF-8"?> <new_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>open</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1000</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:21:44Z</date> <closed_at type="datetime" nil="true"></closed_at> </invoice> </new_invoice_notification> ``` ### New Invoice (Manual) If a new manual invoice is generated, a `new_invoice_notification` is sent. For partially paid manual invoices, a `new_invoice_notification` will not be sent after each partial payment. ```xml <?xml version="1.0" encoding="UTF-8"?> <new_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>open</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1000</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:21:44Z</date> <closed_at type="datetime" nil="true"></closed_at> <net_terms type="integer">0</net_terms> <collection_method>manual</collection_method> </invoice> </new_invoice_notification> ``` ### Processing Invoice (Automatic - Only for ACH payments) If an invoice is paid with ACH, the invoice will move into a processing state. When the invoice state changes to processing, a `processing_invoice_notification` is sent. ```xml <?xml version="1.0" encoding="UTF-8"?> <processing_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>processing</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1000</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:21:44Z</date> <closed_at type="datetime" nil="true"></closed_at> <net_terms type="integer">0</net_terms> <collection_method>automatic</collection_method> </invoice> </processing_invoice_notification> ``` ### Closed Invoice If an invoice is closed, a `closed_invoice_notification` is sent. A closed invoice can result from either a failed to collect invoice or fully paid invoice. ```xml <?xml version="1.0" encoding="UTF-8"?> <closed_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>collected</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1100</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:20:29Z</date> <closed_at type="datetime">2014-01-01T20:24:02Z</closed_at> </invoice> </closed_invoice_notification> ``` ### Closed Invoice (Manual) If a manual invoice is closed, a `closed_invoice_notification` is sent. A closed invoice can result from either a failed to collect invoice or fully paid invoice. A manual ``` <?xml version="1.0" encoding="UTF-8"?> <closed_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>collected</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1100</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:20:29Z</date> <closed_at type="datetime">2014-01-01T20:24:02Z</closed_at> <net_terms type="integer">0</net_terms> <collection_method>manual</collection_method> </invoice> </closed_invoice_notification> ``` ### Past Due Invoice If an invoice is past due, a `past_due_invoice_notification` is sent. An invoice that is past due can result from a failure to collect by the due date. ``` <?xml version="1.0" encoding="UTF-8"?> <past_due_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>past_due</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1100</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:20:29Z</date> <closed_at type="datetime">2014-01-01T20:24:02Z</closed_at> </invoice> </past_due_invoice_notification> ``` ### Past Due Invoice (Manual) If a manual invoice is past due, a `past_due_invoice_notification` is sent. An invoice that is past due can result from a failure to collect by the due date. ``` <?xml version="1.0" encoding="UTF-8"?> <past_due_invoice_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verana</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <invoice> <uuid>ffc64d71d4b5404e93f13aac9c63b007</uuid> <subscription_id nil="true"></subscription_id> <state>past_due</state> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">1000</invoice_number> <po_number></po_number> <vat_number></vat_number> <total_in_cents type="integer">1100</total_in_cents> <currency>USD</currency> <date type="datetime">2014-01-01T20:20:29Z</date> <closed_at type="datetime">2014-01-01T20:24:02Z</closed_at> <net_terms type="integer">0</net_terms> <collection_method>manual</collection_method> </invoice> </past_due_invoice_notification> ``` [block:api-header] { "type": "basic", "title": "Payment Notifications" } [/block] All payment notifications contain the account and transaction as part of the XML body. The root attribute determines the notification type. In most applications, you can ignore these notifications. Recurly will send you the proper subscription notifications when your application needs to modify a user's account status. In the near future, Recurly will let you query for a user's transaction history using the API. ### Scheduled Payment (Only for ACH payments) A `scheduled_payment_notification` is sent when Recurly initiates an ACH payment from a customer entering payment or the renewal procces. ``` <?xml version="1.0" encoding="UTF-8"?> <scheduled_payment_notification> <account> <account_code>1</account_code> <username nil="true">verena</username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true">Company, Inc.</company_name> </account> <transaction> <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id> <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>purchase</action> <date type="datetime">2009-11-22T13:10:38Z</date> <amount_in_cents type="integer">1000</amount_in_cents> <status>scheduled</status> <message>Bogus Gateway: Forced success</message> <reference></reference> <source>subscription</source> <cvv_result code=""></cvv_result> <avs_result code=""></avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">true</voidable> <refundable type="boolean">true</refundable> </transaction> </scheduled_payment_notification> ``` ### Processing Payment (Only for ACH payments) A `processing_payment_notification` is sent when an ACH payment moves from the scheduled state to the processing state. An ACH payment enters a processing state when it has been submitted to the ACH bank network by Check Gateway. ``` <?xml version="1.0" encoding="UTF-8"?> <processing_payment_notification> <account> <account_code>1</account_code> <username nil="true">verena</username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true">Company, Inc.</company_name> </account> <transaction> <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id> <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id> <invoice_number_prefix></invoice_number_prefix> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>purchase</action> <date type="datetime">2009-11-22T13:10:38Z</date> <amount_in_cents type="integer">1000</amount_in_cents> <status>processing</status> <message>Bogus Gateway: Forced success</message> <reference></reference> <source>subscription</source> <cvv_result code=""></cvv_result> <avs_result code=""></avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">true</voidable> <refundable type="boolean">true</refundable> </transaction> </processing_payment_notification> ``` ### Successful Payment A `successful_payment_notification` is sent when a payment is successfully captured. ``` <?xml version="1.0" encoding="UTF-8"?> <successful_payment_notification> <account> <account_code>1</account_code> <username nil="true">verena</username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true">Company, Inc.</company_name> </account> <transaction> <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id> <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>purchase</action> <date type="datetime">2009-11-22T13:10:38Z</date> <amount_in_cents type="integer">1000</amount_in_cents> <status>success</status> <message>Bogus Gateway: Forced success</message> <reference></reference> <source>subscription</source> <cvv_result code=""></cvv_result> <avs_result code=""></avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">true</voidable> <refundable type="boolean">true</refundable> </transaction> </successful_payment_notification> ``` ### Manual Payment A `successful_payment_notification` is also sent when a manual offline payment is recorded. ``` <?xml version="1.0" encoding="UTF-8"?> <successful_payment_notification> <account> <account_code>1</account_code> <username nil="true">verena</username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true">Company, Inc.</company_name> </account> <transaction> <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id> <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>purchase</action> <date type="datetime">2009-11-22T13:10:38Z</date> <amount_in_cents type="integer">1000</amount_in_cents> <status>success</status> <message>Bogus Gateway: Forced success</message> <reference></reference> <source>subscription</source> <cvv_result code=""></cvv_result> <avs_result code=""></avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">true</voidable> <refundable type="boolean">true</refundable> <manually_entered type="boolean">true</manually_entered> <payment_method>credit_card</payment_method> </transaction> </successful_payment_notification> ``` ### Failed Payment A `failed_payment_notification` is sent when a payment attempt is declined by the payment gateway. ``` <?xml version="1.0" encoding="UTF-8"?> <failed_payment_notification> <account> <account_code>1</account_code> <username nil="true">verena</username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true">Company, Inc.</company_name> </account> <transaction> <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id> <invoice_id>8fjk3sd7j90s0789dsf099798jkliy65</invoice_id> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>purchase</action> <date type="datetime">2009-11-22T13:10:38Z</date> <gateway>cybersource</gateway> <amount_in_cents type="integer">1000</amount_in_cents> <status>Declined</status> <message>This transaction has been declined</message> <gateway_error_codes nil="true"></gateway_error_codes> <failure_type>Declined by the gateway</failure_type> <reference></reference> <source>subscription</source> <cvv_result code=""></cvv_result> <avs_result code=""></avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">false</voidable> <refundable type="boolean">false</refundable> </transaction> </failed_payment_notification> ``` ### Successful Refund If you refund an amount through the API or admin interface, a `successful_refund_notification` is sent. Failed refund attempts do not generate a notification. ``` <?xml version="1.0" encoding="UTF-8"?> <successful_refund_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <transaction> <id>2c7a2e30547e49869efd4e8a44b2be34</id> <invoice_id>ffc64d71d4b5404e93f13aac9c63b007</invoice_id> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>credit</action> <date type="datetime">2010-10-06T20:37:55Z</date> <amount_in_cents type="integer">235</amount_in_cents> <status>success</status> <message>Bogus Gateway: Forced success</message> <reference></reference> <source>subscription</source> <cvv_result code=""></cvv_result> <avs_result code=""></avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">true</voidable> <refundable type="boolean">false</refundable> </transaction> </successful_refund_notification> ``` ### Void Payment If you void a successfully captured payment before it settles, a `void_payment_notification` is sent. Payments can only be voided before the funds settle into your merchant account. ``` <?xml version="1.0" encoding="UTF-8"?> <void_payment_notification> <account> <account_code>1</account_code> <username nil="true"></username> <email>verena@example.com</email> <first_name>Verena</first_name> <last_name>Example</last_name> <company_name nil="true"></company_name> </account> <transaction> <id>4997ace0f57341adb3e857f9f7d15de8</id> <invoice_id>ffc64d71d4b5404e93f13aac9c63b007</invoice_id> <invoice_number type="integer">2059</invoice_number> <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id> <action>purchase</action> <date type="datetime">2010-10-05T23:00:50Z</date> <amount_in_cents type="integer">235</amount_in_cents> <status>void</status> <message>Test Gateway: Successful test transaction</message> <reference></reference> <source>subscription</source> <cvv_result code="M">Match</cvv_result> <avs_result code="D">Street address and postal code match.</avs_result> <avs_result_street></avs_result_street> <avs_result_postal></avs_result_postal> <test type="boolean">true</test> <voidable type="boolean">false</voidable> <refundable type="boolean">false</refundable> </transaction> </void_payment_notification> ``` [block:api-header] { "type": "basic", "title": "Dunning Event Notifications" } [/block] A `new_dunning_event_notification` is sent when an invoice enters and remains in dunning. This notification will be sent according to your dunning configuration in Recurly. Please note that these are delivered regardless of whether or not you use Recurly to send customer communication. Recurly merchants use this push notification to customize customer email for each dunning step or to reach customers using different communication channels (email, SMS, Slack channel etc) or to reduce customer churn by offering discounts proactively. ``` <?xml version="1.0" encoding="UTF-8"?> <new_dunning_event_notification> <account> <account_code>09f299492d21</account_code> <username nil="true"></username> <email>joseph.smith@gmail.com</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> ```