Versions Compared

Old Version 60

changes.mady.by.user Loyd James

Saved on

compared with

New Version Current

changes.mady.by.user Hunter Schaeffer

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

receive an xml copy of an order after it is placed.



Tip

UltraCart Webhooks supercede the XML Postback.  They are superior in every way.  

Please see the API page for help using webhooks.



Table of Contents

XML Postback

...


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. 


Warning

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).

...

Placing the URL into this field will tell UltraCart to post back when an auto order changes. 


Code Block
languagegroovy
titleAuto Order Update XML details
collapsetrue
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:
...
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.
Image Removed
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.
Image Removed
For each transmission you can see what is sent to your server and what is returned as shown below.
Image Removed
...
Passing Postbacks To Mutliple URLs
 Info
titleMultiple Postback URL's
If you need to configure multiple XML Postback URL's, separate each URL with a space.

PLEASE NOTE: 
While multiple URL's can be configured, we don't recommend more than 2-3 URL's, because all of the configured scripts must succeed. If any one of the scripts returns an unsuccessful reponse, UltraCart will retry the postback to each of the configured postback URL's.

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.
Image Added
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.
Image Added
For each transmission you can see what is sent to your server and what is returned as shown below.
Image Added
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
 Warning
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.)
Understanding HTTP Errors 
The table below covers common HTTP result codes that UltraCart may encounter from your server.
...
 Info
titlePlease Note
If you need the complete refunds to report the item ID's in the order, contact UltraCart by emailing support@ultracart.com stating your UltraCart MerchantID requesting that we enable the merchant property "XML Postback - Skip Adjustment for Refund". 
With this property is enabled, it will prevent refunded items from being removed from the XML postback, so you will see these items in your refund transaction XML packet.
Pay close attention to these optional elements that will indicate the refunding of the item: 

  • quantity_refunded 
  • total_refunded 
Frequently Asked Questions (FAQ)
 
 Expand
titleQ: "I notice that there's an <order> xml element, and that there could be more than one. Is it often that post backs come in with multiple orders in them?"
 A: The XML Postback transmissions are always a single order only.
...

...
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)

 Expand
titleQ: "I notice that there's an <order> xml element, and that there could be more than one. Is it often that post backs come in with multiple orders in them?"
 A: The XML Postback transmissions are always a single order only.

 Expand
titleQ: Are the merchant notes, special instructions, gift message, and comments transmitted in the XML document?
 A: Yes, if they are present on the order then they are populated in the XML.  We don't populate empty elements for these fields though.  The element names are:
  • special_instructions
  • comments
  • gift_message
  • merchant_notes

    Please consult the XML Schema for a full description of the XML document structure.
...
 Expand
titleFor 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 should check for? 
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.

 Expand
titleWe moved our XML Postback script to a new server via Cloudflare, and since then then our XML Postback is not longer working and is now disabled.
At this point in time you cant configure an XML postback to 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.URL that is fronted by Cloudflare. (XML postback requires a non-SNI hosted environment.)