What is the Shipping API?
The AuctionInc Shipping API is a web service providing an XML interface to our shipping engine technology. By integrating our API, your customers can utilize the shipping rate technology we have developed without ever leaving your web site. With one call to our API, you can offer your customers accurate comparative rates for multiple shipping options across multiple carriers and services for one or more items for both domestic and international destinations.
Is the Shipping API the best choice for you?
AuctionInc provides a variety of products which access our shipping rate technology. Using the API requires the most effort to implement, but offers significant advantages:
What specifically does the Shipping API provide?
For a specified origin and destination and given item characteristics for one or more items, our Shipping API returns accurate shipping rates per service for one of more requested carrier services. For multiple items, our packaging engine intelligently packages items into one or more packages and bases the returned rate on the number of resulting packages required.
Is there a requirement for configuration/shipping preferences to be set up and stored in AuctionInc to utilize the API?
Two varients of the Shipping API are available:
Programmng Skills are necessary in order to implement this API, in particular experience with programming for the Internet and with web site development tools and techniques. You must be able to gather the necessary data for the XML request, construct and parse XML, send a POST request, and probably most importantly, utilize the results of your API appropriately in your web site or product.
Any Programming Language can be used to utilize the Shipping API, including Visual Basic, Perl, ASP, java, PHP, C++, etc. The only requirement is the ability to construct, send and parse the XML which comprises the data which is exchanged between you and us.
XML and HTTP are the two essential protocols which are required to utilize the Shipping API. XML is a simple, platform independent, very flexible text format protocol for exchanging information. HTTP is the standard protocol for transferring World Wide Web documents, including XML documents.
Register for an AuctionInc Account
All Shipping API users must first register for an account with AuctionInc at www.auctioninc.com. On the registration page, select the Shipping API under Ecommerce Tools as your product type. Please familiarize yourself with our pricing policies for the Shipping API before you register. If you already have an AuctionInc account, you can add a subscription to the Shipping API from My Account => Product Subscriptions. The AuctionInc Shipping API includes rating availability for supported international carrier services at no additional charge.
Record your Access Key
After you complete registration or subscription sign-up, you are given an Account ID. This Account ID must be included in all API calls to the AuctionInc Shipping API. This access key will always appear on your Product Subscription page.
For Saved Settings ("SS") Accounts: Complete the Setup Wizard
For customers who are planning to make Saved Settings or Single Seller ("SS") calls, please complete the Setup Wizard in order to store your shipping preferences. These preferences will be used in conjunction with the data received from your API call to determine the shipping services and rates returned. You may edit these settings at any time by logging into your AuctionInc account and going to Control Center => Settings => Shipping Settings.
The process of utilizing the Shipping API breaks down into four general steps:
1. Build the XML Request
Each request is composed of XML elements that specify the request parameters (e.g., the properties of one or more items to be rated). The specific elements required for each of the two call types (configured and non-configured) is provided in detail in API Methods, and the details on each element are specified in the API Schema.
2. Create an HTTP POST Connection
To initiate a Shipping API call, you will make an HTTP request. This request will consist of a standard HTTP “POST” request, made up of the request, request header fields, and the message body. The message body of this request will be the Shipping API Request XML.
3. Send the XML Request
The URL to post your request to is http://api.auctioninc.com/websvc/shire.
4. Parse the XML Response
For every successful POST initiated by you, we will transmit back a HTTP response. The Shipping API response XML will be returned in the message body of this HTTP response. You will then need to parse this response, using the techniques available to you in the language you are using. The elements returned in the response for both call types (Saved Settings and XML settings) are specified in API Methods document. The details on these elements is specified in the API Schema document. After you parse the response, you will then of course want to manage the data returned in whatever way is appropriate for your particular web site or application or, if an error is returned, to take the appropriate action.
The table below illustrates a generic example of the flow of information to and from the AuctionInc API server:
AUCTIONINC SERVER TASKS
|destination country & postal code||1) validate access key||ship rates for each requested service|
|item weight / dimensions / quantity|| 2) look up account configuration
|rate detail for each service|
|item declared value||3) determine best packaging||package detail for each service|
| requested carrier services
|4) call carrier APIs and calculate rates||errors returned from carrier APIs|
|5) construct response XML|
Saved Settings (SS) vs XML Settings (XS) Calls
Saved Settings-based (SS) calls require pre-configuration of shipping preferences prior to making calls, but in exchange for this additional step, some features are supported which are not available when making XML Settings (XS) calls.
Construction of XML Calls
The Request XML is made up of two main elements: the RequestHeader and the RequestBody. Both of these elements are contained within an Envelope root element. The RequestHeader contains the AccountID element, which is used to identify the caller, reference any saved preferences, and provide for accounting data. The RequestBody will contain an element for the method call (along with a version number), and inside that element additional nodes or elements will supply any necessary arguments to support the method invoked.
Sending the Request
Once the XML request has been properly constructed, it needs to be submitted to the AuctionInc Web Service utilizing standard HTTP POST protocol. The POST request should be formatted similar to the following example:
POST /websvc/shire HTTP/1.0
Connection: Close Content-Type: text/xml
Your XML String
"Saved Settings" (SS) sample XML:
"XML Settings" (XS) sample XML:
Here is an article in our knowledgebase detailing some debugging strategies, along with a form you can use to directly test the API:
Troubleshooting the Shipping Calculator API
Testing for Success
The HTTP response code should first be tested for "200 OK" to ensure that your API call was successfully invoked.
Sample Rating Response XML (Detail Level = 1):
There are two general types of errors that could occur.
Type 1 Errors indicate invalid or improperly formatted xml to make the Shipping API call. The error node will appear at the root Envelope level.
These errors need to be handled by correcting the problem and resending the XML request.
Here is a sample Type 1 Error:
Type 2 Errors are for a particular carrier service which for some reason is unable to provide rates for a given item/destination. The error node will appear inside the Carrier node. These errors can be handled by you according to your preference.
Here is a sample Type 2 Error:
Data that you will need available for your shipping rates API calls includes:
Saved Settings (SS) Calls
XML Settings (XS) Calls
|destination address||destination address|
|currency (default: USD)||currency (default: USD)|
|calculation method||calculation method|
|item origin code (optional)||item origin code (optional)|
|item quantity||item quantity|
|item lot size
|item lot size |
|item weight||item weight|
|item dimensions (optional)||item dimensions (optional)|
|units of measures for weight and dims
(defaults: lbs & inches)
unit of measures for weight and dims(defaults: lbs & inches)
|item declared value
|item declared value (optional)|
|item package method||item package method|
|supplemental item handling fee (optional)||supplemental item handling fee (optional)|
|on demand flag (optional)||carriers to rate|
|special carrier services (optional)||carrier entry points|
item fixed fee values or codes (optional)
|carrier services to rate|
supplemental item handling fee codes (optional)
|carrier services package weight maximums|
| item reference code
|carrier services package dimension maximums|
|DHL only: carrier access key & postal code (optional)|
|USPS/FedEx: flat rate packaging flag (optional)|
|special carrier services (optional)|
We have an SDK available for php (most useful for SS integrations) that you can download. This will handle the communications to and from the API, the creation of your outgoing XML and the parsing of our incoming XML. Your remaining tasks will essentially be to gather the necessary item data from the items in your cart, and to integrate the returned rates back into your cart.
We offer plugins for many popular third-party shopping carts including WooCommerce, WP eCommerce, X-Cart, Magento, and Zen Cart that integrate our SS API. These modules support virtually all of our API capabilities, and greatly enhances the capability of the native shopping carts to provide accurate comparative calculated shipping. You can learn more about our plugin modules here.
Coding for XS calls requires data collection from your sellers so that you can include that data in your calls. The four general data categories are: