• Content

Webhooks

Webhooks can be used as alerts to keep your systems and partner applications in sync with actions inside Recurly. Webhooks themselves should not be used as actionable items - please see Best Practices below for more information on working with webhooks.

Recurly can send webhooks to any publicly accessible server. When an event in Recurly triggers a webhook (e.g., an account is opened), Recurly will attempt to send this notification to the endpoint(s) you specify. You can specify up to 10 endpoints through the application. Webhook notifications related to various lifecycle events that occur within your Recurly instance will be sent to the configured endpoints for your site, so long as the endpoint is subscribed to them.

Recurly only considers a notification delivered if it receives a timely response with a successful status code. In other words:

  • Your endpoint must be reachable at ports 80 (HTTP) or 443 (HTTPS) (Recurly does not support other ports).
  • Your endpoint must respond within 5 seconds
  • Your endpoint must respond with a 2XX status code (e.g. 200, 201, 204, etc). Recurly does not follow redirects or consider them successful responses.

If you need to generate a test URL you can do this using RequestBin or Mockbin.

Sandbox vs Production

Recurly sends sandbox and production webhooks from different services, so that the high level of testing done in sandbox mode does not impact production data.

In times of high sandbox testing volume, sandbox webhook deliverability may be delayed by up to 48 hours.

Recurly may auto-pause sandbox webhook endpoints that consistently return a high number of deliverability errors in a short window of time.

Best Practices

Webhooks are not actionable on their own and should not be used for critical functions like provisioning accounts. The API response from an original action (i.e. signup, one time purchase) can be used to provision the account and store the state/details behind the action locally. The state/details of a user should be maintained in your internal database, and assumed unchanged unless a change of state is indicated with a webhook. Use the receipt of a webhook to trigger an API query to validate the push notification details against the current API data.

Recurly webhooks may be retried or sent multiple times if the delivery status is considered failed. Please make sure your endpoint can receive the same notification multiple times and in the wrong order.

For example, an account can close and we will send a notification for this. If delivery fails, the notification will be sent again later. In the meantime, the account could reopen (triggering another push notification). If your endpoint begins working again, it may receive the closed account notification after the account was reopened). Make sure that if your application takes action on closed accounts, that it verifies the account is still closed by issuing an API request.

Configuration & Security

If Recurly fails to deliver a webhook, it will retry it (see Automatic Retries, below).

Webhooks support HTTP Basic Authentication to verify the request came from Recurly’s servers.

Please see our IP Whitelisting documentation for the current list of Recurly IPs.

You may refuse other IP addresses from your endpoint configuration.

Recurly does not advocate the use of specific web servers or plugins, such as Apache with ModSecurity. However, if you are using Apache with ModSecurity, you may need to disable rule #990011 in mod_security in order for webhooks to be unblocked.

Webhook Details

Notifications are never combined. For example, if a user signs up for a new subscription and this triggers a payment, you will receive two separate notifications (one for the subscription and one for the payment).

All webhooks notifications are stored in our systems for 15 days and are available through the application console. The application console also provides details about failure reasons. The timestamp for webhooks is in UTC, although we translate this to your site’s configured timezone when viewing notification status in the application.

Please note that if you delete an endpoint, notifications sent to that endpoint over the last 15 days will no longer appear in the list of notifications.

Automatic Retries

If Recurly receives an error in response to a webhook sent to your webhook URL, the notification will be retried. After ten failed attempts, Recurly will stop trying to send the failed notification. Notifications are sent in the order in which they were created. The interval between retries is approximately 10 + x* 2^(x+5) seconds, where x is the current attempt number. This means that the interval between the first few retries will be very short, but will extend exponentially in length as the retry number increases.

Cross Site Request Forgery (CSRF) for Rails applications

Many Rails applications enable forgery protection protect_from_forgery. You must disable protect_from_forgery for the action you setup to listen for changes from Recurly. In your controller, use the following line (assumes your listening action is named recurly_notification):

protect_from_forgery :except => :recurly_notification

Webhook Payloads: JSON vs. XML

Webhook payloads are available in JSON or XML. Each webhook endpoint can be configured to receive one payload type or the other. The JSON webhooks provide light weight payloads containing information about the type of event (e.g. update, create, etc.), context regarding the object (e.g. Account, Subscription) and object identifiers that can be used to obtain the most up to date information via Recurly API. Recurly highly recommends usage of the JSON webhooks as they are our most modern offering and they encourage our best practice approach.

Signature Verification

For all JSON payloads, Recurly signs the notification and includes this signature in a recurly-signature request header. Signature verification provides additional proof that Recurly sent the notification and it is unchanged. Verification can be performed manually or with the help of our client libraries.

Each webhooks endpoint is assigned a unique secret key. The key can be found on the Webhook Endpoints page. The matching key will be needed for each endpoint you wish to verify.

Using Client Library

Provide the recurly-signature header, the secret key, and the request body.

Ruby

Go

begin
  Recurly::Webhooks.verify_signature(header,
                                     ENV['WEBHOOKS_KEY'],
                                     request.body)
rescue Recurly::Errors::SignatureVerificationError => e
  puts e.message
end
err := recurly.VerifyWebhookSignature(header, secret, body, recurly.DEFAULT_WEBHOOK_TOLERANCE)
if err != nil {
  fmt.Errorf("Verify Webhook Signature failed with: %s", err.Error())
}

Manual Check

The recurly-signature header takes the form of a Unix timestamp (in milliseconds) followed by one or more signatures.

recurly-signature:1659641851,a8c8524a0cdd99e36b55d9fdf6c8aed2c2315dfa1a36c4961f65986ee6cf6ae9,cafe677a2e6fa177d1a73cd9a18e47533de4b8923bbe17e2e1be290717ca29c1

The signatures are generated using a hash-based message authentication code (HMAC) with a SHA-256 hash function. Multiple signatures are present when a secret key is regenerated. The expiring key remains active for 24 hours.

Extract timestamp and signature(s)

Separating on comma, split the signature header into a list of elements. The head of the list is the timestamp; the remainder are signatures. Any other form should be considered invalid.

Prepare message for signing

Concatenate:

  • Timestamp from signature header
  • The . character
  • Received request body

Compute expected signature

Using the endpoint secret as the key and the prior prepared message, compute the HMAC-SHA256 digest.

Compare expected against received signature(s)

Compare the expected signature against the signature(s) from the header. To mitigate timing attacks, use a constant-time string comparison. For the notification to be valid, exactly one should match.

Also consider comparing the timestamp from the header against the current time. Given latency and time drift between servers, some difference is expected and normal, but a large gap could indicate a replay attack.

Lifecycle Events

It is possible to configure / opt-in to only the specific notifications that you would like to receive, on an endpoint by endpoint basis. For example, if you have an endpoint that only needs to receive notifications about new accounts, but is not interested in updated accounts, you can configure that endpoint accordingly.

A full list of all notifications can be found below, along with both the JSON and XML versions of the payloads.

Account Notifications

New Account

Sent when a new account is created.

JSON

XML

{
  "id": "r3oplsj3zo7a",
  "object_type": "account",
  "site_id": "r23khg9b5kyb",
  "event_type": "created",
  "event_time": "2022-06-24T19:55:25Z"
  "account_code": "verena"
}
<?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>

Updated Account

Sent when an account is updated. Specifically attributes in the account information, not the billing information, shipping addresses, or account acquisition. See the Update Account API call for a list of attributes.

JSON

XML

{
  "id": "r3oplsj3zo7a",
  "object_type": "account",
  "site_id": "r23khg9b5kyb",
  "event_type": "updated",
  "event_time": "2022-06-24T19:55:25Z"
  "account_code": "verena"
}
<?xml version="1.0" encoding="UTF-8"?>
<updated_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>
</updated_account_notification>

Closed Account

Sent when an account is closed.

JSON

XML

{
  "id": "r3oplsj3zo7a",
  "object_type": "account",
  "site_id": "r23khg9b5kyb",
  "event_type": "closed",
  "event_time": "2022-06-24T19:55:25Z"
  "account_code": "verena"
}
<?xml version="1.0" encoding="UTF-8"?>
<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 with a credit card or updated with a credit card or token.

JSON

XML

{
  "id": "ra8etjg1z0pr",
  "object_type": "billing_info",
  "site_id": "qc326l1hl8k9",
  "event_type": "updated",
  "event_time": "2022-07-26T21:57:05Z",
  "account_code": "2cfc561c374@example.com"
}
<?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>

A new shipping address is created

JSON

XML

{
  "id": "ra8f7lksukbd",
  "object_type": "shipping_address",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-26T21:59:15Z",
  "account_code": "2597c5c5eb3@example.com"
}
<?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

JSON

XML

{
  "id": "ra8f7lksukbd",
  "object_type": "shipping_address",
  "site_id": "qc326l1hl8k9",
  "event_type": "updated",
  "event_time": "2022-07-26T21:59:16Z",
  "account_code": "2597c5c5eb3@example.com"
}
<?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

JSON

XML

{
  "id": "ra8f7lksukbd",
  "object_type": "shipping_address",
  "site_id": "qc326l1hl8k9",
  "event_type": "deleted",
  "event_time": "2022-07-26T21:59:16Z",
  "account_code": "2597c5c5eb3@example.com"
}
<?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>

Subscription Notifications

When using XML webhooks, 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
  • external_sku
  • tier_type

New Subscription

Sent when a new subscription is created.

JSON

XML

{
  "id": "ra8foq26o2dt",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-26T22:01:56Z",
  "uuid": "63ab531e1d5b1d47eaf1ef44eeb853c3"
}
<?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>
        <external_sku>pre-123</external_sku>
        <add_on_type>fixed</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id nil="true"></measured_unit_id>
        <tier_type>flat</tier_type>
      </subscription_add_on>
      <subscription_add_on>
        <add_on_code>email_blasts</add_on_code>
        <name>Email Blasts</name>
        <quantity type="integer">1</quantity>
        <external_sku>email-123</external_sku>
        <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>
        <tier_type>flat</tier_type>
      </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>
        <tier_type>flat</tier_type>
      </subscription_add_on>
      <subscription_add_on>
        <add_on_code>translation_assistance</add_on_code>
        <name>Translation Assistance</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents nil="true"></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>
        <tier_type>tiered</tier_type>
      </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

Sent when a subscription is upgraded, downgraded, or the renewal date is updated. 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. For a notification of an upcoming change, see Scheduled Subscription Update.

JSON

XML

{
  "id": "r77d8unmt1tt",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "updated",
  "event_time": "2022-07-27T00:17:45Z",
  "uuid": "635c9e549909a5c509bfbb4f55b953da"
}
<?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>
  </subscription>
</updated_subscription_notification>

Canceled Subscription

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.

JSON

XML

{
  "id": "ra8foq26o2dt",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "canceled",
  "event_time": "2022-07-26T22:01:58Z",
  "uuid": "63ab531e1d5b1d47eaf1ef44eeb853c3"
}
<?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>
  </subscription>
</canceled_subscription_notification>

Expired Subscription

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.

JSON

XML

{
  "id": "radnhqhifyql",
  "object_type": "subscription",
  "site_id": "radmlv3z8vl6",
  "event_type": "expired",
  "event_time": "2022-07-27T15:39:17Z",
  "uuid": "63af16e00c35a96baaa9a147d984bb33"
}
<?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>
  </subscription>
</expired_subscription_notification>

Renewed Subscription

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.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewed",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?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>

  </subscription>
</renewed_subscription_notification>

Reactivated Subscription

Sent when a subscription is reactivated after having been canceled.

JSON

XML

{
  "id": "radoktyw8ge4",
  "object_type": "subscription",
  "site_id": "radmlv3z8vl6",
  "event_type": "reactivated",
  "event_time": "2022-07-27T15:41:18Z",
  "uuid": "63af1c72afe86fec35530a4a8aa70f71"
}
<?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>
  </subscription>
</reactivated_account_notification>

Paused Subscription

Sent when a subscription moves from state of active to paused, meaning that the subscription is now paused.

JSON

XML

{
  "id": "radqtk7scy9u",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "paused",
  "event_time": "2022-07-27T16:10:32Z",
  "uuid": "63af27f8b037a8052b530b4bae858dc1"
}
<?xml version="1.0" encoding="UTF-8"?>
<subscription_paused_notification>
  <account>
    <account_code>1</account_code>
    <username>test-user</username>
    <email>test+2605@recurly.com</email>
    <first_name>test</first_name>
    <last_name>test-last</last_name>
    <company_name>Recurly, Inc.</company_name>
    <phone>555-1212</phone>
  </account>
  <subscription>
    <plan>
      <plan_code>daily_plan</plan_code>
      <name>daily_plan</name>
    </plan>
    <uuid>437a818b9dba81065e444448de931842</uuid>
    <state>paused</state>
    <quantity type="integer">10</quantity>
    <total_amount_in_cents type="integer">10000</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2018-03-09T17:01:59Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-03-10T22:12:08Z</current_period_started_at>
    <current_period_ends_at type="datetime">2018-03-11T22:12:08Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime">2018-03-10T22:12:08Z</paused_at>
    <resume_at type="datetime">2018-03-20T22:12:08Z</resume_at>
    <remaining_pause_cycles type="integer">9</remaining_pause_cycles>
  </subscription>
</subscription_paused_notification>

Resumed Subscription

Sent when a subscription moves from state of paused to active, meaning that the subscription is successfully renewed and a new billing cycle has started.

JSON

XML

{
  "id": "radqtk7scy9u",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "resumed",
  "event_time": "2022-07-27T16:11:40Z",
  "uuid": "63af27f8b037a8052b530b4bae858dc1"
}
<?xml version="1.0" encoding="UTF-8"?>
<subscription_resumed_notification>
  <account>
    <account_code>1</account_code>
    <username>test-user</username>
    <email>test+2605@recurly.com</email>
    <first_name>test</first_name>
    <last_name>test-last</last_name>
    <company_name>Recurly, Inc.</company_name>
    <phone>555-1212</phone>
  </account>
  <subscription>
    <plan>
      <plan_code>daily_plan</plan_code>
      <name>daily_plan</name>
    </plan>
    <uuid>437a818b9dba81065e444448de931842</uuid>
    <state>active</state>
    <quantity type="integer">10</quantity>
    <total_amount_in_cents type="integer">10000</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2018-03-09T17:01:59Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-03-20T17:50:27Z</current_period_started_at>
    <current_period_ends_at type="datetime">2018-03-21T17:50:27Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"></remaining_pause_cycles>
  </subscription>
</subscription_resumed_notification>

Scheduled Subscription Pause

Sent when an active and eligible subscription is scheduled to pause using the API or through the Admin UI. The paused_at, resumed_at and remaining_pause_cycles fields will now contain information on when the subscription will become paused, when it will resume, and how many pause cycles are left respectively.

JSON

XML

{
  "id": "ra8ggigeveo0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "pause.scheduled",
  "event_time": "2022-07-27T00:22:26Z",
  "uuid": "63ab5718be89b4f20a27714a8395ec2f"
}
<?xml version="1.0" encoding="UTF-8"?>
<scheduled_subscription_pause_notification>
  <account>
    <account_code>1</account_code>
    <username>test-user</username>
    <email>test+2605@recurly.com</email>
    <first_name>test</first_name>
    <last_name>test-last</last_name>
    <company_name>Recurly, Inc.</company_name>
    <phone>555-1212</phone>
  </account>
  <subscription>
    <plan>
      <plan_code>4ec9adacbc37be072f0d6e2d1affc538</plan_code>
      <name>Aut Fugiat Officia 6eae19a51 plan</name>
    </plan>
    <uuid>437b9def1c442e659f90f4416086dd66</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">709</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2018-03-09T22:12:36Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-03-09T22:12:36Z</current_period_started_at>
    <current_period_ends_at type="datetime">2019-03-09T22:12:36Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime">2019-03-09T22:12:36Z</paused_at>
    <resume_at type="datetime">2024-03-09T22:12:36Z</resume_at>
    <remaining_pause_cycles type="integer">5</remaining_pause_cycles>
  </subscription>
</scheduled_subscription_pause_notification>

Scheduled Subscription Update

Sent when a subscription change is scheduled to take effect at a future date (e.g. renewal). For a notification when update is applied, see Updated Subscription.

JSON

XML

{
  "id": "radqtk7scy9u",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "pending_change.scheduled",
  "event_time": "2022-07-27T16:12:59Z",
  "uuid": "63af27f8b037a8052b530b4bae858dc1"
}
<?xml version="1.0" encoding="UTF-8"?>
<scheduled_subscription_update_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>
  </subscription>
</scheduled_subscription_update_notification>

Subscription Paused Modified

Sent when a subscription’s pause duration is modified. The resume_at and remaining_pause_cycles fields will change to reflect the new date at which the subscription will resume and how many pause cycles are left.

JSON

XML

{
  "id": "ra8ggigeveo0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "pause.modified",
  "event_time": "2022-07-27T00:22:50Z",
  "uuid": "63ab5718be89b4f20a27714a8395ec2f"
}
<?xml version="1.0" encoding="UTF-8"?>
<subscription_pause_modified_notification>
  <account>
    <account_code>1</account_code>
    <username>test-user</username>
    <email>test+2605@recurly.com</email>
    <first_name>test</first_name>
    <last_name>test-last</last_name>
    <company_name>Recurly, Inc.</company_name>
    <phone>555-1212</phone>
  </account>
  <subscription>
    <plan>
      <plan_code>4ec9adacbc37be072f0d6e2d1affc538</plan_code>
      <name>Aut Fugiat Officia 6eae19a51 plan</name>
    </plan>
    <uuid>437a818b9dba81065e444448de931842</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">709</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2018-03-09T17:01:59Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-03-09T13:33:09Z</current_period_started_at>
    <current_period_ends_at type="datetime">2018-03-09T13:38:22Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime">2018-03-09T13:38:22Z</paused_at>
    <resume_at type="datetime">2023-03-09T13:38:22Z</resume_at>
    <remaining_pause_cycles type="integer">5</remaining_pause_cycles>
  </subscription>
</subscription_pause_modified_notification>

Paused Subscription Renewal

Sent when a subscription’s renewal/billing cycle is skipped because it is paused. The remaining_pause_cycles value will decrement by 1 after each pause cycle.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.skipped",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<paused_subscription_renewal_notification>
  <account>
    <account_code>1</account_code>
    <username>test-user</username>
    <email>test+2605@recurly.com</email>
    <first_name>test</first_name>
    <last_name>test-last</last_name>
    <company_name>Recurly, Inc.</company_name>
    <phone>555-1212</phone>
  </account>
  <subscription>
    <plan>
      <plan_code>daily_plan</plan_code>
      <name>daily_plan</name>
    </plan>
    <uuid>437a818b9dba81065e444448de931842</uuid>
    <state>paused</state>
    <quantity type="integer">10</quantity>
    <total_amount_in_cents type="integer">10000</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2018-03-09T17:01:59Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-03-18T17:50:27Z</current_period_started_at>
    <current_period_ends_at type="datetime">2018-03-19T17:50:27Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime">2018-03-10T22:12:08Z</paused_at>
    <resume_at type="datetime">2018-03-20T17:50:27Z</resume_at>
    <remaining_pause_cycles type="integer">1</remaining_pause_cycles>
  </subscription>
</paused_subscription_renewal_notification>

Subscription Pause Canceled

Sent whenever a scheduled pause is canceled. The paused_at, resume_at and remaining_pause_cycles will now be nil as the pause has been canceled.

JSON

XML

{
  "id": "ra8ggigeveo0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "pause.canceled",
  "event_time": "2022-07-27T00:22:56Z",
  "uuid": "63ab5718be89b4f20a27714a8395ec2f"
}
<?xml version="1.0" encoding="UTF-8"?>
<subscription_pause_canceled_notification>
  <account>
    <account_code>1</account_code>
    <username>test-user</username>
    <email>test+2605@recurly.com</email>
    <first_name>test</first_name>
    <last_name>test-last</last_name>
    <company_name>Recurly, Inc.</company_name>
    <phone>555-1212</phone>
  </account>
  <subscription>
    <plan>
      <plan_code>4ec9adacbc37be072f0d6e2d1affc538</plan_code>
      <name>Aut Fugiat Officia 6eae19a51 plan</name>
    </plan>
    <uuid>437b9def1c442e659f90f4416086dd66</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">2000</total_amount_in_cents>
    <subscription_add_ons type="array"/>
    <activated_at type="datetime">2018-03-09T22:12:36Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-03-09T22:12:36Z</current_period_started_at>
    <current_period_ends_at type="datetime">2019-03-09T22:12:36Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"></remaining_pause_cycles>
  </subscription>
</subscription_pause_canceled_notification>

Low Balance Gift Card

Sent when a gift card balance is low; the subscription is sent as payload.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "low_balance",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<low_balance_gift_card_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>
  </subscription>
</low_balance_gift_card_notification>

Prerenewal Notifications

Webhooks notifications that are triggered before specific subscription events. The number of days in advance the webhook is triggered can be configured in the webhooks configuration screen.

Subscription Prerenewal

Sent one day in advance of when a subscription is set to either begin a new billing period or expire.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.scheduled",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>prerenewal</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Annual Subscription Reminder

Sent to a customer 30 (or the configured number of days prior) days before every 12 months their subscription is active.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.annual_subscription_reminder",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>annual_subscription_reminder</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Subscription Bill Date Reminder

Sent to a customer 7 (or the configured number of days prior) days before their upcoming bill date.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.bill_date_reminder",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>bill_date_reminder</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Subscription Credit Card Expired

Sent to a customer with an expired credit card, 10 (or the configured number of days prior) days prior to their next bill date.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.cc_will_expire",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>cc_will_expire</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Subscription Mastercard Subscription Will Renew

Sent to customers paying with Mastercard, 7 (or the configured number of days prior) days prior to their subscription bill date.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.mastercard_subscription_will_renew",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>mastercard_subscription_will_renew</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Subscription Ramp Price Will Change

For subscriptions configured with a ramp pricing model. Sent to a customer 10 (or the configured number of days prior) days before their subscription’s price change goes into effect.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.ramp_price_will_change",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>ramp_price_will_change</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

SEPA Subscription Will Renew

Sent to customers with a SEPA payment method, 14 (or the configured number of days prior) days prior to their next bill date.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.sepa_subscription_will_renew",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>sepa_subscription_will_renew</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Subscription Trial Expiring

Sent 3 (or the configured number of days prior) days prior to the end of a customer’s trial as a reminder that their trial will be converting to a full-price subscription. This is required by law in many regions.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.subscription_trial_expiring",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>subscription_trial_expiring</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Subscription Term Renewal Reminder

Sent to a customer 30 (or the configured number of days prior) days before their subscription term renews.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "subscription",
  "site_id": "qc326l1hl8k9",
  "event_type": "renewal.term_renewal_reminder",
  "event_time": "2022-07-27T15:43:04Z",
  "uuid": "612bcf671a227b272b753a487fb6576a"
}
<?xml version="1.0" encoding="UTF-8"?>
<prerenewal_notification>
  <notification_type>term_renewal_reminder</notification_type>
  <account>
    <account_code>account-asdf</account_code>
    <username>Buddha</username>
    <email>buddha@buddha.com</email>
    <first_name>Buddha</first_name>
    <last_name>Buddha</last_name>
    <company_name nil="true"/>
    <phone nil="true"/>
  </account>
  <subscription>
    <plan>
      <plan_code>dueygolf-daily</plan_code>
      <name>dueygolf-daily</name>
    </plan>
    <uuid>59251f6479964de0f563ee4db383f73b</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">0</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>daily-usage</add_on_code>
        <name>daily-usage</name>
        <quantity type="integer">1</quantity>
        <add_on_source>plan_add_on</add_on_source>
        <unit_amount_in_cents nil="true"/>
        <unit_amount_in_decimal_cents type="float">0.25</unit_amount_in_decimal_cents>
        <add_on_type>usage</add_on_type>
        <usage_percentage nil="true"/>
        <measured_unit_id type="integer">2991694770025207104</measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2021-02-18T18:08:23Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2021-02-18T18:08:23Z</current_period_started_at>
    <current_period_ends_at type="datetime">2021-02-19T18:08:23Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
    <paused_at type="datetime" nil="true"></paused_at>
    <resume_at type="datetime" nil="true"></resume_at>
    <remaining_pause_cycles nil="true"/>
  </subscription>
</prerenewal_notification>

Usage Notifications

New Usage

Sent when we create a usage record on your behalf in a refund or terminate scenario.

JSON

XML

{
  "id": "qlm81nq1drd0",
  "object_type": "usage",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-27T15:43:04Z",
  "subscription_uuid": "612bcf671a227b272b753a487fb6576a",
  "add_on_code": "basic-add-on"
}
<?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>

Gift Card Notifications

Purchased Gift Card

Sent when a gift card is purchased by a gifter.

JSON

XML

{
  "id": "3591723995699407683",
  "object_type": "gift_card",
  "site_id": "qc326l1hl8k9",
  "event_type": "purchased",
  "event_time": "2022-07-27T15:14:25Z"
}
<?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

Sent when you cancel a gift card from the Admin Console.

JSON

XML

{
  "id": "3591723995699407683",
  "object_type": "gift_card",
  "site_id": "qc326l1hl8k9",
  "event_type": "canceled",
  "event_time": "2022-07-27T15:15:25Z"
}
<?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

Sent when you edit a gift card’s delivery information from the Admin Console.

JSON

XML

{
  "id": "3591723995699407683",
  "object_type": "gift_card",
  "site_id": "qc326l1hl8k9",
  "event_type": "updated",
  "event_time": "2022-07-27T15:15:00Z"
}
<?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

Sent when you regenerate a gift card’s redemption code from the Admin Console.

JSON

XML

{
  "id": "3591723995699407683",
  "object_type": "gift_card",
  "site_id": "qc326l1hl8k9",
  "event_type": "regenerated",
  "event_time": "2022-07-27T15:14:53Z"
}
<?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

Sent when a gift card is redeemed by a recipient.

JSON

XML

{
  "id": "3591723995699407683",
  "object_type": "gift_card",
  "site_id": "qc326l1hl8k9",
  "event_type": "redeemed",
  "event_time": "2022-07-27T15:15:00Z"
}
<?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

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.

JSON

XML

{
  "id": "3591723995699407683",
  "object_type": "gift_card",
  "site_id": "qc326l1hl8k9",
  "event_type": "balance_updated",
  "event_time": "2022-07-27T15:15:00Z"
}
<?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>

Charge Invoice Notifications

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

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

Charge Invoice Schema

JSON

XML

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

Credit Invoice Notifications

Only sent once the Credit Invoices feature is enabled on your Recurly site. Recurly sites created after May 8, 2018 UTC (May 7, 2018 5pm PT) automatically have the Credit Invoices feature. <a href="https://docs.recurly.com/docs/credit-invoices-release">Learn more</a>

JSON XML Description
credit_invoice.created new_credit_invoice_notification Sent when a credit invoice is created. This could be a one-off custom credit, refund, subscription downgrade, refund at subscription termination, write-off, or gift card redemption.
credit_invoice.processing processing_credit_invoice_notification Sent when a refund credit invoice enters a processing state due to a processing bank account (ACH) refund. Since only the new_credit_invoice notification is sent when a refund invoice is created, you will not see the processing_credit_invoice notification when a refund credit invoice is created and immediately moves to processing due to a bank account refund. You will only see the processing_credit_invoice when a bank account refund is created against the refund credit invoice after the fact, like retrying the refund or refunding the credit balance to a transaction later on.
credit_invoice.closed closed_credit_invoice_notification Sent when a credit invoice’s balance decreases to zero. This can happen if the full balance was used as credit payments on charge invoices, the balance was refunded out to transactions, or if the balance was voided, creating a reduction credit payment.
credit_invoice.voided voided_credit_invoice_notification Sent when a credit invoice moves to a voided state due to the full balance being removed.
credit_invoice.reopened reopened_credit_invoice_notification Sent when a credit invoice is reopened from a closed state. A credit invoice is only reopened if it has a credit payment on a charge invoice that is later failed. When the charge invoice is failed, the credit payment is voided, resulting in the credit payment amount being added back to the credit invoice’s balance, which reopens the credit invoice.
credit_invoice.opened open_credit_invoice_notification Sent when a credit invoice is issued for the first time in an open state. In the case where a processing credit invoice results in a declined refund transaction, the invoice will move back to an open state and the notification will be sent again. Since processing is not a closed state, we send an opened notification and not a reopened one.
credit_invoice.updated updated_credit_invoice_notification Sent when a credit invoice is edited.

Credit Invoice Schema

JSON

XML

{
  "id": "ra94dgn9ul70",
  "object_type": "credit_invoice",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-27T00:20:19Z",
  "invoice_number": 1034
}
<?xml version="1.0" encoding="UTF-8"?>
<new_credit_invoice_notification>
  <account>
    <account_code>1234</account_code>
    <username></username>
    <email></email>
    <first_name></first_name>
    <last_name></last_name>
    <company_name></company_name>
    <phone></phone>
  </account>
  <invoice>
    <uuid>42fb74de65e9395eb004614144a7b91f</uuid>
    <state>closed</state>
    <origin>write_off</origin>
    <invoice_number_prefix></invoice_number_prefix>
    <invoice_number type="integer">2404</invoice_number>
    <address>
      <address1>123 Main St.</address1>
      <address2></address2>
      <city>San Francisco</city>
      <state>CA</state>
      <zip>94110</zip>
      <country>US</country>
      <phone></phone>
    </address>
    <vat_number></vat_number>
    <currency>USD</currency>
    <balance_in_cents type="integer">0</balance_in_cents>
    <total_in_cents type="integer">-4882</total_in_cents>
    <tax_in_cents type="integer">-382</tax_in_cents>
    <subtotal_in_cents type="integer">-4500</subtotal_in_cents>
    <subtotal_before_discount_in_cents type="integer">-5000</subtotal_before_discount_in_cents>
    <discount_in_cents type="integer">-500</discount_in_cents>
    <subscription_ids type="array">
      <subscription_id>42fb74ba9efe4c6981c2064436a4e9cd</subscription_id>
    </subscription_ids>
    <customer_notes nil="true"></customer_notes>
    <created_at type="datetime">2018-02-13T00:56:22Z</created_at>
    <updated_at type="datetime">2018-02-13T00:56:22Z</updated_at>
    <closed_at type="datetime">2018-02-13T00:56:21Z</closed_at>
  </invoice>
</new_credit_invoice_notification>

Invoice Notifications

Invoice Notifications are deprecated once the Recurly site has the Credit Invoices feature enabled. Invoices issued before the feature was enabled will still send Invoice Notifications for additional states, like Closed Invoice. New invoices will send the Charge Invoice or Credit Invoice Notifications.

When using XML webhooks, 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

Sent when a new invoice is generated.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "created",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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)

Sent when a new manual invoice is generated. For partially paid manual invoices, additional notifications will not be sent after each partial payment.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "created",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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>

Pending Invoice (Automatic)

Sent when an invoice is generated which requires further action. When an ACH transaction fails, the state will return to pending from processing (if not past the due date).

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "pending",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?xml version="1.0" encoding="UTF-8"?>
<pending_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>pending</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>
</pending_invoice_notification>

Processing Invoice (Automatic - Only for ACH and PayPal eCheck payments)

Sent when the invoice state changes to processing. If an invoice is paid with ACH or a PayPal eCheck, the invoice will move into a processing state.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "processing",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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

Sent when an invoice is closed. A closed invoice can result from either a failed to collect invoice or fully paid invoice.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "closed",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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)

Sent when a manual invoice is closed. A closed invoice can result from either a failed to collect invoice or fully paid invoice.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "closed",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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

Sent when an invoice is past due. An invoice that is past due can result from a failure to collect by the due date.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "past_due",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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)

Sent when a manual invoice is past due. An invoice that is past due can result from a failure to collect by the due date.

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "invoice",
  "site_id": "radmlv3z8vl6",
  "event_type": "past_due",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?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>

Updated Invoice

Sent when a legacy invoice is edited.

Payment Notifications

When using XML webhooks, 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)

Sent when Recurly initiates an ACH payment from a customer entering payment or the renewal procces.

JSON

XML

{
  "id": "rafhdbbf41mc",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "scheduled",
  "event_time": "2022-07-27T21:43:53Z",
  "uuid": "63b068f7d409d4b4478dea4e6aba58ae"
}
<?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 and PayPal eCheck payments)

Sent when an ACH or PayPal eCheck 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. A PayPal eCheck payment moves to processing state when PayPal has confirmed that the transaction is “pending”.

JSON

XML

{
  "id": "rafhdbbf41mc",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "processing",
  "event_time": "2022-07-27T21:43:53Z",
  "uuid": "63b068f7d409d4b4478dea4e6aba58ae"
}
<?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

Sent when a payment is successfully captured.

JSON

XML

{
  "id": "rafhdbbf41mc",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "succeeded",
  "event_time": "2022-07-27T21:43:53Z",
  "uuid": "63b068f7d409d4b4478dea4e6aba58ae"
}
<?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

Sent when a manual offline payment is recorded.

JSON

XML

{
  "id": "rafhdbbf41mc",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "succeeded",
  "event_time": "2022-07-27T21:43:53Z",
  "uuid": "63b068f7d409d4b4478dea4e6aba58ae"
}
<?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

Sent when a payment attempt is declined by the payment gateway.

JSON

XML

{
  "id": "ra93x2i8g69t",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "failed",
  "event_time": "2022-07-27T00:17:45Z",
  "uuid": "63abcf806e29cbfb3ec9c84e658777be"
}
<?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

Sent when you refund an amount through the API or admin interface. Failed refund attempts do not generate a notification.

JSON

XML

{
  "id": "rafhoo0hbzff",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "refunded",
  "event_time": "2022-07-27T21:45:37Z",
  "uuid": "63b06a9098839d7b45a18443b6b395a0"
}
<?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

Sent when you void a successfully captured payment before it settles. Payments can only be voided before the funds settle into your merchant account.

JSON

XML

{
  "id": "radnhmaoszxc",
  "object_type": "payment",
  "site_id": "radmlv3z8vl6",
  "event_type": "voided",
  "event_time": "2022-07-27T15:39:17Z",
  "uuid": "63af16e06d659f949c37cc4f8cb2c5d0"
}
<?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>

Fraud Info Updated

If you are using Kount Direct and manually reviewing transactions for fraud, a fraud_info_updated_notification is sent. This notification is sent when we receive an ENS from Kount. More information on Kount ENS is available here. This notification is only used for XML webhooks.

<?xml version="1.0" encoding="UTF-8"?>
<fraud_info_updated_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>41e4e03e10be199252613d424290c5c6</subscription_id>
    <subscription_ids type="array">
      <subscription_id>41e4e03e10be199252613d424290c5c6</subscription_id>
    </subscription_ids>
    <action>purchase</action>
    <date type="datetime">2017-10-20T22:39:35Z</date>
    <gateway>authorize</gateway>
    <payment_method>credit_card</payment_method>
    <amount_in_cents type="integer">1000</amount_in_cents>
    <status>success</status>
    <message>This transaction has been approved.</message>
    <gateway_error_codes>1</gateway_error_codes>
    <failure_type nil="true"></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>
    <billing_phone nil="true"></billing_phone>
    <billing_postal></billing_postal>
    <billing_country></billing_country>
    <test type="boolean">true</test>
    <voidable type="boolean">true</voidable>
    <refundable type="boolean">true</refundable>
  </transaction>
</fraud_info_updated_notification>

Transaction Status Updated

Transactions will occasionally receive status updates from the payment gateway due to reasons such as gateway timeouts or asynchronous behaviors. For these cases, this notification will be sent to provide the updated transaction status.

JSON

XML

{
  "id": "rafhdbbf41mc",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "transaction_status_updated",
  "event_time": "2022-07-27T21:43:53Z",
  "uuid": "63b068f7d409d4b4478dea4e6aba58ae"
}
<?xml version="1.0" encoding="UTF-8"?>
<transaction_status_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>
  <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>
</transaction_status_updated_notification>

Transaction Authorized

Sent when you successfully authorize a payment. Payments that are successfully authorized must be captured upon to receive the settlement.

JSON

XML

{
  "id": "rafhdbbf41mc",
  "object_type": "payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "authorized",
  "event_time": "2022-07-27T21:43:53Z",
  "uuid": "63b068f7d409d4b4478dea4e6aba58ae"
}
<?xml version="1.0" encoding="UTF-8"?>
<transaction_authorized_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>
</transaction_authorized_notification>

Credit Payment Notifications

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

JSON XML Description
credit_payment.created new_credit_payment_notification Sent when a credit payment is created. A credit payment is created when an open credit balance is applied as payment in a billing event, a credit invoice’s balance is removed, or a refund credit invoice refunds a credit payment as a transaction.
credit_payment.voided voided_credit_payment_notification Sent when a credit payment is voided due to the charge invoice it is applied to being failed.

Credit Payment Schema

JSON

XML

{
  "id": "rafj5gtxla1h",
  "object_type": "credit_payment",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-27T21:53:49Z",
  "uuid": "63b0721217fbbd9bda968544aa920cf3"
}
<?xml version="1.0" encoding="UTF-8"?>
<new_credit_payment_notification>
  <account>
    <account_code>1234</account_code>
    <username></username>
    <email></email>
    <first_name></first_name>
    <last_name></last_name>
    <company_name></company_name>
    <phone></phone>
  </account>
  <credit_payment>
    <uuid>42fa2a56dfeca2ace39b0e4a9198f835</uuid>
    <action type="symbol">payment</action>
    <currency>USD</currency>
    <amount_in_cents type="integer">3579</amount_in_cents>
    <original_invoice_number type="integer">2389</original_invoice_number>
    <applied_to_invoice_number type="integer">2390</applied_to_invoice_number>
    <original_credit_payment_uuid nil="true"></original_credit_payment_uuid>
    <refund_transaction_uuid nil="true"></refund_transaction_uuid>
    <created_at type="datetime">2018-02-12T18:55:20Z</created_at>
    <updated_at type="datetime">2018-02-12T18:55:20Z</updated_at>
    <voided_at type="datetime" nil="true"></voided_at>
  </credit_payment>
</new_credit_payment_notification>

Dunning Event Notifications

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.

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

JSON

XML

{
  "id": "radnhqhipxkw",
  "object_type": "dunning_event",
  "site_id": "radmlv3z8vl6",
  "event_type": "created",
  "event_time": "2022-07-27T15:34:35Z",
  "invoice_number": 1000
}
<?xml version="1.0" encoding="UTF-8"?>
<new_dunning_event_notification>
  <account>
    <account_code>1234</account_code>
    <username></username>
    <email></email>
    <first_name></first_name>
    <last_name></last_name>
    <company_name></company_name>
    <phone></phone>
  </account>
  <invoice>
    <uuid>424a9d4a2174b4f39bc776426aa19c32</uuid>
    <state>past_due</state>
    <origin>renewal</origin>
    <invoice_number_prefix></invoice_number_prefix>
    <invoice_number type="integer">1813</invoice_number>
    <address>
      <address1></address1>
      <address2></address2>
      <city></city>
      <state></state>
      <zip></zip>
      <country></country>
      <phone></phone>
    </address>
    <vat_number></vat_number>
    <currency>USD</currency>
    <balance_in_cents type="integer">4000</balance_in_cents>
    <total_in_cents type="integer">4500</total_in_cents>
    <tax_in_cents type="integer">0</tax_in_cents>
    <subtotal_in_cents type="integer">4500</subtotal_in_cents>
    <subtotal_before_discount_in_cents type="integer">4500</subtotal_before_discount_in_cents>
    <discount_in_cents type="integer">0</discount_in_cents>
    <subscription_ids type="array">
      <subscription_id>4110792b3b01967d854f674b7282f542</subscription_id>
    </subscription_ids>
    <customer_notes>Thanks for your business!</customer_notes>
    <created_at type="datetime">2018-01-09T16:47:43Z</created_at>
    <updated_at type="datetime">2018-02-12T16:50:23Z</updated_at>
    <closed_at type="datetime" nil="true"></closed_at>
    <po_number></po_number>
    <terms_and_conditions></terms_and_conditions>
    <due_on type="datetime">2018-02-09T16:47:43Z</due_on>
    <dunning_events_count type="integer">2</dunning_events_count>
    <final_dunning_event type="boolean">false</final_dunning_event>
    <dunning_campaign_name>Dunning</dunning_campaign_name>
    <dunning_campaign_code>dunning</dunning_campaign_code>
    <dunning_campaign_id>4997ace0f57341adb3e857f9f7d15de8</dunning_campaign_id>
    <net_terms type="integer">30</net_terms>
    <collection_method>manual</collection_method>
  </invoice>
  <subscription>
    <plan>
      <plan_code>gold</plan_code>
      <name>Gold</name>
    </plan>
    <uuid>4110792b3b01967d854f674b7282f542</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">4500</total_amount_in_cents>
    <subscription_add_ons type="array">
      <subscription_add_on>
        <add_on_code>training_classes</add_on_code>
        <name>Training Classes</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents type="integer">700</unit_amount_in_cents>
        <add_on_type>fixed</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id nil="true"></measured_unit_id>
      </subscription_add_on>
      <subscription_add_on>
        <add_on_code>executive-brief</add_on_code>
        <name>Executive Brief</name>
        <quantity type="integer">1</quantity>
        <unit_amount_in_cents type="integer">2300</unit_amount_in_cents>
        <add_on_type>fixed</add_on_type>
        <usage_percentage nil="true"></usage_percentage>
        <measured_unit_id nil="true"></measured_unit_id>
      </subscription_add_on>
    </subscription_add_ons>
    <activated_at type="datetime">2017-11-09T16:47:30Z</activated_at>
    <canceled_at type="datetime" nil="true"></canceled_at>
    <expires_at type="datetime" nil="true"></expires_at>
    <current_period_started_at type="datetime">2018-02-09T16:47:30Z</current_period_started_at>
    <current_period_ends_at type="datetime">2018-03-09T16:47:30Z</current_period_ends_at>
    <trial_started_at type="datetime" nil="true"></trial_started_at>
    <trial_ends_at type="datetime" nil="true"></trial_ends_at>
  </subscription>
</new_dunning_event_notification>

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

JSON

XML

{
  "id": "r3oplsj3zo7a",
  "object_type": "account",
  "site_id": "r23khg9b5kyb",
  "event_type": "closed",
  "event_time": "2022-06-24T19:55:25Z"
  "account_code": "verena"
}
<?xml version="1.0" encoding="UTF-8"?>
<new_dunning_event_notification>
  <account>
    <account_code>09f299492d21</account_code>
    <username nil="true"></username>
    <email>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>

Item Notifications

New Item

Sent when an item is created.

JSON

XML

{
  "id": "ra8nn523yemt",
  "object_type": "item",
  "site_id": "qc326l1hl8k9",
  "event_type": "created",
  "event_time": "2022-07-26T22:46:31Z",
  "item_code": "f6e69ecf299"
}
<?xml version="1.0" encoding="UTF-8"?>
<new_item_notification>
  <item>
    <item_code>gray_socks</item_code>
    <name>Gray Socks</name>
    <description>Gray Socks</description>
    <external_sku>socks-12345</external_sku>
    <accounting_code>acc-12345</accounting_code>
    <revenue_schedule_type>evenly</revenue_schedule_type>
    <tax_exempt type="boolean">true</tax_exempt>
    <tax_code nil="nil"/>
    <pricing_type>fixed</pricing_type>
    <custom_fields type="array">
      <custom_field>
        <name>color</name>
        <value>gray</value>
      </custom_field>
    </custom_fields>
    <unit_amount_in_cents>
      <CAD type="integer">6000</CAD>
      <USD type="integer">1000</USD>
    </unit_amount_in_cents>
    <created_at type="datetime">2019-07-15T18:48:01Z</created_at>
    <updated_at type="datetime">2019-07-15T18:48:01Z</updated_at>
    <deleted_at nil="nil"/>
  </item>
</new_item_notification>

Updated Notification

Sent when an item is updated.

JSON

XML

{
  "id": "ra8nn523yemt",
  "object_type": "item",
  "site_id": "qc326l1hl8k9",
  "event_type": "updated",
  "event_time": "2022-07-26T22:46:32Z",
  "item_code": "f6e69ecf299"
}
<?xml version="1.0" encoding="UTF-8"?>
<updated_item_notification>
  <item>
    <item_code>gray_socks</item_code>
    <name>Gray Socks</name>
    <description>Gray Socks</description>
    <external_sku>socks-12345</external_sku>
    <accounting_code>acc-12345</accounting_code>
    <revenue_schedule_type>evenly</revenue_schedule_type>
    <tax_exempt type="boolean">true</tax_exempt>
    <tax_code nil="nil"/>
    <pricing_type>fixed</pricing_type>
    <custom_fields type="array">
      <custom_field>
        <name>color</name>
        <value>gray</value>
      </custom_field>
    </custom_fields>
    <unit_amount_in_cents>
      <CAD type="integer">6000</CAD>
      <USD type="integer">1000</USD>
    </unit_amount_in_cents>
    <created_at type="datetime">2019-07-15T18:48:01Z</created_at>
    <updated_at type="datetime">2019-07-15T18:48:01Z</updated_at>
    <deleted_at nil="nil"/>
  </item>
</updated_item_notification>

Deactivated Item

Sent when an item is deactivated.

JSON

XML

{
  "id": "ra8nn523yemt",
  "object_type": "item",
  "site_id": "qc326l1hl8k9",
  "event_type": "deactivated",
  "event_time": "2022-07-26T22:46:32Z",
  "item_code": "f6e69ecf299"
}
<?xml version="1.0" encoding="UTF-8"?>
<deactivated_item_notification>
  <item>
    <item_code>gray_socks</item_code>
    <name>Gray Socks</name>
    <description>Gray Socks</description>
    <external_sku>socks-12345</external_sku>
    <accounting_code>acc-12345</accounting_code>
    <revenue_schedule_type>evenly</revenue_schedule_type>
    <tax_exempt type="boolean">true</tax_exempt>
    <tax_code nil="nil"/>
    <pricing_type>fixed</pricing_type>
    <custom_fields type="array">
      <custom_field>
        <name>color</name>
        <value>gray</value>
      </custom_field>
    </custom_fields>
    <unit_amount_in_cents>
      <CAD type="integer">6000</CAD>
      <USD type="integer">1000</USD>
    </unit_amount_in_cents>
    <created_at type="datetime">2019-07-15T18:48:01Z</created_at>
    <updated_at type="datetime">2019-07-15T18:48:01Z</updated_at>
    <deleted_at nil="nil"/>
  </item>
</deactivated_item_notification>

Reactivated Item

Sent when an item is reactivated.

JSON

XML

{
  "id": "ra8nsl5lj561",
  "object_type": "item",
  "site_id": "qc326l1hl8k9",
  "event_type": "reactivated",
  "event_time": "2022-07-26T22:47:22Z",
  "item_code": "07aa63cc7c8"
}
<?xml version="1.0" encoding="UTF-8"?>
<reactivated_item_notification>
  <item>
    <item_code>gray_socks</item_code>
    <name>Gray Socks</name>
    <description>Gray Socks</description>
    <external_sku>socks-12345</external_sku>
    <accounting_code>acc-12345</accounting_code>
    <revenue_schedule_type>evenly</revenue_schedule_type>
    <tax_exempt type="boolean">true</tax_exempt>
    <tax_code nil="nil"/>
    <pricing_type>fixed</pricing_type>
    <custom_fields type="array">
      <custom_field>
        <name>color</name>
        <value>gray</value>
      </custom_field>
    </custom_fields>
    <unit_amount_in_cents>
      <CAD type="integer">6000</CAD>
      <USD type="integer">1000</USD>
    </unit_amount_in_cents>
    <created_at type="datetime">2019-07-15T18:48:01Z</created_at>
    <updated_at type="datetime">2019-07-15T18:48:01Z</updated_at>
    <deleted_at nil="nil"/>
  </item>
</reactivated_item_notification>

External Subscription Notifications

New External Subscription

Sent when an external subscription is created.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "created",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<new_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</new_external_subscription_notification>

Renewed External Subscription

Sent when an external subscription is renewed.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "renewed",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<renewed_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</renewed_external_subscription_notification>

Canceled External Subscription

Sent when an external subscription is canceled.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "canceled",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<canceled_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</canceled_external_subscription_notification>

Downgraded External Subscription

Sent when an external subscription is downgraded.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "downgraded",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<downgraded_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</downgraded_external_subscription_notification>

Upgraded External Subscription

Sent when an external subscription is upgraded.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "upgraded",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<upgraded_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</upgraded_external_subscription_notification>

Expired External Subscription

Sent when an external subscription is expired.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "expired",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<expired_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</expired_external_subscription_notification>

Extended Renewal for External Subscription

Sent when an external subscription’s renewal has been extended.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "extended_renewal",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<extended_renewal_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</extended_renewal_external_subscription_notification>

Failed Renewal for External Subscription

Sent when an external subscription’s renewal has failed.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "failed_renewal",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<renewal_failure_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</renewal_failure_external_subscription_notification>

Failed Renewal with Grace Period for External Subscription

Sent when an external subscription’s renewal has failed with a grace period.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "failed_renewal_with_grace_period",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<renewal_failure_with_grace_period_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</renewal_failure_with_grace_period_external_subscription_notification>

Reactivated External Subscription

Sent when an external subscription is reactivated.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "reactivated",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<reactivated_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</reactivated_external_subscription_notification>

Resubscribed External Subscription

Sent when an external subscription is resubscribed.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "resubscribed",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<resubscribed_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</resubscribed_external_subscription_notification>

Refunded External Subscription

Sent when an external subscription is refunded.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "refunded",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<refunded_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</refunded_external_subscription_notification>

Refund Declined for External Subscription

Sent when an external subscription’s refund is declined.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "refund_declined",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<refund_declined_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</refund_declined_external_subscription_notification>

Refund Reversed for External Subscription

Sent when an external subscription’s refund is reversed.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "refund_reversed",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<refund_reversed_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</refund_reversed_external_subscription_notification>

Paused External Subscription

Sent when an external subscription is paused.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "paused",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<paused_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</paused_external_subscription_notification>

Revoked External Subscription

Sent when an external subscription is revoked.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "revoked",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<revoked_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</revoked_external_subscription_notification>

Recovered External Subscription

Sent when an external subscription is recovered.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "recovered",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<recovered_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</recovered_external_subscription_notification>

Price Change Confirmed for External Subscription

Sent when an external subscription’s price change is confirmed.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "price_change_confirmed",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<price_change_confirmed_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</price_change_confirmed_external_subscription_notification>

Pause Schedule Changed for External Subscription

Sent when an external subscription’s pause schedule is changed.

JSON

XML

{
  "id": "s0lo0hdfmauc",
  "object_type": "external_subscription",
  "site_id": "qpem7fkwr763",
  "event_type": "pause_schedule_changed",
  "event_time": "2022-12-06T22:19:15Z"
}
<?xml version="1.0" encoding="UTF-8"?>
<pause_schedule_changed_external_subscription_notification>
  <external_subscription>
    <id>uuid</>
  </external_subscription>
  <external_resource>
    <id></id>
    <external_object_reference></external_object_reference>
  </external_resource>
  <external_product_reference>
    <id></id>
    <reference_code></reference_code>
    <created_at></created_at>
    <updated_at></updated_at>
  </external_product_reference>
</pause_schedule_changed_external_subscription_notification>