AuctionInc Shipping Rates API 
XML Schema

Request Schemas

Response Schemas


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 Schemas

Carrier Schema (XS only)

Subset of CarrierList and appears in the request XML of the XS method to indicate which carriers will be included in the ratings.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

Code

 

X

xs:string

10

1.0

Attribute value indicating the carrier code (see Appendix C).

EntryPoint

 

X

xs:string

2

1.0

The entry point indicates the method used to deliver the  packages to the carrier. (see Appendix E)

ServiceList

 

X

Service Schemas Collection


 

List of the carrier services to be rated (see Appendix D).

AccessKey
(DHL only)

 

X

xs:string

20

1.0

Your DHL account ID (for account rates). If not present, DHL "list" rates will be returned. 

(Optional, for DHL only)

AcctCountryCode
(DHL only)

 

X

xs:string

2

2.4

The account country code which correlates to the DHL Account ID (for account rates). Required when the AccessKey is optionally included, but if not present, will default to the Origin Address country code. 

(Optional, for DHL only)

PostalCode
(DHL only)
(Deprecated June 2013)

 

X

xs:string

5

1.0

The account postal code which correlates to the DHL Account ID, required when the AccessKey is optionally included.

 (Deprecated June 2013: no longer needed when submitting the DHL AccessKey)

FlatRatePackaging
(optional:
USPS & FEDEX only)

 

X

xs:string

5

2.1

USPS & FEDEX provide various flat rate packaging options using their pre-paid boxes & envelopes. These products support USPS Priority and Express (both domestic and international) and FEDEX International Priority services. This flag allows you to request that AuctionInc attempt to qualify, for each appropriate service, your items into each eligible flat rate product, in turn from smallest to largest. (The items must both fit and not exceed any weight limit for the particular product.)  If your USPS Entry Point is Commercial Base, packages will also be tested for fit into the Regional flat rate boxes for (domestic) Priority Mail. 

In all cases qualification means that a) item dimensions have been provided in the API for all items in the package; b) the items in the shipment fit; c) the weight of the package is not greater than any weight limit for the flat rate product; and d) the cost of the fitted flat rate product is less expensive than the regular calculated rate for the same service. (Please take note this final test; a comparison of the product's cost is made with the regular calculated rate.) If all these tests are passed, the underlying service (USPS Priority, Express, or FedEx Priority) will be priced at the appropriate flat rate, and the appropriate code will be returned in the ShipRate schema indicating if and which flat rate product qualified.

If the USPS Entry Point is Commercial Base, the lowest-price option for Priority Mail will be selected from among the weight-based calculated rate, the retail flat rate boxes, and the commercial base flat rate boxes.

Valid values are:

FEDEX:

  • PKG (packages)

USPS:

  • PKG (packages)
  • ENV (envelopes)
  • ALL (both packages & envelopes will be considered for qualification, including, if the entry point indicates eligibility, regional boxes)

Additional information:

USPS Flat Rate Boxes
USPS Flat Rate Envelopes
FEDEX Flat Rate Packages

(Optional, and utilized for USPS & FEDEX only)

Carrier Schema Example:


<CarrierList>
    <Carrier code="UPS">
        <EntryPoint>D</EntryPoint>
        <ServiceList>
            <Service code="UPSWEP">
                <PkgMaxWeight>25</PkgMaxWeight>
            </Service>
            <Service code="UPSWSV">
                <PkgMaxWeight>25</PkgMaxWeight>
            </Service>
        </ServiceList>
    </Carrier>
    <Carrier code="DHL">
        <EntryPoint>P</EntryPoint>
        <AccessKey>12345678</AccessKey>
        <ServiceList>
            <Service code="DHLWPE" />
            <Service code="DHL9AM" />
        </ServiceList>
    </Carrier>
    <Carrier code="USPS">
        <EntryPoint>R</EntryPoint>
        <FlatRatePackaging>PKG</FlatRatePackaging>
        <ServiceList>
            <Service code="USPPMI" />
            <Service code="USPEMI">
                <OnDemand>true</OnDemand>
            </Service>
        </ServiceList>
    </Carrier>
</CarrierList>

Service Schema (XS only)

One or more Service schema make up the ServiceList, a sub-element within the Carrier schema  in the request XML of the XS method to indicate which carrier services should be rated.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

Code

 

X

xs:string

10

1.0

Attribute value indicating the carrier service code (see Appendix B).

PkgMaxWeight

 

X

xs:decimal

3.2

2.1

Sets the maximum weight of the package for the service. When packaging multiple items with PackMethod = "T", this value, if present, will be used instead of the service's maximum weight as established by the carrier. (The weight must be less than the carrier's maximum weight for the service, or it will be ignored.)  If packaging a single item with a weight exceeding this value, this value is ignored.

(Optional)

PkgMaxLength

 

X

xs:decimal

4.2

2.3

Sets the maximum length of the package for the service (the three dimensions are interchangeable). When packaging multiple items with PackMethod = "T", this value, if present, will be used to calculate total box volume for this service, and if this calculated volume is less than the maximum service volume established by the carrier, it will be used to determine volume splits.Splits will also occur if any item dimension exceeds the largest package dimension, or if the sum of the smallest dimension for each item exceeds the largest package dimension. If packaging a single item with a dimension exceeding this value, this value is ignored.

(Optional)

PkgMaxWidth

 

X

xs:decimal

4.2

2.3

Sets the maximum width of the package for the service (the three dimensions are interchangeable). When packaging multiple items with PackMethod = "T", this value, if present, will be used to calculate total box volume for this service, and if this calculated volume is less than the maximum service volume established by the carrier, it will be used to determine volume splits. Splits will also occur if any item dimension exceeds the largest package dimension, or if the sum of the smallest dimension for each item exceeds the largest package dimension. If packaging a single item with a dimension exceeding this value, this value is ignored.

(Optional)

PkgMaxHeight

 

X

xs:decimal

4.2

2.3

Sets the maximum height of the package for the service (the three dimensions are interchangeable). When packaging multiple items with PackMethod = "T", this value, if present, will be used to calculate total box volume for this service, and if this calculated volume is less than the maximum service volume established by the carrier, it will be used to determine volume splits.Splits will also occur if any item dimension exceeds the largest package dimension, or if the sum of the smallest dimension for each item exceeds the largest package dimension.  If packaging a single item with a dimension exceeding this value, this value is ignored.

(Optional)

OnDemand

 

X

xs:boolean

5

2.0

Restrict our shipping engine to only calculating shipping rates for this service if all of the items in a given package are flagged to indicate that they qualify for this service. (This is especially useful for content-restricted services such as  USPS Media Mail; also used if shipping from different origins, each of which supports different carrier services.)

(Optional, default=false)

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.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

ResidentialDelivery


X

X

xs:boolean

5

1.0

Set to true if the delivery address is going to a residential address. Most carriers charge additional fees for delivering to residential addresses. Possible values: true/false

(Optional, default=true)

CountryCode

X

X

xs:string

2

1.0

The country code to where the shipment will be delivered. For a list of country codes see Appendix F.

PostalCode

X

X

xs:string

11

1.0

The Postal Code to where shipment will be delivered. (Not required for countries that do not use postal codes.)

StateOrProvinceCode

X

X

xs:string

2

1.0

The State or Province Code to where the shipment will be delivered. Only required when destination is to USA or Canada.

Destination Address Example:


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

Item Schema

One or more Item schema make up the ItemList, representing an object with physical, monetary, and shipping characteristics.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

RefCode

X

X

xs:string

128

1.0

User-definable item code that is passed thru to the Packaging Detail (Detail Level = 3) of the reply ShipRate schema

(Optional)

Quantity

X

X

xs:integer

8

1.0

Quantity of the item to be packaged.

(optional, default=1)

CalcMethod

X

X

xs:element

2

1.0

This element contains the attribute code that indicates the method that the shipping calculator should use to determine shipping. Each calculation method has its own schema for the appropriate attributes (except free shipping items). The CalcMethod element will contain the appropriate schema as indicated below. Items in the shipment may utilize carrier rates and/or fixed fees (including, for SS calls, fixed fee codes) or offer free shipping. See our Knowledgebase article for the business logic employed when these calculations methods are mixed together.

The "CI" CalcMethod will quote free rates for domestic destinations (relative to the shipping origin address) and carrier rates for international destinations.

Code
Calc Method Schema
C
Carrier Rates CarrierCalcProps
CI
Free Domestic /
Carrier Rates Intl
CarrierCalcProps
F
Fixed Fee FixedCalcProps
N
No Charge (free) none

Item Schema Example:


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

CarrierCalcProps Schema

The CarrierCalcProps schema, subset of the Item schema, represents various characteristics of an item relevant to a calculation method of Carrier Rates.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

Weight

X

X

xs:decimal

5.4

1.0

Weight of item (required)

WeightUOM

X

X

xs:string

3

1.0

Unit of measure associated with the item weight. Possible values include:

  • LBS = Pounds
  • OZ = Ounces
  • KGS = Kilograms

(Optional, default = LBS)

Length

X

X

xs:decimal

6.2

1.0

Length dimension of individual item (the three item dimensions are interchangeable).
(Optional, but dimensions will be utilized only if all three are sent)

Width

X

X

xs:decimal

6.2

1.0

Width dimension of individual item (the three item dimensions are interchangeable).
(Optional, but dimensions will be utilized only if all three are sent)

Height

X

X

xs:decimal

6.2

1.0

Height dimension of individual item (the three item dimensions are interchangeable).
(Optional, but dimensions will be utilized only if all three are sent)

DimUOM

X

X

xs:string

2

1.0

Dimension unit of measure. Possible values include:

  • IN = Inches (default)
  • CM = Centimeters

LotSize

X

X

xs:integer

6

1.0

Number of units an item breaks into (with each unit typically packed seperately). This property simplifies shipping calculations for a product that consists of multiple units (i.e., four tires). Primarily used with units that are packed separately; when setting Item PackMethod to "S" in conjunction with lot size > 1, each item unit will be packed seperately. When setting lot size > 1, set the weight/dims to those of the item unit rather than the item.

(Optional, default=1)

DeclaredValue

X

X

xs:decimal

6.2

1.0

Insurable value of the item (expected currency is that set in the Currency element).  For XS calls carrier insurance will be calculated based on this value; your inclusion of a nonzero value will result in carrier insurance, if available for the service, being calculated and added to the shipping rate.  For SS calls your configured insurance thresholds and other insurance settings will be utilized to determine if insurance is added. 

For SS calls, this value is also used to determine applicability of any configured Shipping Promotions.

PackMethod

X

X

xs:string

1

1.0

Indicates if this item should be packaged seperately by our packaging engine, or whether it is combinable with other items from the same origin (or origin code, if you are assigning them) that are also flagged as packagable together. Possible values are:

  • T = Together with other items
  • S = Separately

Important Note: For items that are packaged seperately, item weight and dimensions should be that of the package rather than the item. (For SS calls, any Packaging Weight settngs will be ignored for items packaged seperately.)

OnDemandServices

X

X

OnDemandServices Schema Collection
 

2.0

List of on-demand carrier services to be applied to the package containing this item. See OnDemandServices schema.  All the items in the package must be qualified for the service for it to be rated.

(Optional)

SpecialServices

X

X

Special Services Schema Collection
 

2.0

List of special services to be applied to the package containing this item. See SpecialServices schema.

(Optional)

OriginCode

X

X

xs:string

20

2.0

This user-defined code either refers to configured origin codes set up in account preferences (SS) or to addresses included in the OriginAddress schema (XS).  Links this item to the origin address defined by the code.  Use OriginCode if the items in your shipment are originating in different ship locations. Can also be used to group items together that are packageable with each other but not with other items.

(Optional)

SuppHandlingFee

X

X

xs:decimal

6.2

2.0

A handling fee that is applied at the item level (expected currency is that set in the Currency element). (For SS calls, this fee will supplement your configured package and/or order level fees.) The fee is applied for each unit of quantity of the item.

(Optional)

SuppHandlingCode

X

 

xs:string

20

2.0

This user-defined code references configured supplemental item-level handling codes set up in account preferences (SS).

(Optional)  (SS only)

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</OriginCode>
    <SuppHandlingFee>10</SuppHandlingFee>
</CarrierCalcProps>

FixedCalcProps Schema

The FixedCalcProps schema, subset of the Item schema,  represents various characteristics of an item relevant to a calculation method of Fixed Fee.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

FeeType

X

X

xs:string

1

1.0

Identifies which values are used to calculate the fixed fee. Use either fee1 and fee2 OR FeeCode, but not both. Possible values are:

  • F = Fees 1 & 2
  • C = Fee Code (SS method only)

Fee1

X

X

xs:decimal

6.2

1.0

Fixed fee applied to first item.
(Expected currency is that set in the Currency element.)

Fee2

X

X

xs:decimal

6.2

1.0

Fixed fee applied to additional fixed fee items or when quantity of the fixed fee item > 1. When there is more than one fixed fee item in package, the largest fee1 is applied first, and then fee2 for the additional items.  If you do not set Fee2, it will default to your Fee1 value.

(Expected currency is that set in the Currency element.)

(Optional, default=Fee1)

FeeCode

X

 

xs:string

20

2.0

References stored Fixed Fee Codes in the account preferences which allow for greater flexibility of Fixed Fees. Fees can be based on geography and also allows for setting unique fixed fees for each carrier or carrier service.

(Optional)
(SS method only)

OriginCode

 

X

xs:string

20

2.1

Required if XS API call is submitting multiple origin address schemas; in this case all items, including fixed fee items, need to be linked to one of the origin codes defined in your origin address schemas.

(Optional)
(XS method only)

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

The OnDemand Services schema, subset of the CarrierCalcProps schema, qualifies an item to be rated for the indicated on-demand carrier service.   

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

ODService

X

X

xs:string

10

2.0

Carrier Services code which qualifies this item for a service which has been set to on-demand. All items in the package must be flagged as on-demand for same service for the service to be rated for the package. 

If multiple items are being rated from different ship origins, rating engine will rate all services shared by all resulting packages. If there are no shared services, a "mixed" service rate will be constructed by accruing the cost of the least expensive service supported by each package.

OnDemandServices Schema Example:


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

SpecialServices Schema

The SpecialServices schema, subset of the CarrierCalcProps schema,  applies 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.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Version

Description

AddlHandling

X

X

xs:boolean

5

2.0

Apply additional handling charges to ship rates of all supporting carriers. Possible values: true/false

AddlHandlingUPS

X

X

xs:boolean

5

2.0

Apply additional handling charges to UPS ship rates. For more info read here. Possible values: true/false

AddlHandlingDHL

X

X

xs:boolean

5

2.0

Apply additional handling charges to DHL ship rates. For more info read here. Possible values: true/false

AddlHandlingFDX

X

X

xs:boolean

5

2.0

Apply additional handling charges to Fedex ship rates. For more info read here. Possible values: true/false

Hazard

X

X

xs:boolean

5

2.0

Indicate that this package qualifies as hazardous content for all carriers. Possible values: true/false

HazardUPS

X

X

xs:boolean

5

2.0

Indicate that this package qualifies as hazardous content for UPS. For more info read here. Possible values: true/false

HazardDHL

X

X

xs:boolean

5

2.0

Indicate that this package qualifies as hazardous content for DHL. For more info read here. Possible values: true/false

HazardFDX

X

X

xs:boolean

5

2.0

Indicate that this package qualifies as hazardous content for Fedex. For more info read here. Possible values: true/false

SignatureReq

X

X

xs:boolean

5

2.0

Apply additional charge for signature required for all supporting carriers. Possible values: true/false

SignatureReqUPS

X

X

xs:boolean

5

2.0

Apply additional charge for signature required for UPS. For more info read here. Possible values: true/false

SignatureReqDHL

X

X

xs:boolean

5

2.0

Apply additional charge for signature required for DHL. For more info read here. Possible values: true/false

SignatureReqFDX

X

X

xs:boolean

5

2.0

Apply additional charge for (indirect) signature required for FedEx. For more info read here. Possible values: true/false

SignatureReqUSP

X

X

xs:boolean

5

2.0

Apply additional charge for signature required for USPS. For more info read here. Possible values: true/false

UPSAdultSignature

X

X

xs:boolean

5

2.0

Apply additional charge for adult signature required for UPS. For more info read here. Possible values: true/false

DHLAdultSignature

X

X

xs:boolean

5

2.0

Apply additional charge for adult signature required for DHL. For more info read here. Possible values: true/false

FDXAdultSignature

X

X

xs:boolean

5

2.0

Apply additional charge for adult signature required for FedEx. For more info read here. Possible values: true/false

DHLPrefSignature

X

X

xs:boolean

5

2.0

Apply additional charge for signature preferred for DHL. For more info read here. Possible values: true/false

FDXDirectSignature

X

X

xs:boolean

5

2.0

Apply additional charge for direct signature required for FedEx. For more info read here. Possible values: true/false

FDXHomeCertain

X

X

xs:boolean

5

2.0

Apply additional charge for home date certain delivery for FedEx Home Delivery (FDXHD) carrier service. For more info read here. Possible values: true/false

FDXHomeEvening

X

X

xs:boolean

5

2.0

Apply additional charge for home evening delivery for FedEx Home Delivery (FDXHD) carrier service. For more info read here. Possible values: true/false

FDXHomeAppmnt

X

X

xs:boolean

5

2.0

Apply additional charge for home appointment delivery for FedEx Home Delivery (FDXHD) carrier service. For more info read here. Possible values: true/false

Pod

X

X

xs:boolean

5

2.0

Apply additional charge for proof of delivery for all supporting carriers. Possible values: true/false

PodUPS

X

X

xs:boolean

5

2.0

Apply additional charge for proof of delivery for UPS. For more info read here. Possible values: true/false

PodDHL

X

X

xs:boolean

5

2.0

Apply additional charge for proof of delivery for DHL. For more info read here. Possible values: true/false

PodFDX

X

X

xs:boolean

5

2.0

Apply additional charge for proof of delivery for FedEx. For more info read here. Possible values: true/false

PodUSP

X

X

xs:boolean

5

2.0

Apply additional charge for proof of delivery for USPS. For more info read here. Possible values: true/false

UPSDelivery

X

X

xs:boolean

5

2.0

Apply additional charge for delivery confirmation for UPS. For more info read here. Possible values: true/false

USPCertified

X

X

xs:boolean

5

2.0

Apply additional charge for certified delivery for USPS. For more info read here. Possible values: true/false

USPRestricted

X

X

xs:boolean

5

2.0

Apply additional charge for restricted delivery for USPS. For more info read here. Possible values: true/false

USPDelivery

X

X

xs:boolean

5

2.0

Apply additional charge for delivery confirmation for USPS. For more info read here. Possible values: true/false

USPReturn

X

X

xs:boolean

5

2.0

Apply additional charge for return receipt for USPS. For more info read here. Possible values: true/false

USPReturnMerchandise

X

X

xs:boolean

5

2.0

Apply additional charge for return receipt for merchandise for USPS. For more info read here. Possible values: true/false

USPRegistered

X

X

xs:boolean

5

2.0

Apply additional charge for registered mail for USPS. For more info read here. Possible values: true/false

IrregularUSP

X

X

xs:boolean

5

2.0

Indicate that this package qualifies for the USPS dimensional weighting discount for irregularly-shaped items. When set to true, must be used in conjunction with PackMethod = "S" to be valid.For more info read here. Possible values: true/false

SpecialServices Schema Example:


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

OriginAddress Schema (XS only)

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.

Items that have different origin addresses are separated by our packaging engine so that they can never be packed together with items across different origins, but can be packed with each other. You can take advantage of this functionality to group items that are packageable together within their group but not with other groups for any reason, not just due to origin. Just use origin addresses in the same postal zone (i.e, next town over) so that the shipping rates due to orgin will be the same. 

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.

Our Packaging Engine will sort all items from unique OriginCodes and package them seperately from items from differing OriginCodes.

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


<OriginAddressList>
    <OriginAddress>
        <OriginCode>CA-WHS</OriginCode>
        <CountryCode>US</CountryCode>
        <PostalCode>90210</PostalCode>
        <StateOrProvinceCode>CA</StateOrProvinceCode>
    </OriginAddress>
    <OriginAddress>
        <OriginCode>MA-RST</OriginCode>
        <CountryCode>US</CountryCode>
        <PostalCode>01609</PostalCode>
        <StateOrProvinceCode>MA</StateOrProvinceCode>
    </OriginAddress>
</OriginAddressList>

...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 Schemas (SS & XS)

Header Schema

Element Name

Data Type

Max Size

Version

Description

Date

 xs:string

 

128

1.0

Current DateTime


ItemShipRate Schema

Element Name

Data Type

Max Size

Version

Description

Currency

xs:string

3

1.0

Currency associated to the monetary elements in the results.

ErrorList

Error Collection


1.0

The presence of this element indicates that the API call failed and will contain one or more Error Schema datasets that identify the cause of the error(s).  See Appendix A.

ShipRateList

ShipRate Collection


1.0

A collection of ShipRate elements that represent each carrier service that was rated by method.


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)
  •  N (no charge)
  •  M (mixed)
     non-intersecting services from multiple origins;
     Detail  Level 2 specifies service rated per package
  •  CUSTOM (SS Response only)
     currently returned for Delivery & Pickup services
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. If your USPS Entry Point is Commercial Base, packages will also be tested for fit into the Regional flat rate boxes. Testing for "Cubic" fit will also occur ("SS" calls) if this option is selected along with a Commercial Plus Entry Point.

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 .75)
  • REG-A1 = USPS Regional Flat Rate Box
    (size limit of: 10 x 7 x 4-3/4 )
  • REG-A2= USPS Regional Flat Rate Box
    (size limit of: 12-13/16 x 10-15/16 x 2-3/8)
  • REG-B1 = USPS Regional Flat Rate Box
    (size limit of: 12 x 10-1/4 x 5)
  • REG-B2= USPS Regional Flat Rate Box
    (size limit of: 15-7/8 x 14-3/8 x 2-7/8)
  • REG-C = USPS Regional Flat Rate Box
    (size limit of: 14-3/4 x 11-3/4 x 11-1/2)
  • 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)
  • CUBIC = USPS Cubic Pricing
  • 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.

Element Name

SS Calls

XS Calls

Data Type

Max Size

Detail Level

Version

Description

Quantity


X

X

xs:integer

8

3

2.1

Quantity of packages this package schema represents.  When packaging an item packaged seperately which has a quantity > 1, multiple identical packages will be created. In this case, this quantity figure will represent the number of identical multiple packages.

PackMethod

X

X

xs:string

1

3

2.1

The pack method for the items in this package.

CarrierService

X

X

xs:string

10

3

2.2

The carrier service rated for this package. Returned only for shipments with a MIXED service rate.

Origin

X

X

xs:string

5

3

2.1

The origin postal code for the items in this package.

DeclaredValue

X

X

xs:demical

6.2

3

2.1

The declared value of this package. If package quantity > 1, this represents the value for one package.

Weight

X

X

xs:demical

6.2

3

2.1

The weight of this package. If package quantity > 1, this represents the value for one package (lbs).

Length

X

X

xs:demical

6.2

3

2.1

The length of this package. If package quantity > 1, this represents the value for one package (inches).

Width

X

X

xs:demical

6.2

3

2.1

The width of this package. If package quantity > 1, this represents the value for one package (inches).

Height

X

X

xs:demical

6.2

3

2.1

The height of this package. If package quantity > 1, this represents the value for one package (inches).

OversizeCode

X

X

xs:string

20

3

2.1

The carrier oversize code, if any for this package. May also contain other notes.

Carriers have unique oversize codes.  Possible value include (but are not limited to):

  • NONE
  • DimWt (Package qualified by carrier to use dimensional weight for ship rate)
  • Large Pkg

For some carriers, discounted "Shipment" pricing may be calculated in some circumstances in which multiple boxes are considered as a single box for the rate calculation. In these cases, this field will contain the designation "combined" (indicating the rate for the single "package the carrier has constructed for rating), or "subset" (indicating the other actual packages that the carrier does not individually rate).

SplitCode

X

X

xs:string

2

3

2.3

Identifies the reason why a "split" to the next box was required for this service. Only included for those packages that require a split. See Appendix G.

FlatRateCode

X

X

xs:string

5

3

2.1

Identifies whether USPS services which support flat rate packaging have qualified for a flat rate. Please see FlatRateCode in the ShipRate schema for additional information.

CarrierRate

X

X

xs:demical

6.2

3

2.1

The base carrier rate for this package. If package quantity > 1, this represents the value for one package.

FixedRate

X

X

xs:demical

6.2

3

2.2

The fixed rate for this package. Returned only if fixed rate exists for this package.

Surcharge

X

X

xs:demical

6.2

3

2.1

Carrier surcharge for this package. If package quantity > 1, this represents the value for one package.

FuelSurcharge

X

X

xs:demical

6.2

3

2.1

Fuel surcharge forthis package. If package quantity > 1, this represents the value for one package. (Not all carriers report their fuel surcharge seperately from surcharges.)

Insurance

X

X

xs:demical

6.2

3

2.1

Insurance cost for this package. If package quantity > 1, this represents the value for one package>

Handling

X

X

xs:demical

6.2

3

2.1

Handling charge calculated for this package. If package quantity > 1, this represents the value for one package. Calculated for SS calls only.

ShipRate

X

X

xs:demical

6.2

3

2.1

Shipping rate for this package. Includes total of carrier rate, surcharge, fuel surcharge, insurance & handling. If package quantity > 1, this represents the value for one package.

PkgItem

X

X

PkgItem Collection

 

3

2.1

One or more PkgItem schema which identifies of the items in this package.

Package Example:


<PackageDetail>
    <Package>
        <Quantity>1</Quantity>
        <PackMethod>T</PackMethod>
        <Origin>01610</Origin>
        <DeclaredValue>19.95</DeclaredValue>
        <Weight>12</Weight>
        <Length>15</Length>
        <Width>3</Width>
        <Height>22</Height>
        <OversizeCode>NONE</OversizeCode>
        <SplitCode>CV</SplitCode>
        <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>monitor</RefCode>
            <Qty>2</Qty>
            <Weight>5</Weight>
        </PkgItem>
    </Package>
    <Package>
        <Quantity>2</Quantity>
        <PackMethod>S</PackMethod>
        <Origin>01610</Origin>
        <DeclaredValue>19.95</DeclaredValue>
        <Weight>2</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>
</PackageDetail>

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</RefCode>
    <Qty>1</Qty>
    <Weight>10</Weight>
</PkgItem>

Error Schema

The Error Schema contains error, warning or notice information that may be generated during a method call. The Error node can appear in the reply (root) level which would indicate a failed API call or at a sub-node level indicating a failure for individual services. Error schema appear only in response schemas.

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>