receive an xml copy of an order after it is placed.
XML Postback
UltraCart's XML Post Back feature gives merchants the opportunity to have orders automatically "posted" to their server shortly after the order is placed. Orders will be transmitted in XML (Extensible Markup Language) format. Once received, they can have any number of functions automatically performed based on any parameters within the order.
Merchants might consider utilizing the post back function for the following reasons:
- Automatically receive orders shortly after they are placed.
- For doing any validation or other processing on their server side.
- Receive updated order status automatically (optional).
Requirements
The XML Post Back feature should only be used by advanced merchants with software development skills or with programmers at their disposal. Presently, UltraCart does not provide script templates.
There are two requirements to make the XML Post Back possible. A merchant must:
- have a web server that supports HTTPS (secure sockets), and
- create (or have created) a script that will;
- receive the order (one order per post),
- perform the desired functions, and
- send a "return success" code 200 to UltraCart.
XML Postback Script on Your Server
Several languages can and are used for receiving and performing functions with the XML format. Some examples are; PHP, Perl, Python, C#, ASP, Java, Ruby, and Cold Fusion. Here is an example PHP Script that you can use to get started. You will need to embellish it with your back-end business logic.
The XML message posted back is equivalent to manually exporting 1 order in the XML W3C Schema format from Order Management → Export Orders.
Programmers need to be aware that the XML is within the HTTP body, not in parameters.
Post Back Configuration
Prior to configuring the Post Back feature insure that you have your script in place on your server. Once that is completed, log in to your UltraCart account and navigate to:
Main Menu → Configuration → Back Office → XML Post Back
Once you click on the XML Postback link, the following screen will appear
Most merchants will chose to use one or the other of the two options list here. You may use both. The urls tell UltraCart where to post the XML file to and the name of the script itself.
UltraCart will not send duplicate notifications. If you configure the second option (stage changes), you will not receive any notifications via the first option. Instead, when an order is placed, you'll receive a postback with the appropriate stage change (depends on the status/success of the order).
First Option: Transmit to URL when order placed
Placing the URL into this field will tell UltraCart to post back any order when and only when the order is created. UltraCart will continue to post back the order to your server until it receives a "return success" code (200).
Second Option: Transmit to URL when stage changes
Placing the URL into this field will tell UltraCart to post back any order when the status (stage) of an order changes.
The status will appear in the current_stage
field. The status (stage) values are:
current_stage status | Stage |
---|---|
AR | Accounts Receivable |
CO | Completed Order |
IN | Inserting (Placed Order) |
PC | Pending Clearance (of check orders) |
PO | Pre-Order |
QR | Quote Request |
QS | Quote Sent |
REJ | Rejected |
SD | Shipping Department |
Once you've entered the URL into the appropriate field, click on the "Save" button at the bottom of the screen. Your configuration is completed.
Third Option: Transmit Auto Order Status to URL when auto order changes
Placing the URL into this field will tell UltraCart to post back when an auto order changes.
Frequently Asked Questions
Q: When the postback occurs does it always pass the full set of customer data including custom fields?
A: There is quite a bit of order information in the XML postback, including customer data and the custom fields 1-7.
Q: Is there a way it identifies it self as an auto-order vs an initial order?
A: On an order XML postback there is an element for the auto_order information. Inside that element there is a field for auto_order_original_order_id. If that is the same as the order_id in the XML document then this is the original order in the auto order sequence. If it's different then it's a rebill.
Q: Just to clarify for each successful auto-order charge it will go through the main postback URL right? (not the auto-order status change URL)
A: Orders go through one URL and auto order status information through another. They can be the same URL if you want to configure it that way and just teach the one script to parse the XML document and then look at the content differently.
Q: For the auto-order status change postback, do you have an XML schema for that? or is it the same as the normal postback? is their a particular field that we shouid check for?
A: There is not a schema file for this yet, but the easiest thing to do is configure a dummy URL, let the auto order XML postback fire, and then check the log under the XML postback configuration to see a copy of the document it tried to send.
Refunds
If you use the second option "Transmit to URL when stage changes" then UltraCart will also send you an XML postback when a refund occurs. When refunds occur the order can be in multiple stages (SD or CO typically) so you will want to look for the following elements in the XML:
subtotal_discount_refunded
subtotal_refunded
other_refunded
tax_refunded
shipping_handling_refunded
buysafe_refunded
total_refunded
refund_dts
If a refund has occurred the elements "total_refunded" and "refund_dts" will always exist. The other elements mentioned above will exist if that component of the order was refunded.
Log
Since the information sent to your server is critical to your business operation, UltraCart records logs of each transmission. To access the logs
click on the Log button as shown below.
When you click on the log it will show you the order id, timestamp, and result for each transmission. Notice that we can quickly see that UltraCart
is having trouble connecting to this server.
For each transmission you can see what is sent to your server and what is returned as shown below.
Notice that UltraCart is logging the response back from your server. It only cares about the 200 result code to determine success, but logging
the response from your server allows you to output information that you can review in the logs for debugging purposes.
If UltraCart encounters 50 consecutive errors from your server, it will disable the XML postback and email you. The transmissions will queue up until you edit your XML Postback configuration.
After reviewing the logs to determine the cause of the errors. To restart the processing of the queued orders, re-save the XML PostBack settings (Click the save button on the XML Postback configuration page.)
The table below covers common HTTP result codes that UltraCart may encounter from your server.
Code | Meaning |
---|---|
200 | OK |
301 | Moved Permanently |
302 | Moved Temporarily (Redirect) |
400 | Bad Request |
401 | Unauthorized |
403 | Forbidden |
404 | Not found (the script doesn't exist on your server) |
405 | Method Not Allowed (Your script doesn't support POST) |
500 | Internal Error (your script blew chunks) |
The complete list can be found at http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
How do I resend historical data to my server via XML postback?
Identify the first and last order id for the range of data that you want to resend to your new XML postback URL. Use the batch order operation utility to populate the XML postback queue.
Frequently Asked Questions (FAQ)