Automatic XML Orders Download

Note:

The information on this page applies to Orders only. For information on automated XML uploads and downloads of Products or Pages, see Database Automated XML Upload/Download.

Note:

To implement this feature as intended, you should familiarize yourself with the sample OAuth source code. It can be downloaded here:
OAuth_Sample.zip

If you plan to implement OAuth in PHP, we've created a pair of files that can be used to accelerate your development. The first, oauth.php, is an OAuth module that can be plugged directly in to your custom PHP script. The second, oauth_tester.php, contains examples of how to use the module with ShopSite. The zip file containing these files can be downloaded here:
OAuth_PHP.zip

You can use a merchant-supplied program to automatically download a store’s orders as an XML-formatted text file. This help page describes the programmatic interface; the XML DTD is described on Orders Download XML Format.

Your orders download program must send a request to a ShopSite Authorization CGI program (authorize.cgi) and provide authentication to receive a token that can authorize a request to a ShopSite Download CGI program (db_xml.cgi) to start the download. To keep order information secure, the ShopSite CGI program must be invoked through a secure connection (https). If the connection is not secure, customer credit card information will not be included in the download.

The db_xml.cgi program can accept these optional parameters:

version - XML order download version. The xml elements included in the download will correspond to the DTD specified by the version. ShopSite will determine the version to use in the following order:

Use the version passed in this field.
If no version is passed, and the merchant has previously done a manual XML download from the Orders Download screen, default to the version selected for the last manual XML download.
If the merchant has not performed a manual download and no version was passed, use version 6.3

You can view the Orders Download screen to do a manual XML download and to see all the versions that are available. ShopSite supports versions 6.3 through 14.0. We strongly recommend that you pass a version or you may not get the elements that you expect!

startorder - The order number of the first order to include in the download. If not specified, the download starts with the oldest order.

endorder - The order number of the last order to include in the download. If not specified, all orders after startorder will be included, or until maxorder is reached.

startdate - The date of the oldest orders to download, in mm/dd/yyyy format. The date is based on server time.

enddate - The date of the newest orders to download, in mm/dd/yyyy format. The date is based on server time.

maxorder - The maximum number of orders to download.

pay - Include payment information (credit card details) in the download. The recommended value for this parameter is "yes". If this parameter is not included in the command line or if a secure connection is not used, the download will not include payment information.

Note:

CVV2 information is only stored by ShopSite when the store is accepting credit cards for manual processing. This information is purged from ShopSite when orders are viewed or downloaded. Sometimes it is necessary to download the order information before authorizations occur, such as when using order managing software. For example, let's say that you manually authorize your credit card transactions and have an order manager that automatically downloads information from ShopSite. When those orders are downloaded to the order manager, the CVV2 information is purged from ShopSite, even if it is not used by the order manager. By setting the value for the "pay" parameter to "no_cvv" ( pay=no_cvv ), the CVV2 information will remain in ShopSite until the order is viewed or downloaded through the back office.

html - Display downloaded orders as HTML output in the browser window.

dkey - The URL encoded key used to decrypt payment information if merchant key encryption is used. If the merchant is using merchant key encryption, the key must be read into a buffer from a file on the merchant's client, URL encoded (keys may include carriage returns, line feeds, and plus characters that must be converted to their hexadecimal codes, %0D, %0A, and %2B respectively), and transmitted securely to the server as the value for the dkey attribute, or else encrypted payment information will not be readable.

While it is possible to use startorder and endorder or startdate and enddate to download a specific set of orders, you do not have to use both the start and end value. You could, for example, use startdate without enddate to download all the orders that have come in since the last time you downloaded orders.

The db_xml.cgi will output the following line, followed by the XML order information:

Content-type: application/x-www-form-urlencoded\n\n