Push Notifications API

Configuration

Please see our push notifications documentation for more information.

There is an example on how to use push notification in PHP available here. This example is for educational purposes only and should not be used for mission critical information.

Examples

Account Notifications

New Account

Sent when a new account is created.

<?xml version="1.0" encoding="UTF-8"?>
<new_account_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
</new_account_notification>

Closed Account

Sent when an account is closed. If an account is reopened, a new_account_notification is sent.

<?xml version="1.0" encoding="UTF-8"?>
<canceled_account_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
</canceled_account_notification>

Updated Billing Information

Sent when billing information is successfully created or updated on an account.

<?xml 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>

Reactivated Account

Sent when an account subscription is reactivated after having been canceled.

<?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>
    <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>

Subscription Notifications

New Subscription

Sent when a new subscription is created.

<?xml version="1.0" encoding="UTF-8"?>
<new_subscription_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true">verena</username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true">Company, Inc.</company_name>
  </account>
  <subscription>
    <plan>
      <plan_code>bronze</plan_code>
      <name>Bronze Plan</name>
      <version type="integer">2</version>
    </plan>
    <uuid>8047cb4fd5f874b14d713d785436ebd3</uuid>
    <state>active</state>
    <quantity type="integer">2</quantity>
    <total_amount_in_cents type="integer">2000</total_amount_in_cents>
    <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>
  </subscription>
</new_subscription_notification>

Updated Subscription

When a subscription is upgraded or downgraded, Recurly will send an updated_subscription_notification. The notification is sent after the modification is performed. If you modify a subscription and it takes place immediately, the notification will also be sent immediately. If the subscription change takes effect at renewal, then the notification will be sent when the subscription renews. Therefore, if you receive an updated_subscription_notification, it contains the latest subscription information.

<?xml version="1.0" encoding="UTF-8"?>
<updated_subscription_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
  <subscription>
    <plan>
      <plan_code>1dpt</plan_code>
      <name>Subscription One</name>
    </plan>
    <uuid>292332928954ca62fa48048be5ac98ec</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">200</total_amount_in_cents>
    <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

The canceled_subscription_notification is sent when a subscription is canceled. This means the subscription will not renew. The subscription state is set to canceled but the subscription is still valid until the expires_at date. The next notification is sent when the subscription is completely terminated.

<?xml version="1.0" encoding="UTF-8"?>
<canceled_subscription_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
  <subscription>
    <plan>
      <plan_code>1dpt</plan_code>
      <name>Subscription One</name>
    </plan>
    <uuid>dccd742f4710e78515714d275839f891</uuid>
    <state>canceled</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">200</total_amount_in_cents>
    <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

The expired_subscription_notification is sent when a subscription is no longer valid. This can happen if a canceled subscription expires or if an active subscription is refunded (and terminated immediately). If you receive this message, the account no longer has a subscription.

<?xml version="1.0" encoding="UTF-8"?>
<expired_subscription_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
  <subscription>
    <plan>
      <plan_code>1dpt</plan_code>
      <name>Subscription One</name>
    </plan>
    <uuid>d1b6d359a01ded71caed78eaa0fedf8e</uuid>
    <state>expired</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">200</total_amount_in_cents>
    <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

The renewed_subscription_notification is sent whenever a subscription renews. This notification is sent regardless of a successful payment being applied to the subscription—it indicates the previous term is over and the subscription is now in a new term. If you are performing metered or usage-based billing, use this notification to reset your usage stats for the current billing term.

<?xml version="1.0" encoding="UTF-8"?>
<renewed_subscription_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
  <subscription>
    <plan>
      <plan_code>bootstrap</plan_code>
      <name>Bootstrap</name>
    </plan>
    <uuid>6ab458a887d38070807ebb3bed7ac1e5</uuid>
    <state>active</state>
    <quantity type="integer">1</quantity>
    <total_amount_in_cents type="integer">9900</total_amount_in_cents>
    <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>

Payments

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.

Successful Payment

A successful_payment_notification is sent when a payment is successfully captured.

<?xml version="1.0" encoding="UTF-8"?>
<successful_payment_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true">verena</username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true">Company, Inc.</company_name>
  </account>
  <transaction>
    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>
    <invoice_id>1974a09kj90s0789dsf099798326881c</invoice_id>
    <invoice_number type="integer">2059</invoice_number>
    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>
    <action>purchase</action>
    <date type="datetime">2009-11-22T13:10:38Z</date>
    <amount_in_cents type="integer">1000</amount_in_cents>
    <status>success</status>
    <message>Bogus Gateway: Forced success</message>
    <reference></reference>
    <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>

Failed Payment

A failed_payment_notification is sent when a payment attempt is declined by the payment gateway.

<?xml version="1.0" encoding="UTF-8"?>
<failed_payment_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true">verena</username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true">Company, Inc.</company_name>
  </account>
  <transaction>
    <id>a5143c1d3a6f4a8287d0e2cc1d4c0427</id>
    <invoice_id>8fjk3sd7j90s0789dsf099798jkliy65</invoice_id>
    <invoice_number type="integer">2059</invoice_number>
    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>
    <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>Declined</status>
    <message>This transaction has been declined</message>
    <reference></reference>
    <cvv_result code=""></cvv_result>
    <avs_result code=""></avs_result>
    <avs_result_street></avs_result_street>
    <avs_result_postal></avs_result_postal>
    <test type="boolean">true</test>
    <voidable type="boolean">false</voidable>
    <refundable type="boolean">false</refundable>
  </transaction>
</failed_payment_notification>

Successful Refund

If you refund an amount through the API or admin interface, a successful_refund_notification is sent. Failed refund attempts do not generate a notification.

<?xml version="1.0" encoding="UTF-8"?>
<successful_refund_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
  <transaction>
    <id>2c7a2e30547e49869efd4e8a44b2be34</id>
    <invoice_id>ffc64d71d4b5404e93f13aac9c63b007</invoice_id>
    <invoice_number type="integer">2059</invoice_number>
    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>
    <action>credit</action>
    <date type="datetime">2010-10-06T20:37:55Z</date>
    <amount_in_cents type="integer">235</amount_in_cents>
    <status>success</status>
    <message>Bogus Gateway: Forced success</message>
    <reference></reference>
    <cvv_result code=""></cvv_result>
    <avs_result code=""></avs_result>
    <avs_result_street></avs_result_street>
    <avs_result_postal></avs_result_postal>
    <test type="boolean">true</test>
    <voidable type="boolean">true</voidable>
    <refundable type="boolean">false</refundable>
  </transaction>
</successful_refund_notification>

Void Payment

If you void a successfully captured payment before it settles, a void_payment_notification is sent. Payments can only be voided before the funds settle into your merchant account.

<?xml version="1.0" encoding="UTF-8"?>
<void_payment_notification>
  <account>
    <account_code>1</account_code>
    <username nil="true"></username>
    <email>verena@example.com</email>
    <first_name>Verena</first_name>
    <last_name>Example</last_name>
    <company_name nil="true"></company_name>
  </account>
  <transaction>
    <id>4997ace0f57341adb3e857f9f7d15de8</id>
    <invoice_id>ffc64d71d4b5404e93f13aac9c63b007</invoice_id>
    <invoice_number type="integer">2059</invoice_number>
    <subscription_id>1974a098jhlkjasdfljkha898326881c</subscription_id>
    <action>purchase</action>
    <date type="datetime">2010-10-05T23:00:50Z</date>
    <amount_in_cents type="integer">235</amount_in_cents>
    <status>void</status>
    <message>Test Gateway: Successful test transaction</message>
    <reference></reference>
    <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>