AuctionInc Shipping Rates API: Getting Started

INTRODUCTION

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:

You can utilize the shipping rates returned from the API in the manner and presentation most appropriate for your particuar site
Web Service Providers who offer products such as shopping carts can integrate our shipping rates directly into their product
If you are an ecommerce vendor currently using a shopping cart or ecommerce storefront which you wish to continue using, utlilizing our API will allow you to offer accurate,
configurable shipping rates to your customers without having to switch to our own ShopCart product

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:

"XML Settings" (XS) based calls: Multi-Seller version
These calls do not rely on any saved shipping settings/preferences in AuctionInc; instead, all the necessary information to calculate and return accurate ratings is contained within the XML that you send to us. No configuration setup in AuctionInc is required to make XML Settings (XS) calls. This call type is appropriate for Web Service Providers, integrators, etc, as the customers of these providers do not need to interact directly with the AuctionInc site, and as multiple sellers are supported.
"Saved Settings" (SS) based calls: Single-Seller version
Ecommerce vendors may establish and save various shipping preferences in their AuctionInc account, including carrier services to rate, handling charges, discounting, and a variety of other settings. For those who wish to utilize saved settings-based (SS) calls, these pre-defined shipping preferences allow for a higher level of versatility and flexibility in customizing the shipping rates provided by your API calls, while at the same time cutting back the amount of data you need to send to us in your calls. SS calls are appropriate for our "retail" customers, who are selling on one site and integrating our rates into their ecommerce store.

TECHNICAL REQUIREMENTS

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.

BEFORE YOU START

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.

OVERVIEW OF THE API PROCESS

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.

Data Transaction Summary

The table below illustrates a generic example of the flow of information to and from the AuctionInc API server:

INPUTS	AUCTIONINC SERVER TASKS	OUTPUTS
destination country & postal code	1) validate access key	ship rates for each requested service
item weight / dimensions / quantity	2) look up account configuration (SS calls)	rate detail for each service
item declared value	3) determine best packaging	package detail for each service
requested carrier services (XS calls)	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.

These include:

Promotional Rates Discounts
Packaging Weight Factors
Third Party Insurance
Insurance Thresholds
Handling Fees
Custom Codes for Handling Fees
Custom Codes for Fixed Fees

MAKING THE API 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.

A example of the request XML construction for the GetTime method would be:

<?xml version="1.0" encoding="utf-8"?>
<Envelope>
    <Header>
        <AccountId>your account id</AccountId>
    </Header>
    <Body>
        </GetTime version="1.0">
    </Body>
</Envelope>

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
HOST: api.auctioninc.com
Connection: Close
Content-Type: text/xml
Content-Length: 262

Your XML String

Sample XML

"Saved Settings" (SS) sample XML:

"XML Settings" (XS) sample XML:

DEBUGGING

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

Managing the Response XML

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

Handling Errors

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:

<?xml version="1.0" encoding="utf-8"?>
<Envelope>
    <Header>
        <AccountId>your access key</AccountId>
    </Header>
    <Body>
        <ErrorList>
            <Error>
                <Code>560</Code>
                <Message>Invalid Account Id</Message>
                <Severity>CRITICAL</Severity>
            </Error>
        </ErrorList>
    </Body>
</Envelope>

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:

<?xml version="1.0" encoding="utf-8"?>
<Envelope>
    <Header>
        <AccountId>your access key</AccountId>
    </Header>
    <Body>
        <ItemShipRate>
            ...
            <ShipRate>
                <Valid>False</Valid>
                <CarrierCode>USPS</CarrierCode>
                <ServiceCode>USPSPP</ServiceCode>
                <ServiceName>Parcel Post</ServiceName>
                <CalcMethod>CARRIER></CalcMethod>
                </Rate>
                <ErrorList>
                    <Error>
                        <Code>710</Code>
                        <Message>Item exceeds maximum weight</Message>
                        <Severity>NOTICE</Severity>
                    </Error>
                </ErrorList>
            </ShipRate>
            ...
        </ItemShipRate>
    </Body>
</Envelope>

INTEGRATING WITH YOUR SITE

SS and XS Required and Optional Parameters

Data Retrieval

Data that you will need available for your shipping rates API calls includes:

Saved Settings (SS) Calls	XML Settings (XS) Calls
	origin address
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 (optional)	item lot size (optional)
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 (optional)	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 (optional)
item reference code (optional)	carrier services package dimension maximums (optional)
	DHL only: carrier access key & postal code (optional)
	USPS/FedEx: flat rate packaging flag (optional)
	special carrier services (optional)

PHP TOOLKIT

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.

API PLUGINS FOR THIRD-PARTY SHOPPING CARTS

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.

BEST PRACTICES

Caching
In order to keep to a minumim the number of API calls you make, you should cache the results you receive and only make additional calls if there is a change in the data to be sent.
Provide rates on demand
Instead of providing the shipping rates by default to your users, we suggest that you require the user to take a positive action, such as clicking on a "Calculate Shipping" button, in order to view rates. This will control the number of unwanted views and thus keep your frequency of API calls to a minumum.

XS INTEGRATION TASKS

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:

Ship Origin data
This is typcially simply the origin location of the seller. If you want to support drop-shipping, you will need to collect item origin for each item.
Carrier data
The carriers and carrier services that each seller wants to support. In most cases your seller will want to offer the same services for all items; however, if you want to support "on-demand" services, you will need to allow your sellers to link services to items. The private carriers charge differentially based on how the shipment is delivered to the carrier ("entry method") so this needs to be collected. We provide custom rates for DHL and require the seller's DHL account number. We support a wide variety of carrier "special services" such as Delivery Confirmation, some or all of which you may wish to support. Maximum package weight and dimensions can be optionally included; if not included, service maximum weight and dimensions will be used to determine package splits.
Item data
Data on the items in your cart, i.e., quantity, weight, optionally dimensions, optionally declared value (for insurance), along with any item-linked characteristics such as origin code or on-demand services.
Destination data
The destination country and postal code of the shipment, and whether it is a commercial or residential address.

AuctionInc Shipping Rates API: Getting Started

TABLE OF CONTENTS

Data Transaction Summary

Sample XML

Handling Errors

SS and XS Required and Optional Parameters