Request Info
AuctionInc Live Help
  Log In
Auction Management Home Shipping Calculator Auction Tools e-Commerce Tools Auction Management Image Hosting Auction Management Affiliate Program Control Center Helpdesk


  • API XML Methods
  • API XML Schema
  • API Appendix

  • AuctionInc Shipping 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:

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

    Establish an AuctionInc Account
    All Shipping API users must first establish 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" Calls: Complete the Setup Wizard
    For customers who are planning to make Saved Settings (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


    Four Step 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, a variety of features are offered 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 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=iso-8859-1" utf-8 ?>
    <Envelope>
       <Header>
          <AccountId>your account id</AccountId>
    </Header> <Body> <GetTime version="1.0">
    </GetTime> </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 version="1.0" encoding="utf-8" ?>
    <Envelope>
     <Header>
          <AccountId>your account id</AccountId>
     </Header>
     <Body>
          <GetItemShipRateSS version="2.3">
    <DetailLevel>1</DetailLevel>
    <Currency>USD</Currency>
    <DestinationAddress>
                <ResidentialDelivery>true</ResidentialDelivery>
                <CountryCode>US</CountryCode>
                <PostalCode>90210</PostalCode>
                <StateOrProvinceCode>CA</StateOrProvinceCode >
          </DestinationAddress>
        <ItemList>
           <Item>
                 <RefCode>keyboard-101</RefCode>
                 <Quantity>2</Quantity>
                 <CalcMethod code="C">
                       <CarrierCalcProps>                             
                             <Weight>4</Weight>
                             <WeightUOM>LBS</WeightUOM>
                             <DeclaredValue>59.95</DeclaredValue>
                            <PackMethod>T</PackMethod>
                       </CarrierCalcProps>
                 </CalcMethod>
           </Item>
        </ItemList>
     </GetItemShipRateSS>
     </Body>
    </Envelope>


    "XML Settings" (XS) sample XML
    :
     
    <?xml version="1.0" encoding="utf-8" ?>
    <Envelope>

    <Header>
      <AccountId>your account id</AccountId>
     </Header>
     <Body>
      <GetItemShipRateXS version="2.3">

    <DetailLevel>1</DetailLevel>
        <Currency>USD</Currency>
        <CarrierList>
             <Carrier code="UPS">
                  <EntryPoint>P</EntryPoint>
                  <ServiceList>
                       <Service code="UPSGND">
    <PkgMaxWeight>50</PkgMaxWeight>
                          <PkgMaxLength>20</PkgMaxLength>
    <PkgMaxWidth>20</PkgMaxWidth>
    <PkgMaxHeight>10</PkgMaxHeight>
    </Service>
    <Service code="UPSNDA">
                          <PkgMaxWeight>50</PkgMaxWeight>
                          <PkgMaxLength>20</PkgMaxLength>
    <PkgMaxWidth>20</PkgMaxWidth>
    <PkgMaxHeight>20</PkgMaxHeight>
                       </Service>
                 </ServiceList>
             </Carrier>
             <Carrier code="USPS">
                  <EntryPoint>R</EntryPoint>
    <FlatRatePackaging>ENV</FlatRatePackaging>
    <ServiceList>
                       <Service code="USPEXP" />
                       <Service code="USPMM">
                          <PkgMaxWeight>15</PkgMaxWeight>
                          <PkgMaxLength>10</PkgMaxLength>
    <PkgMaxWidth>10</PkgMaxWidth>
    <PkgMaxHeight>8</PkgMaxHeight>
                       <OnDemand>true</OnDemand>
    </Service>
                  </ServiceList>
             </Carrier>
        </CarrierList>
        <OriginAddressList>
             <OriginAddress>
                  <OriginCode>MA-RTS</OriginCode>
                  <CountryCode>US</CountryCode>
                  <PostalCode>01610</PostalCode>
                  <StateOrProvinceCode>MA</StateOrProvinceCode>
             </OriginAddress>
             <OriginAddress>
                 <OriginCode>CA-WHS</OriginCode>     
                 <CountryCode>US</CountryCode>
                 <PostalCode>90210</PostalCode>
                 <StateOrProvinceCode>CA</StateOrProvinceCode>
            </OriginAddress>
        </OriginAddressList>
        <DestinationAddress>
            <ResidentialDelivery>true</ResidentialDelivery>
             <CountryCode>US</CountryCode>
             <PostalCode>90210</PostalCode>
             <StateOrProvinceCode>CA</StateOrProvinceCode >
        </DestinationAddress>
        <ItemList>
             <Item>
                  <RefCode>Compact Disk</RefCode>
                  <Quantity>2</Quantity>
                  <CalcMethod  code="C">
                       <CarrierCalcProps>
    <Length>2</Length>
                            <Width>10</Width>
                            <Height>2.5</Height>
                            <DimUOM>IN</DimUOM>
                            <Weight>4</Weight>
                            <WeightUOM>LBS</WeightUOM>
                            <DeclaredValue>59.95</DeclaredValue>
                            <PackMethod>T</PackMethod>
    <OriginCode>MA-RTS</OriginCode>
    <OnDemandServices>
    <ODService>USPMM</ODService>
    </OnDemandServices>
    </CarrierCalcProps>
                  </CalcMethod>
             </Item>
             <Item>
                  <RefCode>Instruction Book</RefCode>
                  <Quantity>1</Quantity>
                  <CalcMethod code="C">
                       <CarrierCalcProps>
                            <Length>6</Length>
                            <Width>1</Width>
                            <Height>8</Height>
                            <DimUOM>IN</DimUOM>
                            <Weight>1.5</Weight>
                            <WeightUOM>LBS</WeightUOM>
                            <DeclaredValue>29.95</DeclaredValue>
                            <PackMethod>S</PackMethod>
    <OriginCode>CA-WHS</OriginCode>
    <OnDemandServices>
    <ODService>USPMM</ODService>
    </OnDemandServices>
    </CarrierCalcProps>
                  </CalcMethod>
             </Item>
        </ItemList>
    </GetItemShipRateXS>
    </Body>
    </Envelope>



    Debugging Your API Calls

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

    <?xml version="1.0" encoding="utf-8" ?>
    <Envelope> <Header>
    <Date>2008-10-28 19:53:14 GMT</Date>
    </Header> <Body>
    <ItemShipRate>
          <Currency>USD</Currency>
            <ShipRateList>
             <ShipRate>
                <Valid>1</Valid>
                  <CarrierCode>USPS</CarrierCode>
                  <ServiceCode>USPSPM</ServiceCode>
                  <ServiceName>PriorityMail</ServiceName>
                  <CalcMethod>C</CalcMethod>

                  <Rate>48.26</Rate>
               </ShipRate>
               <ShipRate>
                <Valid>1</Valid>
                  <CarrierCode>UPS</CarrierCode>
                  <ServiceCode>UPSGND</ServiceCode>
                  <ServiceName>Ground</ServiceName>
                  <CalcMethod>C</CalcMethod>

                  <Rate>31.21</Rate>
                </ShipRate>
          </ShipRateList>
       </ItemShipRate>
    </Body>
    </Envelope>


     

    • 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=iso-8859-1" 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=iso-8859-1" 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></Carrier> <Rate></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.

    WooCommerce Plug-In Module
    We offer a free plug-in module for WooCommerce on the wordpress platform that integrates our SS API. The module supports virtually all our API capabilities, and greatly enhances the capability of your WooCommerce cart to provide accurate comparative calculated shipping. You can learn more about our plug-in module here.

    Zen Cart Extension Module
    We offer a free add-on module for your Zen Cart that integrates our SS API. The module supports virtually all our API capabilities, and greatly enhances the capability of Zen Cart to provide accurate comparative calculated shipping. You can learn more about our Zen Cart module 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.




      Home | About Us | Contact Us | Partnerships | User Agreement | Privacy Policy