====== Ecommerce + XML = Flexible ====== **Prior to v0.5.1:** When you turn on the XML, FoxyCart will "feed" //all// "unfed" transactions back to you. That is, if you turn on your datafeed right now, the first XML sent will include ALL previous transactions that your store may have processed. This would be helpful if, for example, you wanted to import all of your customers into a mailing list, but in some cases this is //NOT// the behavior you want. This functionality may change in the future once exporting transactions to XML is allowed. ===== An Overview of FoxyCart's XML Datafeeds ===== In order to allow the flexibility and integration options that you need, FoxyCart can be configured to send encrypted XML to a URL of your choosing. This allows you to integrate FoxyCart without duplicating data across applications. When you configure it for your store, it will send you an encrypted xml data post of your new transactions immediately* upon a successful transaction. (*The processing actually happens between the checkout and the receipt for FoxyCart version 0.5.1+. Prior versions will send the datafeed once a minute.) You can then [[http://www.modxcms.com/FoxyCart-Inventory-0.1.0-1495.html|update your inventory]], [[http://www.modxcms.com/FoxyCart-Webuser-Paid-Subsciptions-0.1.0-1684.html|manage paid subscriptions]], [[:integration:campaign_monitor|add users to your mailing list]], or whatever else you can dream up. You have full control. Please note that FoxyCart's XML datafeeds do //not// include credit card information (number, CSC, date, etc.). ===== DETAILS, BEST PRACTICES and TESTING Recommendations ===== ==== Details ==== * When the datafeed is sent it **REQUIRES A RESPONSE OF ''foxy''** in order to indicate success. If anything other than ''foxy'' is returned by your datafeed processing script, FoxyCart will assume that your script errored, and you will be alerted. * As of FoxyCart v051 the XML datafeed is sent immediately, in between the checkout and the receipt during your customers' transactions. Prior to v051 the datafeed was sent once a minute, and may have included multiple transactions in a single POST. ==== Testing ==== When you're testing your custom XML integration, don't run transactions through FoxyCart. This is both time consuming (as you have to add-to-cart, checkout, then wait up to a minute to receive the XML), but it also doesn't give you any indication of what's actually going wrong. A much better method is to use the [[:integration:foxycart:test_xml_post|XML Test Post]] script or [[:integration:foxycart:test_xml_post_with_csharp|application (C#)]]. This effectively mimics what FoxyCart is actually doing when sending the XML to your server in the first place. **Make sure you update the test XML** in the script to the appropriate version (below). If you'd like to test using real data from your store, you can run a test transaction and [[:integration:foxycart:test_xml_write_to_file|write the datafeed to a file]], then copy it out and put it in the Test Post script. If you're struggling to just get started with //reading// the feed, try this: on your script page, capture all the POST data and write it to a file. Test it by posting a simple form to this page just to ensure that it works, and then you can run a //single// FoxyCart transaction to capture its data. You should end up with an array with a key of 'FoxyData' and pages of url-encrypted data, e.g. "%EBrV%8C%E9...". After you've saved this to a file, you can work out the other details of your script, e.g. decoding the XML and routing it to your database or 3rd party applications (e.g. MailChimp). When you turn on the XML, FoxyCart will "feed" //all// "unfed" transactions back to you. That is, if you turn on your datafeed right now, the first XML sent will include ALL previous transactions that your store may have processed. This would be helpful if, for example, you wanted to import all of your customers into a mailing list, but in some cases this is //NOT// the behavior you want. This functionality may change in the future once exporting transactions to XML is allowed. If you'd like to "clear" your datafeed and mark all previous transactions as "fed", you can create a text file on your server containing just the word "foxy". Point your datafeed URL to that file and FoxyCart will mark all your existing transactions as "fed", and it will not feed them again. ==== Best Practices ==== * Test according to the above method. * If you're doing complicated stuff, you may want to [[:integration:mysql|backup the XML to a database]]. This allows you to re-process things at a later date (like if you change mailing list service providers, add a new member functionality, etc.). * Don't make assumptions about the data structure. Rather than just accessing a node and assuming the value is there, test first. This can prevent errors down the road. ===== Notes ===== * The transaction XML datafeed comes with a ''POST'' name of ''FoxyData''. This is different than the [[subscription_datafeed|subscription XML datafeed]], which has a ''POST'' name of ''FoxySubscriptionData''. * FoxyCart v0.5.1+ sends the XML datafeed immediately, in between the checkout and receipt. Previous version send it once a minute. === Country Codes === For compatibility, FoxyCart uses ISO country codes in our XML: * http://www.iso.org/iso/country_codes/iso_3166_code_lists/english_country_names_and_code_elements.htm * http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Decoding_table ===== Example XML ===== === FoxyCart v060 Datafeed === * CHANGE: ''CDATA'' tags added to most elements. * NEW FIELDS: ''is_test'' used to indicate if the transaction is a test transaction (or a live one) based on the store's payment processor settings. * NEW FIELDS: ''is_anonymous'' * NEW FIELDS: ''cc_number_masked'' * NEW FIELDS: ''cc_type'' * NEW FIELDS: ''cc_exp_month'' * NEW FIELDS: ''cc_exp_year'' * NEW FIELDS: ''processor_response_details''. Only used for Orbital and Cybersource. Child nodes vary per gateway. * FIX: ''shipto_shipping_service_description'' was added back to the shipto_address node. * CHANGE: ''sub_token_url'' is populated on the initial transaction's datafeed. At this point, it will populate with the ''sub_token'' of the //first// subscription in the transaction. If you have multiple distinct subscriptions in one transaction you may not want to rely on the ''sub_token'' sent in the initial datafeed. * CHANGE: The ''processor_response'' now includes the gateway's ID, not the FoxyCart transaction ID. === FoxyCart v051 Datafeed === 2699 13 2009-05-09 19:04:41 Authorize.net Transaction ID:2699 116 John Doe ACME Inc. 555 Mulberry Dr. #200 Pleasantville CA 90740 US 555-444-3333 test1@example.com 71.165.140.208 US 15.88 0.1 193.04 209.02 authorize https://example.foxycart.com/receipt?id=466f78a86b9e031f7ede4fb1600a0605 2010-01-01 3.0000 California 0 5.0000 US 0 1.0000 Global Tax 0 1.0000 Global Tax 0.1 517b823f9575bbad3268d7d1d6ed951c hash testing12345 Example Product 10.00 1 4.000 abc123zzz 0000-00-00 Me Discount: Price: Percentage discount_price_percentage shipped color red -4.000 0.000 Price Discount Amount -2% -0.120 0.000 Example Subscription 10.00 1 4.000 xyz456 1m 2009-12-01 Me Default for all products DEFAULT flat_rate color red -4.000 0.000 testing aa 10.00 1 0.000 046a https://example.foxycart.com/path/to/file 0000-00-00 mom Default for all products DEFAULT flat_rate color red 0.000 0.000 55 Me John Doe ACME Inc. 555 Mulberry Dr. #200 Pleasantville CA 90740 US 56 mom Madre Doe 1234 Calle de Carretas Madrid Madrid 28004 ES === FoxyCart versions prior to v051 === Versions of FoxyCart prior to v051 the datafeed version was independent of the store version. Here are the datafeed versions available with v050 and prior. === Datafeed v0.8 === * NEW FIELDS: store_id * NEW FIELDS: processor_response * NEW FIELDS: taxes * tax * tax_name * tax_amount * tax_rate * NEW FIELDS: shipto_taxes * shipto_tax * shipto_tax_name * shipto_tax_amount * shipto_tax_rate * //undocumented fields in the sample XML?// * transaction/payment_gateway_type * transaction/receipt_url * transaction/transaction_details/transaction_detail/sub_token_url XML FoxyCart Version 0.8 2429 13 2009-03-06 11:16:36 Authorize.net Transaction ID:2429 62 John Doe 555 Mulberry Dr. Happyville CA 90740 US example@example.com 55.55.22.190 UPS: 2nd Day Air 21.19 0.00 66.06 71.95 authorize https://example.foxycart.com/receipt?id=40880711ff2c02bc689b54f9b0159d1d 5.0000 US 0.0000 3.0000 California 0.0000 test1 $5 off all orders over $5! -5.00 -5.00 price_amount 5-5 test2 Testing Again -1.00 -1.00 quantity_amount 3-1 912ec803b2ce49e4a541068d495ab570 example_hidden value_1 Example Product 10.00 3 4.000 abc123zzz 0000-00-00 0000-00-00 Discount: Price: Percentage discount_price_percentage shipped color red -4.000 0.000 Price Discount Amount -5% -0.267 0.000 Quantity Discount -$0.67 -0.667 0.000 Example Subscription 10.00 1 4.000 xyz456 1m 2009-12-01 2009-12-01 https://example.foxycart.com/cart?sub_token=fb5dfbbb51c81bdc60b033665515884c Default for all products DEFAULT shipped color red -4.000 0.000 === Datafeed v0.7 === * NEW FIELDS: discounts * discount * code * name * amount * display * coupon_discount_type * coupon_discount_details * NEW FIELDS: transaction * customer_company * shipping_company * NEW FIELDS: shipto_address * shipto_company XML FoxyCart Version 0.7 2279 2009-02-12 12:28:50 51 John Doe 555 Mulberry Ln Hapyville CA 55555 US example@example.tld 55.44.33.222 115.00 2.05 57.75 156.30 asdf $5 off all orders over $5! -5.00 -5.00 price_amount 5-5 fd2cc6c54239c40495a0d3a93b6380eb testing 03 10.00 1 1.000 003a 0000-00-00 0000-00-00 Me Default for all products DEFAULT shipped color red 0.000 4.000 testing 38 10.00 1 1.000 028a 1m 2012-03-01 2012-03-01 Me Default for all products DEFAULT shipped color red 0.000 0.000 lamerss 17 10.00 10 0.500 317a 0000-00-00 0000-00-00 Me Discount: Qty: Percentage discount_qty_percentage shipped color red 0.000 0.000 Quantity Discount -5% -0.500 0.000 Me John Doe 555 Mullberry Ln Happyville CA 55555 US UPS: 2nd Day Air 115.00 1.44 57.75 160.69 === Datafeed v0.6 === v0.6 added the hash of the customer's password, sent as an MD5 hash. XML FoxyCart Version 0.6 616 2007-05-04 20:53:57 122 John Doe 12345 Any Street Any City TN 37013 US (123) 456-7890 someone@somewhere.com 71.228.237.177 John Doe 1234 Any Street Some City TN 37013 US UPS: Ground 20.00 0.00 4.38 24.38 1aab23051b24582c5dc8e23fc595d505 My_Cool_Text Value123 Another_Custom_Field 10 foo 20.00 1 0.10 1m 2007-07-07 2007-08-07 John Doe Default for all products DEFAULT shipped color blue John Doe John Doe 2345 Some Address Some City TN 37013 US DHL: Next Afternoon 52.15 6.31 15.76 74.22 My_Custom_Info john's stuff More_Custom_Info more of john's stuff === Datafeed v0.5 === XML FoxyCart Version 0.5 616 2007-05-04 20:53:57 122 John Doe 12345 Any Street Any City TN 37013 US (123) 456-7890 someone@somewhere.com 71.228.237.177 John Doe 1234 Any Street Some City TN 37013 US UPS: Ground 20.00 0.00 4.38 24.38 My_Cool_Text Value123 Another_Custom_Field 10 foo 20.00 1 0.10 1m 2007-07-07 2007-08-07 John Doe Default for all products DEFAULT shipped color blue John Doe John Doe 2345 Some Address Some City TN 37013 US DHL: Next Afternoon 52.15 6.31 15.76 74.22 My_Custom_Info john's stuff More_Custom_Info more of john's stuff === Datafeed v0.4 === XML FoxyCart Version 0.4 616 2007-05-04 20:53:57 John Doe 12345 Any Street Any City TN 37013 US (123) 456-7890 someone@somewhere.com 71.228.237.177 John Doe 1234 Any Street Some City TN 37013 US 20.00 0.00 4.38 24.38 122 My_Cool_Text Value123 Another_Custom_Field 10 foo 20.00 1 0.10 1m 2007-07-07 2007-08-07 Default for all products DEFAULT shipped color blue