Specifying Shipping Types and Costs

Subtopics

Mixing Shipping Types

Specifying Flat Rate Shipping

Specifying Calculated Shipping

Package Dimensions and Weight

Specifying Freight Shipping

UPS Rate Scales

Search Results and Shipping Costs

Mixing Shipping Types

In offering multiple shipping services, sellers can mix different shipping types (for example, Flat or Calculated) depending on the circumstances, as follows:

All domestic and international shipping services offered by the seller must be the same shipping type, specified by one field, Item.ShippingDetails.ShippingType. However, for eBay US and for Motors Parts and Accessories, a seller can select one shipping type for all domestic shipping services, and a different type for all international shipping services. The ShippingType values CalculatedDomesticFlatInternational and FlatDomesticCalculatedInternational exist for this reason. (See also InternationalShippingServiceOptionsType and ShippingServiceOptionsType.) Which input properties are required and which tags are returned in the realm of shipping depends on whether the seller selected flat rate or calculated shipping, and on whether domestic or international shipping services have been offered.

With the Global Shipping Program, the international shipping provider determines the shipping parameters for the international leg.

The international leg of the Global Shipping Program is always considered to be a calculated shipping type, and it is entirely the responsibility of the international shipping provider.

If Global Shipping is available for an item, and the seller chooses to provide the Flat shipping type domestically for that item, the Finding API's findItemsAdvanced call will return the shippingType field with a value of FlatDomesticCalculatedInternational to account for both legs of the shipment.

If the seller offers the item with Calculated domestic shipping, this field will return a value of Calculated, which also accounts for both legs of the shipment. For a purely domestic shipment, you can ignore the information about the international leg.

Specifying Flat Rate Shipping

Set ShippingDetails.ShippingType to Flat.

Specify the domestic and international shipping services. If any international shipping services are specified, at least one domestic shipping service must be specified. The seller can specify up to four domestic shipping services and up to five international shipping services from which the buyer may choose.

Flat Rate Freight: Sellers (on the eBay US site only) can provide the convenience and predictability of free or flat rate domestic shipping to buyers of heavy and bulky items by offering the Flat Rate Freight shipping service. Sellers negotiate the actual shipping cost with their preferred freight carrier separately from the checkout process, so the sale can be completed quickly. To offer Flat Rate Freight, set ShippingDetails.ShippingServiceOptions.ShippingService to FlatRateFreight.

Flat Rate Freight has a flat-rate cost model, but is obviously a bit different than standard flat rate shipping. See Specifying Freight Shipping for more information about freight shipping services.

Use ShippingServicePriority to note the seller's preference for sequence of display of the corresponding shipping service relative to the other services (1 = first in list).

Set the base shipping cost and the cost for shipping additional items, if fitting.

To learn how total shipping cost is calculated using these values, see UPS Rate Scales.

For details about the individual fields, see the eBay Trading API Reference (for example, in AddItem):

eBay Trading API Reference

Maximum Flat Rate Shipping Cost

For some categories, eBay imposes a maximum on the shipping cost that a seller can specify for the first domestic flat rate shipping service.

In most cases, the maximum shipping cost depends only upon the category in which the listing is being created. The key element in such a case is MaxFlatShippingCost.

Call GetCategoryFeatures periodically (but not with every listing) to establish a database of facts about maximum flat rate shipping cost per site and per category and per shipping service. (See GetCategoryFeatures documentation to learn the basic use of this call.) Here is how to interpret the response of GetCategoryFeatures regarding maximum flat rate shipping cost:

Once you know the maximum, you can test your seller's proposed total shipping cost to ensure it does not exceed the maximum shipping cost.

Using Shipping Rate Tables

On certain eBay sites, sellers can configure flat shipping rate tables in My eBay Shipping Preferences. These tables can then be applied to individual listings using the Trading API. Shipping rate tables enable sellers to tailor the flat shipping rates offered for an item to fit the shipping destination. They can specify a base rate for a country or an international region, then specify alternative rates or surcharges for shipping to more distant or inconvenient areas within the country or individual countries within the region.

You can use the API to apply a shipping rate table to a listing, but to set up, modify or retrieve the contents of the table, sellers must use the eBay web site. Currently, sellers can configure and apply one domestic rate table and one international rate table. For more information about configuring rate tables, see the Specifying your shipping costs and locations help page.

Domestic Rate Tables

Domestic shipping rate tables are available on the eBay US, UK, DE, AU, and Motors Parts and Accessories web sites. In a domestic shipping rate table, the seller can specify an alternative shipping rate for each shipping service category, in each of several domestic regions. For example, in the UK the shipping service categories are Economy, Standard and Express. In the US, they are Economy, Standard, Expedited and One-day.

Sellers use a dropdown list to specify the alternative shipping rates applied by the rate table as one of the following:

This selection applies to the entire table; there is no mixing and matching by region or shipping category.

The first row of the table's collapsible Domestic Regions section is the base region, which by default includes all domestic locations. The additional rows identify each of the more distant or inconvenient (extended) regions of the country to which the seller might also wish to ship. For example, in the UK these extended regions include Northern Ireland, the Scottish Highlands, and several different islands and island groups. In the US, the extended regions are Alaska and Hawaii, US Protectorates, and Army/Fleet Post Offices.

International Rate Tables

International shipping rate tables are available on the eBay US, UK, and DE sites. International rate tables work in much the same way as domestic rate tables. The seller can specify an alternative shipping rate for each shipping service category, in each of several international regions. The shipping service categories are Economy, Standard and Express.

Sellers use a dropdown list to specify the alternative shipping rates applied by the rate table as one of the following:

This selection applies to the entire table; there is no mixing and matching by region or shipping category.

The international rate table has nine top-level base regions: Africa, Asia, Central America and Caribbean, Europe, Middle East, North America, Oceania, Southeast Asia, and South America. Unlike in the domestic rate table, each base region is entirely comprised of its extended regions (countries). For example, the Southeast Asia base region consists of these extended regions: Brunei Darussalam, Cambodia, Hong Kong, Indonesia, Laos, Macau, Malaysia, Philippines, Singapore, Taiwan, Thailand, and Vietnam.

Configuring Shipping Rate Tables

When a seller enters or modifies a rate in a given shipping service category for a base region, that entry is automatically copied to all of its extended regions in the same category. The seller can then modify any of the extended region values in that category.

When any extended region rate is changed, the base region rate is replaced with a reminder that the rates in that category (table column) are now specific to each extended region. Upon saving the table, if a value had previously been entered for the base position, that value is restored.

The rates entered in a shipping rate table replace (if a flat amount) or increase (if a surcharge) the shipping costs that were specified for the respective categories in the listing to which the table is applied.

The alternative rates specified in the table for a given shipping service category take effect only if the seller has offered a shipping service in that category for the listing. If a buyer is located in a region for which an alternative shipping rate was entered, that rate will be shown to the buyer.

Rates specified in the shipping rate table for a given region take effect only if the seller has not excluded that region, and only to the extent that the region has a rate specified in the table for a shipping service category that is offered in the listing. If the seller configures and applies a rate table that has no rate entered in any offered shipping service category for a particular region, and does not exclude the region, buyers in that region will be instructed to contact the seller for shipping costs and services.

Managing Rate Tables with the API

For listings made using the Trading API, use the Item.ShippingDetails.RateTableDetails container in the Add/Relist/Revise family of API calls to specify the DomesticRateTable or InternationalRateTable to use. Currently, sellers can define only one domestic and one international rate table, and the only applicable value of DomesticRateTable or InternationalRateTable is Default, which indicates that the currently defined table will be used. Both the domestic and international tables can be applied at the same time.

To get a list of the available domestic and international shipping locations, call GeteBayDetails with DetailName set to ShippingLocationDetails.

To specify the use of shipping rate tables with an item listing:

  1. Call GetUser to ensure that the seller has configured the desired rate table on the eBay web site (User.SellerInfo.DomesticRateTable = true or User.SellerInfo.InternationalRateTable = true).
  2. Using the Add/Relist/Revise family of calls, for Item.ShippingDetails.RateTableDetails, specify the value Default for the DomesticRateTable or InternationalRateTable field to apply that rate table to the listing. To stop using the rate table with the listing, provide an empty <DomesticRateTable /> or <InternationalRateTable /> element.
  3. Specify flat rate shipping as you normally would, as described in Specifying Flat Rate Shipping.
  4. If you are applying a shipping rate table that specifies a surcharge by weight, you must specify the item weight in the ShippingDetails.CalculatedShippingRate container's WeightMajor and WeightMinor fields, even though this is a flat rate listing. Do not use any other fields in the ShippingDetails.CalculatedShippingRate container because those are not supported in this scenario. Be aware that there is currently no way to determine through the API whether a seller's rate table specifies a surcharge by weight, so your application must make it clear to the seller that item weight must be supplied if the seller has specified a surcharge by weight.

    Remember that any value in the WeightMinor field is rounded UP to the next unit, that is, to the next pound or kilogram, when the shipping cost is calculated, so make sure you message your users appropriately. One way to do this kind of UI messaging is the way the US eBay site does it, by presenting sellers with a pulldown of weight ranges, where the pulldown lists, for example, 0 lb to 1 lb as one selection (1 lb), over 1 lb to 2 lbs as another selection (2 lbs), over 2 lbs to 3 lbs as another selection (3 lbs) and so on. However, your application can ask for and use specific weights (WeightMajor and WeightMinor) if you wish.

    If the required weight values are not supplied in ShippingDetails.CalculatedShippingRate, a default weight of one unit (1 lb or 1 kg, depending on locale) is used as the basis for the surcharge. Currently the weight values used in this scenario are not returned by GetItem or GetItemShipping, although the values can be seen by the seller in the eBay UI.

    For more information, see Package Dimensions and Weight.
  5. Exclude any region to which the seller does not wish to ship even though that region has a service level and rate set up in the applied domestic or international shipping rate table. For example, a US seller might normally ship to Alaska and have Alaska shipping rates set up in the domestic rate table. However, if an item is too heavy and the shipping costs are too expensive, you can exclude Alaska for this item via the ShippingDetails.ExcludeShipToLocation field.

Specifying Calculated Shipping

Set ShippingDetails.ShippingType to Calculated.

Specify the domestic and international shipping services. If any international shipping services are specified, at least one domestic shipping service must be specified. The seller can specify up to four domestic shipping services and up to five international shipping services from which the buyer may choose. Use ShippingServicePriority to note the seller's preference for sequence of display of the corresponding shipping service relative to the other services (1 = first in list).

You should not attempt to set the base shipping cost (e.g. via ShippingServiceCost) because the base shipping cost is determined by eBay for the shipping service that the buyer selects from among the choices the seller has provided. (See Shipping Carriers and Services.)

If the seller wishes to add packaging/handling costs, set CalculatedShippingRate.PackagingHandlingCosts. See Packaging and Handling Cost.

The sites which support domestic and international calculated shipping are United States, Canada, Canada France, and Australia.

Package dimensions and weight are required for some combinations of package type and shipping service on some sites. See Package Dimensions and Weight.

For details about the individual fields, see the eBay Trading API Reference (for example, in AddItem).

Package Dimensions and Weight

For calculated shipping, and for shipping based on a rate table that specifies weight-based surcharges.

Note: With the Global Shipping Program, the dimensions, weight and package type are required for calculated shipping on the domestic leg of the shipment; you can optionally provide these values for flat rate domestic shipping as well.

Measurement Units

The sites which support domestic and international calculated shipping are United States, Canada, Canada France, and Australia.

To specify the unit type of the weight and dimensions of a package, include Item.ShippingDetails.CalculatedShippingRate.MeasurementUnit in the call input. For best practice, use MeasurementUnit. Specifying MeasurementUnit and measurementSystem will cause the measurementSystem attribute to be ignored. The available options per site are:

If no MeasurementUnit is specified, the default will be used.

The Global Shipping Program is currently supported on the eBay US and UK sites. The unit type of measurement for Global Shipping packages (with either calculated or flat shipping) defaults to the United States value, US, but you can set the measurement unit using Item.ShippingPackageDetails.MeasurementUnit.

Dimensions

The dimensions of a package are expressed with the following fields:

These support the unit and measurementSystem attributes. The unit attribute is optional and is understood to be in (whole inches). The measurementSystem attribute is optional and is understood to be English. At this time, the only supported unit is whole inches.

The following would represent a package that is 3" x 8" x 8".

<PackageDepth>3</PackageDepth>

<PackageLength>8</PackageLength>

<PackageWidth>8</PackageWidth>

Or, more formally:

<PackageDepth unit="in">3</PackageDepth>

<PackageLength unit="in">8</PackageLength>

<PackageWidth unit="in">8</PackageWidth>

or even:

<PackageDepth unit="in" measurementSystem="English">3</PackageDepth>

<PackageLength unit="in" measurementSystem="English">8</PackageLength>

<PackageWidth unit="in" measurementSystem="English">8</PackageWidth>

Developer impact: UPS requires dimensions on all UPS Air packages or Ground packages that are 3 cubic feet or larger, if they are to provide correct shipping cost. If package dimensions are not included for an item listed with calculated shipping, the shipping cost returned will be an estimate based on standard dimensions for the defined package type. eBay enforces a dimensions requirement on listings so that buyers receive accurate calculated shipping costs.

Weights

The shipping weight of an item (or set of items shipped together) is expressed with CalculatedShippingRate.WeightMajor and CalculatedShippingRate.WeightMinor. These support the unit and measurementSystem attributes. The unit attribute is optional and is understood to be the lbs (pounds) for WeightMajor and oz (ounces) for WeightMinor. The measurementSystem attribute is optional and is understood to be English.

The following would represent a package weight of 5 lbs 2 oz:

<WeightMajor>5</WeightMajor>

<WeightMinor>2</WeightMinor>

Or, more formally:

<WeightMajor unit="lbs">5</WeightMajor>

<WeightMinor unit="oz">2</WeightMinor>

Or even:

<WeightMajor unit="lbs" measurementSystem="English">5</WeightMajor>

<WeightMinor unit="oz" measurementSystem="English">2</WeightMinor>

Dimensions, Weight and Package Type for Global Shipping

Because the Global Shipping measurement system defaults to US, you might need to include measurement system and unit attributes with the dimensions and weight fields for the eBay UK implementation.

Global Shipping Package Dimensions

To specify the dimensions of a Global Shipping package, include values in whole units (for example, inches in the US) for the following fields in the call input:

Global Shipping Package Weight

To specify the shipping weight of a Global Shipping package, include values in the following fields:

For the eBay US site, the unit value for WeightMajor defaults to lbs (whole pounds), and for WeightMinor it defaults to oz (whole ounces). For example, the following represents a package weight of 5 lbs 2 oz:

<WeightMajor>5</WeightMajor>

<WeightMinor>2</WeightMinor>

Global Shipping Package Type

To specify the type of package being shipped via the Global Shipping, include values for the following fields in the call input:

ShippingIrregular is a boolean type. Set its value to true to indicate that the package is irregular and therefore cannot go through the stamping machine at the shipping service office, and thus requires special or fragile handling. Otherwise, set its value to false.

ShippingPackage is an enumerated type. Specify a value that appropriately describes the nature of the package.

When Package Dimensions and Weight are Required

For calculated shipping, package dimensions are required for irregular large packages or for packages of type LargePackage or if the shipping service is a UPS air service.

Dimensions or weight (or both) are required for certain combinations of package type and shipping service. You will need to evaluate certain data from GeteBayDetails to determine whether dimensions are required for a listing. On those eBay sites that support calculated shipping (US, CA, AU, eBay Motors Parts and Accessories), this applies only to domestic shipping. For the API, this applies to domestic and international shipping for the US, CA and AU sites and eBay Motors Parts and Accessories.

With the Global Shipping Program, package dimensions and weight are always required for calculated domestic shipping.

About the Elements for Dimensions and Weight Requirement

The difference in the two "package" container names: ShippingServicePackageDetails has "Service" in its name while ShippingPackageDetails does not. ShippingServicePackageDetails is about packages in the context of a particular service. ShippingPackageDetails is about packages in general.

ShippingServicePackageDetails.DimensionsRequired is a characteristic of a package type in the context of a particular shipping service.

DimensionsSupported is a characteristic of a type of package. There is no connection between it and individual shipping services.

(Trivia: DimensionsSupported will be true for a package type on a particular site if dimensions are required for that package type for any service on that eBay site. Also, if DimensionsSupported is false for a particular package type on that eBay site, ShippingServicePackageDetails.DimensionsRequired will be false for that package type for all services that support that package on that eBay site.)

Using the Elements for Dimensions and Weight Requirement

If the eBay site supports calculated shipping, use GeteBayDetails to determine whether package dimensions or weight are required for shipping services associated with that site. Call GeteBayDetails with one DetailName set to ShippingPackageDetails and with another DetailName set to ShippingServiceDetails.

If ShippingServicePackageDetails.DimensionsRequired is true, a seller who selects that package and service combination for a listing must submit PackageWidth, PackageLength and PackageDepth in the item definition for the listing.

If DimensionsSupported is true, a seller is allowed to provide package dimensions and eBay will store the seller-supplied dimensions, even if dimensions are not required by whatever service is ultimately selected by the buyer.

It is a best practice to always provide dimensions for a package, even if a particular combination of package type and selected shipping service does not require dimensions. This enables eBay and its shipping affiliates to be most accurate in its shipping cost calculations.

If ShippingServicePackageDetails.WeightRequired is true, a seller who selects that package and service combination for a listing must specify WeightMajor and WeightMinor in the item definition for the listing.

Examples

Scenario 1: Let's say that DimensionsSupported is true for the LargePackage package type for a particular site. And let's say that, for shipping services named S1 and S2, ShippingServicePackageDetails.DimensionsRequired is true for LargePackage. In this situation, the seller must provide dimensions.

Scenario 2: Let's say that DimensionsSupported is true for the Package package type for a particular site. And let's say that, for the shipping service named S1, ShippingServicePackageDetails.DimensionsRequired is false for Package. Further, for the shipping service named S2, ShippingServicePackageDetails.DimensionsRequired is true for Package.

In this case, if the seller only offers service S1, the seller can offer the Package option for service S1 and is not required to provide dimensions. (If the seller chooses to provide dimensions, eBay stores those dimensions and uses them for shipping cost calculations if the buyer selects service S1.)

In order for the seller to offer shipping service S2 for the Package package type, the seller must provide package dimensions.

Therefore, if the seller offers both services S1 and S2 and selects the Package option, the seller must provide package dimensions (to satisfy service S2's requirement).

Scenario 3: Let's say that DimensionsSupported is false for the package type Letter. And let's say that ShippingServicePackageDetails.DimensionsRequired is false for the Letter package type for all shipping services that the seller offers. In this case, dimensions are not needed at all; it would be best for the seller to not provide dimensions.

Scenario 4: Let's say that ShippingServicePackageDetails.WeightRequired is true for one of the shipping services offered by the seller and false for the rest. In this case, the seller must provide weight details for the item to satisfy that one service's requirement for weight details.

Specifying Freight Shipping

Freight shipping may be required if the items to be shipped exceed a particular weight. Freight shipping solutions exist only for the US, UK, Australia, Canada and Canada (French) sites, and only for domestic shipping.

Sellers can choose one of the following freight shipping solutions for each listing:

When using the Trading API's Add, Relist, Revise, or Verify calls to create a listing, the combination of ShippingDetails.ShippingType and ShippingDetails.ShippingServiceOptions.ShippingService fields is unique for each eBay site and freight shipping option, as follows:

API field values for Freight shipping

SiteFreight TypeShippingType valueShippingService value
USFreightQuote.comn/a (Web only)n/a (Web only)
USFlat Rate FreightFlatFlatRateFreight
USOther freight serviceFreightFlatFreight
UKCourierFreightFlatCourier
AUFreightFreightFlatAU_Freight
CA/CAFRFreightFreightFlatCA_Freight

The following table outlines the events and actions needed to offer each type of freight shipping for a listing.

Specifying Freight shipping via web site and API

Freight optionWeb solutionAPI solution
US site: To choose FreightQuote.com as the freight shipping service...What seller does: - selects dropdown option Freight (instead of Flat or Calculated or No Shipping) - selects FreightQuote.com.

What eBay does: - sets ShippingType to Freight - sets ShippingService to FreightShipping - sets shipping cost according to FreightQuote.com's calculation.		(None)
US site: To specify Flat Rate Freight shipping...What seller does: - selects dropdown option Flat (instead of Freight or Calculated or No Shipping) - selects Flat Rate Freight from the Services dropdown - selects Free shipping or enters a shipping Cost greater than 0. The seller also selects other features related to flat rate shipping in the Web UI.

What eBay does: - sets ShippingType to Flat - sets ShippingService to FlatRateFreight, and implements the seller's other selections.		What your code does: - sets ShippingType to Flat - sets ShippingService to FlatRateFreight.

Your code also applies other flat rate shipping settings, such as shipping cost. For details, see Specifying Flat Rate Shipping.
US site: To specify "Other freight service"...What seller does: - selects dropdown option Freight (instead of Flat or Calculated or No Shipping) - selects Other freight service.

What eBay does: - sets ShippingType to FreightFlat - sets ShippingService to Freight.		What your code does: - sets ShippingType to FreightFlat - submits an empty ShippingServiceOptions container - (optional and recommended) alters the item description to note that the seller and buyer will work out the shipping cost details outside of eBay.

What eBay does: - sets ShippingService to Freight - sets shipping cost to 0; it is up to the seller and buyer to work out the cost.
UK site: To specify courier shipping...What seller does: - selects dropdown option Courier (instead of Flat or No Shipping).

What eBay does: - sets ShippingType to FreightFlat - sets ShippingService to Courier.		(The details here are the same as for the US "Other freight service" above except for the name "Courier".) What your code does: - sets ShippingType to FreightFlat - submits an empty ShippingServiceOptions container - (optional and recommended) alters the item description to note that the seller and buyer will work out the shipping cost details outside of eBay

What eBay does: - sets ShippingService to Courier - sets shipping cost to 0; it is up to the seller and buyer to work out the cost
Australia site: To specify freight shipping...What seller does: - selects dropdown option Freight (instead of Flat or No Shipping).

What eBay does: - sets ShippingType to FreightFlat - sets ShippingService to AU_Freight.		(The details here are the same as for the US "Other freight service" above except for the name "AU_Freight".) What your code does: - sets ShippingType to FreightFlat - submits an empty ShippingServiceOptions container - (optional and recommended) alters the item description to note that the seller and buyer will work out the shipping cost details outside of eBay.

What eBay does: - sets ShippingService to AU_Freight - sets shipping cost to 0; it is up to the seller and buyer to work out the cost
Canada (English and French) site: To specify freight shipping...What seller does: - selects dropdown option Freight (instead of Flat or No Shipping).

What eBay does: - sets ShippingType to FreightFlat - sets ShippingService to CA_Freight.		(The details here are the same as for the US "Other freight service" above except for the name "CA_Freight".) What your code does: - sets ShippingType to FreightFlat - submits an empty ShippingServiceOptions container - (optional and recommended) alters the item description to note that the seller and buyer will work out the shipping cost details outside of eBay.

What eBay does: - sets ShippingService to CA_Freight - sets shipping cost to 0; it is up to the seller and buyer to work out the cost

UPS Rate Scales

Two rate scales are available for shipping when shipping is done via UPS:

Sellers identify which type of UPS rates they use by setting a preference on the Payment and Shipping Preferences web page. The selected rate type is indicated on the eBay web site in the Shipping Calculator. It is seen in the API in ShippingRateType.

ShippingRateType is only returned if the value in ShippingServiceOptions.ShippingService is a UPS shipping service. If ShippingRateType has a value of DailyPickup on input and no UPS shipping service is used, there is no shipping costs reduction.

Search Results and Shipping Costs

The pages that eBay displays upon search can include details about shipping cost.

The shipping cost text displayed as a result of search will be "Not specified" if all of the following are true:

If an item's shipping costs are specified in the item description, you should set ShippingTermsInDescription to true when creating or revising a listing so that users of search on the eBay web site will see something to the effect of "shipping terms in description" in the section about shipping costs.

For eBay Motors vehicles (but not for Parts and Accessories), passing ShippingTermsInDescription with a value of true has the same effect as setting BuyerResponsibleForShipping to false: the Search results page displays the shipping cost as "See description."