AuctionInc Shipping Rates API: Getting Started

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.

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

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.

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.

Data Transaction Summary

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

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.

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

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:

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.0HOST: api.auctioninc.comConnection: Close Content-Type: text/xmlContent-Length: 262Your XML String

Sample XML

"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

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:

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:

INTEGRATING WITH YOUR SITE

SS and XS Required and Optional Parameters

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

unit of measures for weight and dims(defaults: lbs & inches)

item fixed fee values or codes (optional)

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)

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.

XS INTEGRATION TASKS

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

Copyright © 2024 AuctionInc. A division of PAID, Inc.

PAID, Inc. 200 Friberg Parkway Suite 4004, Westboro, MA 01581. 1-866-323-8833