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:

1. have a web server that supports HTTPS (secure sockets), and
2. create (or have created) a script that will;
   1. receive the order (one order per post),
   2. perform the desired functions, and
   3. 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.

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:

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 listed here. You may use both. The URL's tell UltraCart where to post the XML file to and the name of the script itself.

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:

Once you've entered the URL into the appropriate field, click on the "Save" button at the bottom of the screen. Your configuration is complete.

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.

auto_order
  original_order_id
  auto_order_code
  firstname
  lastname
  email
  address
  address2
  city
  state
  zip
  company
  country
  home_phone
  cell_phone
  office_phone
  custom_field_1
  custom_field_2
  custom_field_3
  custom_field_4
  custom_field_5
  custom_field_6
  custom_field_7
  status = active, card declined, cancelled upgrade, cancelled downgrade, cancelled, terminated
  next_attempt
  attempt
  failure_reason
  status
  cancelled_by
  cancelled_dts
  original_items
    item
      item_id
      description
      unit_cost
      quantity
  auto_order_items
    auto_order_item
      original_item_id
      quantity
      frequency_override
      next_shipment
      next_item_id
      no_orders_after
      override_unit_cost
      override_unit_cost_next_x_orders
      percentage_discount
      next_preshipment_notice

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.

Passing Postbacks To Mutliple URLs

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.

Restarting Postbacks After Errors Have Halted Postback Processing

Understanding HTTP Errors 

The table below covers common HTTP result codes that UltraCart may encounter from your server.

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.

Refunds

Orders with partial refunds will report the item Id's of the refunded items, whereas complete refunds will not include the item Id's by default.

Handling Read Timeouts

The XML postback process will wait at most 60 seconds for a response from your web server.  Do not try and perform complex processing of the XML postback document on your receiver.  Simply queue up the XML document in a persistent storage (database, Redis, SQS, etc.) and then perform your more complex processing in a decoupled fashion.  This will allow you to receive a greater velocity of XML postbacks from UltraCart and fan out the processing of those postbacks appropriately. 

Frequently Asked Questions (FAQ)