Subscription XML Datafeed

Version 0.5.0+ contains a subscription datafeed which runs once a day and sends data to the same location configured for your regular data feed. It contains transaction information for subscriptions that are either past due, have a subscription end date set or were canceled today. The transaction details are obtained from the last successful transaction. Note: This is not the datafeed that tracks new and recurring subscription transactions; that data is sent as the transactions occur in the transaction XML datafeed.

It also contains customer information for customers who's payment methods are about to expire.

A few things worth noting:

• The subscription XML datafeed comes with a POST name of FoxySubscriptionData. This is different than the transaction XML datafeed, which has a POST name of FoxyData.
• The subscription XML datafeeds are set to run once a day, about 19:00 GMT (12:00 noon PST). The exact time you receive your subscription XML datafeed depends on a variety of factors.
• Subscriptions themselves are set to run about 12:00 noon GMT (05:00 PST). As with the subscription XML datafeed, the exact time depends on a variety of factors.
• Customers will be included in the payment_methods_soon_to_expire node if their credit card expiration month is the current month, or the next month. So if the expiration month is 05, the customer will be included if the current month is 04 or 05.

<?xml version='1.0' encoding='UTF-8' standalone='yes'?>
<foxysubscriptiondata>
 <subscriptions>
  <subscription>
   <subscription_id>200</subscription_id>
   <next_transaction_date>2009-03-24</next_transaction_date>
   <end_date>2009-03-04</end_date>
   <past_due_amount>0.00</past_due_amount>
   <frequency>1m</frequency>
   <error_message></error_message>
   <sub_token_url>https://example.foxycart.com/cart?sub_token=9c7ac0cadc73f93e126b6d97893cad3f</sub_token_url>
   <first_failed_transaction_date></first_failed_transaction_date>
   <store_id>1</store_id>
   <customer_id>44</customer_id>
   <transaction_id>2397</transaction_id>
   <transaction_date>2009-02-24 23:00:33</transaction_date>
   <order_total>10.00</order_total>
   <customer_first_name>John</customer_first_name>
   <customer_last_name>Doe</customer_last_name>
   <customer_address1>1234 Any Street</customer_address1>
   <customer_address2></customer_address2>
   <customer_city>Any City</customer_city>
   <customer_state>TN</customer_state>
   <customer_postal_code>12345</customer_postal_code>
   <customer_country>US</customer_country>
   <customer_phone></customer_phone>
   <customer_email>email@example.com</customer_email>
   <customer_ip>123.123.123.123</customer_ip>
   <receipt_url>https://example.foxycart.com/receipt?id=fe376559e8f76a2fafa8c707c73cda2a</receipt_url>
   <transaction_details>
    <transaction_detail>
     <product_name>monthly subscription</product_name>
     <product_price>10.00</product_price>
     <product_quantity>1</product_quantity>
     <product_weight>0.000</product_weight>
     <product_code></product_code>
     <category_description>Default for all products</category_description>
     <category_code>DEFAULT</category_code>
     <product_delivery_type>notshipped</product_delivery_type>
     <product_options>
     </product_options>
    </transaction_detail>
   </transaction_details>
  </subscription>
  <subscription>
   <subscription_id>196</subscription_id>
   <next_transaction_date>2009-03-25</next_transaction_date>
   <end_date>0000-00-00</end_date>
   <past_due_amount>50.00</past_due_amount>
   <frequency>1m</frequency>
   <error_message>Error: There was an error processing your payment: Credit card number is required. (Response Reason Code: 33)</error_message>
   <sub_token_url>https://example.foxycart.com/cart?sub_token=3076ca2af366d8a2647b60484a9fbefc</sub_token_url>
   <first_failed_transaction_date>2009-03-24</first_failed_transaction_date>
   <store_id>1</store_id>
   <customer_id>60</customer_id>
   <transaction_id>2380</transaction_id>
   <transaction_date>2009-02-24 21:06:31</transaction_date>
   <order_total>25.00</order_total>
   <customer_first_name>Test</customer_first_name>
   <customer_last_name>Test</customer_last_name>
   <customer_address1>12345 any city</customer_address1>
   <customer_address2></customer_address2>
   <customer_city>Any City</customer_city>
   <customer_state>TN</customer_state>
   <customer_postal_code>12345</customer_postal_code>
   <customer_country>US</customer_country>
   <customer_phone></customer_phone>
   <customer_email>email2@example.com</customer_email>
   <customer_ip>123.123.123.123</customer_ip>
   <receipt_url>https://example.foxycart.com/receipt?id=962aafde40dbc187abbd420e13548529</receipt_url>
   <transaction_details>
    <transaction_detail>
     <product_name>monthly product</product_name>
     <product_price>25.00</product_price>
     <product_quantity>1</product_quantity>
     <product_weight>0.000</product_weight>
     <product_code>610</product_code>
     <category_description>Default for all products</category_description>
     <category_code>DEFAULT</category_code>
     <product_delivery_type>notshipped</product_delivery_type>
     <product_options>
     </product_options>
    </transaction_detail>
   </transaction_details>
  </subscription>
 </subscriptions>
 <payment_methods_soon_to_expire>
  <customer>
   <customer_id>4</customer_id>
   <customer_first_name>Test</customer_first_name>
   <customer_last_name>Test</customer_last_name>
   <customer_email>test.test@example.com</customer_email>
   <cc_exp_month>02</cc_exp_month>
   <cc_exp_year>2009</cc_exp_year>
  </customer>
  <customer>
   <customer_id>10</customer_id>
   <customer_first_name>Test2</customer_first_name>
   <customer_last_name>Test2</customer_last_name>
   <customer_email>test2.test2@example.com</customer_email>
   <cc_exp_month>02</cc_exp_month>
   <cc_exp_year>2009</cc_exp_year>
  </customer>
 </payment_methods_soon_to_expire>
</foxysubscriptiondata>

While the options are endless, the basic idea of how to handle paid memberships to your site is as follows: As far as using the subscription XML, it'd be fairly straightforward.

1. Create a processor to send the XML (both subscription and transaction XML datafeeds) to.
2. The processor decrypts the XML.
3. On transaction XML datafeed, the processor checks for new subscription transactions and adds the appropriate permissions to the appropriate user.
4. On daily subscription XML datafeed, the processor checks for expiring subscriptions and removes permissions as necessary.
5. The processor could also check for expiring credit cards, billing errors, and etc., and email customers as necessary.

An additional consideration is to figure out what you want to do with billing errors. You could remove access immediately, or you could flag the user to expire on a certain date in the future to provide a grace period of sorts. Doing so might require adding a column to the user or permissions table and perhaps a cron job, or you could tie it to your system's login event.

There are some sample scripts for dealing with the XML datafeeds in a variety of languages in our integration repository.