AuctionInc Shipping API 

XML Schema

This document details the XML request & response schema used by the AuctionInc Shipping Rates API. Theses schemas are combined in composite schemas that make up the dataset necessary for each method.

Various methods in the API can optionally utilize predefined configuration settings referred to as Saved Settings (SS). These values are managed through the AuctionInc web site in the Settings menu and provide additional options for the shipping and packaging methods for accounts making SS calls. The documentation indicates when these preferences are required with an [SS] notation.

Request Schema

Carrier Schema

The Carrier schema appears in the request XML of the XS method to indicate which carriers will be included in the ratings.

Carrier Schema Example:

Service Schema

The Service schema appears as a sub-element within the Carrier schema  in the request XML of the XS method to indicate which carrier services should be rated.

Service Schema Example:

<ServiceList>
   <Service code="USPMM">
     <PkgMaxWeight>50</PkgMaxWeight>
        <OnDemand>true</OnDemand> 
     </Service>
   <Service code="USPPM" />
</ServiceList>

DestinationAddress Schema

The DestinationAddress represents the geographic destination location  for the shipment.

Destination Address Example:

<DestinationAddress>
   <ResidentialDelivery>true</ResidentialDelivery>
   <CountryCode>US</CountryCode>
   <PostalCode>90210</PostalCode> 
   <StateOrProvinceCode>CA</StateOrProvinceCode>
</DestinationAddress>

Item Schema

The Item schema is used in various request schemas and represents an object with physical, monetary, and shipping characteristics.

Item Schema Example:

<Item> 
   <RefCode>keyboard-101e</RefCode>
   <Quantity>2</Quantity >
   <CalcMethod Code="C">
   <CarrierCalcProps> 
          ...
   </CarrierCalcProps>
   </CalcMethod>
</Item>

CarrierCalcProps Schema

The CarrierCalcProps schema to represent various characteristics of an item relevant to a Carrier Calculation Method.

CarrierCalcProps Schema Example:

<CarrierCalcProps>
   <Weight>2.5</Weight>
   <WeightUOM>LBS</WeightUOM> 
   <Length>6</Length>
   <Width>4</Width>    
   <Height>3</Height>
   <DimUOM>IN</DimUOM>
   <DeclaredValue>18.50</DeclaredValue>
   <PackMethod>T</PackMethod>
   <SpecialServices>
         ...
   </SpecialServices>
   <OriginCode>CA-WHS&l t;/OriginCode>
   <SuppHandlingFee>10</SuppHandlingFee>
</CarrierCalcProps>

FixedCalcProps Schema

The FixedCalcProps schema  represent various characteristics of an item relevant to a Fixed Calculation Method.

FixedCalcProps Schema Example:

<FixedCalcProps>
   <FeeType>F</FeeType>
   <Fee1>3.00</Fee1> 
   <Fee2>2.50</Fee2>
</FixedCalcProps>

OR

<FixedCalcProps>
   <FeeType>C</FeeType>
   <FeeCode>PictureFee</FeeCode>
</FixedCalcProps>

OnDemandServices Schema

On Demand Services qualify an item to be rated for the indicated on-demand carrier service.   

OnDemandServices Schema Example:

<OnDemandServices>
   <ODService>USPMM</ODService>
   <ODService>USPBPM</ODService> 
</OnDemandServices>

SpecialServices Schema

Special services apply additional fees to packages to account for the cost of extra services offered by the carrier, such as Proof of Delivery, additional handling,
hazardous package handling, etc.

SpecialServices Schema Example:

<SpecialServices>
   <AddlHandlingUPS>true</AddlHandlingUPS>
   <AddlHandlingFDX>true</AddlHandlingFDX> 
   <Hazard>true</Hazard>
</SpecialServices>

OriginAddress Schema

The OriginAddress represents the address location from which the shipment will originate from (XS calls) Multiple OriginAddress schemas may be included if items in the shipment have multiple shipping origin locations.

Multiple origin addresses are often used in conjunction with on-demand services, to account for different carrier services supported by different origins. In these cases, the services shared by all origins will be rated. If there are no shared services, a "mixed" service rate is constructed and returned which accrues the least expensive service available from each origin.

Element Name	SS Calls	XS Calls	Data Type	Max Size	Version	Description
OriginCode		X	xs:string	20	1.0	Origin Codes provide the functionality to connect each of multiple items in a shipment to different origin addresses. This user-defined code "names"  the addresses included in the OrginAddress schema (XS).  Reference to this defined code at the item level connects each item to a particular origin.  Not needed if you are using a single origin address for your shipment. (Optional)
CountryCode		X	xs:string	2	1.0	The country code from where the shipment will originate. For a list of country codes see Appendix F.
PostalCode		X	xs:string	11	1.0	The Postal Code from where the shipment will originate.
StateOrProvinceCode		X	xs:string	2	1.0	The State or Province Code from where the shipment will originate. Only required when origination is from USA or Canada.

OriginAddress Schema Example:

<OriginAddress>
   <OriginCode>CA-WHS</OriginCode>       
   <CountryCode>US</CountryCode>
   <PostalCode>90210</Postal Code>
   <StateOrProvinceCode>CA</StateOrProvinceCode>
</OriginAddress>

<OriginAddress>
   <OriginCode>MA-RST</OriginCode>       
   <CountryCode>US</CountryCode>
   <PostalCode>01609</Postal Code>
   <StateOrProvinceCode>MA</StateOrProvinceCode>
</OriginAddress>

...then link your items to your OriginCode:

<Item>
   <RefCode>Instruction Book</RefCode>
   <Quantity>1</Quantity>
   <CalcMethod code="C">
     <CarrierCalcProps>
         ...
      <OriginCode>CA-WHS</OriginCode>
         ...
     </CarrierCalcProps>
   </CalcMethod>
</Item>

Response Schema

ShipRate Schema

A ShipRate schema appears in AuctionInc's response for the ship rate methods. The detail returned is dependent upon the Detail Level indicated in the rating call.
Higher detail levels include all the information provided in lower detail levels.

Detail Level = 1:  Summary rate data for the service 
Detail Level = 2:  Rate component breakdown for each rate
Detail Level = 3:  Packaging detail for each rate

Element Name	SS Calls	XS Calls	Data Type	Max Size	Detail Level	Version	Description
Valid	X	X	xs:string	5	1	1.0	Indicates if rate engine was successful in computing the shipping rate of the carrier service. Possible values: true/false
CarrierCode	X	X	xs:string	10	1	1.0	Rated Carrier Code. (see Appendix C).
ServiceCode	X	X	xs:string	10	1	1.0	Rated Carrier Service Code. (see Appendix D).
ServiceName	X	X	xs:string	30	1	1.0	Rated Carrier Service Name. (see Appendix D)
CalcMethod	X	X	xs:string	1	1	1.0	Method that the shipping calculator used determine rate for this carrier service. Possible values are:  C (calculated)  F (fixed)  M (mixed)  CUSTOM (SS Response only)
Rate	X	X	xs:decimal	6.2	1	1.0	Total rate for this carrier service for all packages in shipment.
ErrorList	X	X	Error Schema Collection		1	1.0	The presence of this element indicates that rating for the carrier service failed and will contain one or more Error Schema datasets that identify the cause of the error(s).
CarrierRate	X	X	xs:decimal	6.2	2	2.0	Aggregate of the base rates returned from carrier APIs for all packages in shipment.
FixedRate	X	X	xs:decimal	6.2	2	2.2	Aggregate of the fixed rates returned by our rating engine for all packages in shipment. Returned only if fixed rates are used for one or more items.
Surcharges	X	X	xs:decimal	6.2	2	2.0	Aggregate of the surcharges for all packages in shipment.
FuelSurcharges	X	X	xs:decimal	6.2	2	2.0	Aggregate of the fuel surcharges for all packages in shipment (not all carriers report this seperately from surcharges).
HandlingFees	X		xs:decimal	6.2	2	2.0	Aggregate of the handling fees calculated for all packages in shipment.  Calculated for SS calls only.
DeclaredValue	X	X	xs:decimal	6.2	2	2.0	Aggregate of the value for all items in shipment
InsuranceCharges	X	X	xs:decimal	6.2	2	2.0	Aggregate of the insurance calculated for all packages in shipment.
Weight	X	X	xs:decimal	6.2	2	2.0	Total weight for all packages in shipment (LBS).
PackageCount	X	X	xs:integer	3	2	2.0	Number of packages constructed by AuctionInc shipping engine.
FlatRateCode	X	X	xs:string	5	2	2.1	For USPS & FEDEX services which support flat rate packaging, identifies if one or more packages in the shipment has qualified for a flat rate.  This element will only be returned if a) the appropriate configuration setting has been enabled (SS calls) or 2) the FlatRatePackaging element has been set in the call (XS calls). Item dimensions must be included in your API call for AuctionInc to attempt to qualify the items. Possible values are: SFRB = USPS Small Flat Rate Box  (size limit of: 8-5/8 x 5-3/8 x 1-5/8) FRB1 = USPS Flat Rate Box One (size limit of: 11 x 8-1/2 x 5-1/2) FRB2 = USPS Flat Rate Box Two (size limit of: 11-7/8 x 3-3/8 x 13-5/8) LFRB = USPS Large Flat Rate Box (size limit of: 12 x 12 x 5-1/2) FRE = USPS Flat Rate Envelope (size limit of: 12 x 9 x .5) 10KG = FEDEX 10KG Flat Rate Box (size limit of: 15.81 x 12.94 x 10.19 ) (weight limit of 22 LBS) 25KG = FEDEX 25KG Flat Rate Box (size limit of: 21.56 x 16.56 x 13.19) (weight limit of 55 LBS) NONE = no flat rate box or envelope MULTIPLE = multi-package shipment for which at least two packages in the shipment qualify for different flat rate codes for a particular carrier service (use Detail Level = 3 to display the oversize code for each package)  Additional information: USPS Flat Rate Boxes USPS Flat Rate Envelopes FEDEX Flat Rate Packages
PackageDetail	X	X	Package Schema Collection		3	2.1	One or more Package schema which provides details on each of the packages created by our packaging engine.

ShipRate Example #1 (Detail Level = 1)

<ItemShipRate>
    <Currency>USD</Currency>
    <ShipRateList>
       <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>USPS</CarrierCode>
         <ServiceCode>USPPM</ServiceCode>
         <ServiceName>USPS Priority Mail</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>11.50</Rate>
      </ShipRate>
      <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>UPS</CarrierCode>
         <ServiceCode>UPSGND</ServiceCode>
         <ServiceName>UPS Ground</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>11.30</Rate>
      </ShipRate>
      <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>UPS</CarrierCode>
         <ServiceCode>UPS2ND</ServiceCode>
         <ServiceName>UPS 2 Day</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>27.47</Rate>
      </ShipRate>
   </ShipRateList>
</ItemShipRate>

ShipRate Example #2 (Detail Level = 2)

<ItemShipRate>
    <Currency>USD</Currency>
    <ShipRateList>
       <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>USPS</CarrierCode>
         <ServiceCode>USPPM</ServiceCode>
         <ServiceName>USPS Priority Mail</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>11.50</Rate>
         <CarrierRate>9.80</CarrierRate>
         <Surcharges>0.00</Surcharges>
         <FuelSurcharges>0.00</FuelSurcharges>
         <HandlingFees>0.00</HandlingFees>
         <DeclaredValue>19.95</DeclaredValue>
         <InsuranceCharges>1.70</InsuranceCharges>
         <Weight>10.00</Weight>
         <PackageCount>1</PackageCount>
         <FlatRateCode>FRB1</FlatRateCode>
      </ShipRate>
      <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>UPS</CarrierCode>
         <ServiceCode>UPSGND</ServiceCode>
         <ServiceName>UPS Ground</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>11.30</Rate>
         <CarrierRate>10.81</CarrierRate>
         <Surcharges>0.00</Surcharges>
         <FuelSurcharges>0.49</FuelSurcharges>
         <HandlingFees>0.00</HandlingFees>
         <DeclaredValue>19.95</DeclaredValue>
         <InsuranceCharges>0.00</InsuranceCharges>
         <Weight>10.00</Weight>
         <PackageCount>1</PackageCount>
      </ShipRate>
      <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>UPS</CarrierCode>
         <ServiceCode>UPS2ND</ServiceCode>
         <ServiceName>UPS 2 Day</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>27.47</Rate>
         <CarrierRate>24.20</CarrierRate>
         <Surcharges>0.00</Surcharges>
         <FuelSurcharges>3.27</FuelSurcharges>
         <HandlingFees>0.00</HandlingFees>
         <DeclaredValue>19.95</DeclaredValue>
         <InsuranceCharges>1.70</InsuranceCharges>
         <Weight>10.00</Weight>
         <PackageCount>1</PackageCount>
      </ShipRate>
   </ShipRateList>
</ItemShipRate>

ShipRate Example #3 (Detail Level = 3)

<ItemShipRate>
    <Currency>USD</Currency>
    <ShipRateList>
       <ShipRate>
         <Valid>true</Valid>
         <CarrierCode>USPS</CarrierCode>
         <ServiceCode>USPPM</ServiceCode>
         <ServiceName>USPS Priority Mail</ServiceName>
         <CalcMethod>C</CalcMethod>
         <Rate>39.67</Rate>
         <CarrierRate>30.50</CarrierRate>
         <Surcharges>2.40</Surcharges>
         <FuelSurcharges>1.67</FuelSurcharges>
         <HandlingFees>0.00</HandlingFees>
         <DeclaredValue>19.95</DeclaredValue>
         <InsuranceCharges>5.10</InsuranceCharges>
         <Weight>20.00</Weight>
         <PackageCount>2</PackageCount>
         <FlatRateCode>NONE</FlatRateCode>
         <PackageDetail>
             < Package>
              ...
            </Package>
            < Package>
            ;   ...
            </Package>
         </PackageDetail>
      </ShipRate>
   </ShipRateList>
</ItemShipRate>

Package Schema

A Package schema represents package details for the package.

Package Example:

<Package>
   <Quantity>1</Quantity>
   <PackMethod>T</PackMethod>
   <Origin>01610</Origin>
   <DeclaredValue>19.95</DeclaredValue>
   <Weight>10</Weight>
   <Length>5</Length>
   <Width>3</Width>
   <Height>4</Height>
   <OversizeCode>NONE</OversizeCode>
   <FlatRateCode>NONE</FlatRateCode>
   <CarrierRate>9.80</CarrierRate>
   <Surcharge>2.40</Surcharge>
   <FuelSurcharge>1.67</FuelSurcharge>
   <Insurance>1.70</Insurance>
   <Handling>0</Handling>
   <ShipRate>15.57</ShipRate>
   <PkgItem>
      <RefCode>keyboard-101-e</RefCode>
      <Qty>2</Qty>
      <Weight>5</Weight>
   </PkgItem>
</Package>
<Package>
   <Quantity>2</Quantity>
   <PackMethod>S</PackMethod>
   <Origin>01610</Origin>
   <DeclaredValue>19.95</DeclaredValue>
   <Weight>1</Weight>
   <Length>1</Length>
   <Width>1</Width>
   <Height>1</Height>
   <OversizeCode>NONE</OversizeCode>
   <FlatRateCode>NONE</FlatRateCode>
   <CarrierRate>10.35</CarrierRate>
   <Surcharge>0</Surcharge>
   <FuelSurcharge>0</FuelSurcharge>
   <Insurance>1.70</Insurance>
   <Handling>0</Handling>
   <ShipRate>12.05</ShipRate>
   <PkgItem>
      <RefCode>mouse</RefCode>
      <Qty>1</Qty>
      <Weight>1</Weight>
   </PkgItem>
</Package>

PkgItem Schema

The PkgItem Schema contains data on an item in the Package schema.

Element Name	SS Calls	XS Calls	Data Type	Max Size	Detail Level	Version	Description
RefCode	X	X	xs:string	1	3	2.1	Pass-thru value from the Item schema in the incoming call.
Qty	X	X	xs:string	64	3	2.1	Quantity of this item in the package
Weight	X	X	xs:string	64	3	2.1	Item weight. If pkgitem quantity > 1, this represents the value for one item.

PkgItem Schema Example:

<PkgItem>
   <RefCode>QU-510</Code>      
   <Qty>1</Qty>
    <Weight>10</Weight>
</PkgItem>

Error Schema

Element Name	SS Calls	XS Calls	Data Type	Max Size	Version	Description
Code	X	X	xs:string	1	1.0	Identifies the error that occurred. See Appendix A for error details.
Message	X	X	xs:string	64	1.0	Contains descriptive error message pertaining to the error code.
Detail	X	X	xs:string	64	1.0	One or more optional elements containing descriptive detail pertaining to the error message.
Severity	X	X	xs:string	10	1.0	Indicates the severity of the error. Possible values are: NOTICE = a non-fatal issue that may be appropriate to address. WARNING = A non-fatal error that may indicate a problem with configuration settings or missing data. CRITICAL = A fatal error that could not be handled and must be corrected.

Error Schema Example:

<Error>
     <Code>510</Code>     
     <Message>
        Packaging Engine unable to determine any services to be rated
     </Message>
     <Detail>USPPM:Item weight exceeds limit</Detail>
     <Detail>USPPP:Item weight exceeds limit</Detail>
     <Severity>CRITICAL</Severity>
</Error>