Working with Shipping in API Calls


Shipping is not a distinct eBay API. Shipping functionality is achieved through the use of various containers, fields, types and values within eBay's Trading API and Shopping API.

Topics:

Setting Versus Retrieving Shipping Details

Specifying Global Shipping in an Item Listing

Specifying Global Shipping-Related Item Attributes

Revising Shipping Details

Using Global Shipping Information After Checkout

Retrieving a Seller's Global Shipping Records

Setting Versus Retrieving Shipping Details

The Item container is where you specify shipping details when adding or revising a listing via the Add Item family of calls. See Managing Inventory.

Retrieving shipping details is done via such calls as GetItem, GetItemTransactions, GetItemShipping and GetOrders. See Retrieving and Modifying Data About Sold Items.

Global Shipping Program Preferences

To determine whether Global Shipping is available on the current eBay site, call GetCategoryFeatures with a FeatureID value of GlobalShippingEnabled. If SiteDefaults.GlobalShippingEnabled = true, Global Shipping is available. You can also provide a category name in the CategoryID field to determine if the specified category is eligible for Global Shipping (Category.GlobalShippingEnabled = true). For more information, see the GetCategoryFeatures call reference.

To determine if the current user has opted in to Global Shipping, call GetUserPreferences with a ShowGlobalShippingProgramPreference value of true. If OfferGlobalShippingProgramPreference = true, the caller has opted in to the Global Shipping Program. For more information, see the GetUserPreferences call reference.

To specify that the current user's new listings will enable the Global Shipping Program by default, call SetUserPreferences with GlobalShippingProgramListingPreference set to true. To determine the current state of this option, call GetUserPreferences with ShowGlobalShippingProgramListingPreference set to true. The GlobalShippingProgramListingPreference field will be returned, with a true value indicating the Global Shipping program is enabled by default for new listings. For more information, see the SetUserPreferences call reference.

To specify that a seller can offer an international shipping service to a particular country for a Global Shipping-eligible listing, call SetUserPreferences with OverrideGSPserviceWithIntlService set to true. For any Global Shipping-eligible listing, the seller-specified service will take precedence and be the listing's default international shipping option for buyers in that country, rather than the Global Shipping Program. The Global Shipping Program will still be the listing's default option for shipping to any Global Shipping-eligible country for which the seller does not specify an international shipping service.

To determine the current state of this option, call GetUserPreferences with ShowOverrideGSPServiceWithIntlServicePreference set to true. The OverrideGSPServiceWithIntlServicePreference field will be returned, with a true value indicating that OverrideGSPserviceWithIntlService = true.

Specifying Global Shipping in an Item Listing

For sellers enrolled in the Global Shipping Program, their shipping preferences include the option to offer international shipping via the program. This option's default value is Yes. The InternationalPriorityShipping service becomes the default first international shipping option for any new item listings created.

Global Shipping becomes an option the seller can offer when listing an item. To list an item with Global Shipping as an international shipping option, use any API listing call that contains the ShippingDetails.GlobalShipping field, and set its value to True. This is the only step needed to configure the international portion of shipping for the item, because the international shipping provider handles the details of that leg. The default Global Shipping Program service, InternationalPriorityShipping, is automatically set for the listing.

Listing calls that contain the ShippingDetails.GlobalShipping input field include AddFixedPriceItem, AddItem, AddItems, RelistFixedPriceItem, RelistItem, ReviseFixedPriceItem and ReviseItem.

To confirm that a listing offers Global Shipping, the Trading API's GetItem call provides the ShippingDetails.GlobalShipping output field, and the Shopping API's GetSingleItem and GetMultipleItems calls provide the Item.GlobalShipping output field.

The listed item must also meet the Global Shipping Program eligibility requirements. See Participation in the Global Shipping Program.

If the seller uses ShippingDetails.InternationalShippingServiceOption.ShippingService to specify (up to four) additional international shipping options for the same listing, Global Shipping will automatically take precedence, and International Priority Shipping will be the sole international shipping service offered to any Global Shipping-eligible buyer who views that listing. However, if the buyer or the item is determined by eBay or the international shipping provider to be ineligible for the Global Shipping Program, the other international shipping options will automatically be offered for the listing instead.

Sellers must also configure shipping settings for the domestic leg of the shipment. All of the normal domestic shipping settings are available for that leg, and sellers can use the same techniques to configure those settings as for any listing with domestic shipping.

Specifying Global Shipping-Related Item Attributes

With the Global Shipping Program, the international shipping provider makes use of two item characteristics in determining customs duty, taxes, and whether an item can be shipped to a particular country. Sellers can provide either or both of these two characteristics when listing an item. They're stored as item attributes using the Item.ItemSpecifics container that's available with most Trading API calls that create or update item listings, such as AddItem or ReviseFixedPriceItem. Each instance of Item.ItemSpecifics.NameValueList contains a name/value pair. For the Global Shipping attributes, the names are:

These two attributes are currently optional. For more information about ItemSpecifics, see Working with Custom Item Specifics.

Multiple Packages

If the shipment for an order is split into two or more packages, the Country Of Manufacture value becomes mandatory. However, in this case it's not provided in ItemSpecifics, but rather in a dedicated field, CountryOfOrigin, using the CompleteSale call. For more information, see the CompleteSale call reference.

Revising Shipping Details

If your goal is to revise shipping details for an existing listing, you should be aware that the approach for revising the listing differs from the typical approach for revising a list.

To avoid loss of shipping details, do not omit any tag when revising shipping details, even if its value does not change. Omitting shipping fields while revising an item will remove that detail from the listing.

For example, if you specify ShippingDetails when you revise or relist an item but you omit its child field InternationalShippingServiceOption, eBay will drop any international shipping services from the listing.

Note: One exception to this behavior is the boolean ShippingDetails.GlobalShipping field. If you omit this field when revising or relisting an item listing, its value will be unchanged. A listing that offers Global Shipping will continue to offer Global Shipping unless you explicitly include the GlobalShipping field with a value of false.

To find out the shipping fields present in the current listing, call GetItem and look through the Item.ShippingDetails fields in the response.

For multi-quantity Fixed Price listings, a seller can revise all shipping details of the listing (except for sales tax and for shipping type of Freight) for all unsold items. This applies to both domestic and international shipping. Checkout is not affected for those who bought items prior to the seller's shipping changes--the shipping details that were in effect at the time of purchase are used for that buyer at the time of checkout.

See also Item Changes Allowed During Revisions.

Using Global Shipping Information After Checkout

Sellers can use the GetItemTransactions, GetOrders, GetOrderTransactions or GetSellerTransactions call to retrieve a variety of information about a recent sale. Global Shipping Program information is returned in containers and fields in one the following paths:

The structure of the Global Shipping-specific containers and fields is as follows:

Example: Global Shipping Containers and Fields
<IsMultilegShipping>true<IsMultilegShipping>
<MultiLegShippingDetails>
   <SellerShipmentToLogisticsProvider>
      <ShippingServiceDetails>
         <ShippingService> </ShippingService>
         <TotalShippingCost currencyID="USD"> </TotalShippingCost>
      </ShippingServiceDetails>
      <ShippingTimeMin> </ShippingTimeMin>
      <ShippingTimeMax> </ShippingTimeMax>
      <ShipToAddress>
         ...
         <ReferenceID> </ReferenceID>
         ...
      </ShipToAddress>
   </SellerShipmentToLogisticsProvider>
</MultiLegShippingDetails>

To determine if the shipment for an order or transaction uses the Global Shipping Program, examine the boolean IsMultilegShipping field. If IsMultilegShipping is true, the shipment uses the Global Shipping Program.

To determine the seller-specified shipping service for the domestic leg, examine the ShippingService field. To determine the seller-specified shipping cost for the domestic leg, examine the TotalShippingCost field. To determine the seller-specified minimum and maximum number of shipping days for the domestic leg, examine the ShippingTimeMin and ShippingTimeMax fields.

Addressing a Global Shipping Program Shipment

The buyer's shipping address is returned in the ShippingAddress container by the Get family of transactions. However, sellers should not ship to this address; instead, they should ship the order to the international shipping provider's domestic warehouse. The international shipping provider handles the subsequent leg of the shipment.

When addressing a package for the first, domestic leg of a Global Shipping Program shipment to the international shipping provider, sellers obtain the addressing information using the GetItemTransactions, GetOrders, GetOrderTransactions or GetSellerTransactions call. In each of these calls, the output structure that contains the domestic address is MultiLegShippingDetails.SellerShipmentToLogisticsProvider.ShipToAddress.

This is the domestic address of the international shipping provider's warehouse. It includes the ReferenceID field, the value of which must be included on the package above the street address. The name of the addressee is the buyer name as shown by the Name field, for example:

Example: International Shipping Provider's Warehouse Address (US)
Casey P. Buyer
Reference #1234567890123456
1850 Airport Exchange Blvd #200
Erlanger KY 41025
Example: International Shipping Provider's Warehouse Address (UK)
Casey P. Buyer
Reference #1234567890123456
GSP Shipping Centre, 1 Langham Park
South Normanton DE55 2GF

The international shipping provider uses the ReferenceID value to retrieve the relevant details about the buyer and the order, so the shipment can be completed.

The shipping and import charges are calculated for each Global Shipping Program order, to be displayed to buyers before checkout. Because those calculations are based on sending the order as a single shipment, sellers are expected to send a single shipment.

Note: To ensure fast, smooth shipping and customs processing, sellers are strongly encouraged to ship all items belonging to an order in a single shipment. However, it might occasionally be physically impossible for a seller to send the entire order in a single shipment. If an order is sent as multiple shipments, the overall cost of shipping and import charges might increase, but sellers will not be charged for the extra cost. If in the future the use of multiple shipments becomes more prevalent, this policy is subject to change, and sellers could be held liable for the increased shipping costs.

Retrieving a Seller's Global Shipping Records

Several Trading API calls provide information about a seller's activity involving the Global Shipping Program. Following are the relevant fields returned:

GetMyeBaySelling

This call returns information about the current status of items that the seller has listed or sold under the Global Shipping Program.

For more information about these fields, see the GetMyeBaySelling call reference.

GetSellerList

This call returns information about items that the seller has listed under the Global Shipping Program.

For more information about these fields, see the GetSellerList call reference.

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.