Specifying Shipping Services


Topics:

Required Domestic Shipping Service

Handling Time and Estimated Delivery Time

Enabling Get It Fast

Deprecated Shipping Services

A seller can specify up to four domestic shipping services and up to five international shipping services (or four international shipping services plus Global Shipping if the seller is enrolled in the Global Shipping Program). To get basic facts about each available shipping service, call GeteBayDetails with DetailName set to ShippingServiceDetails.

Note: The Global Shipping Program is represented by the InternationalPriorityShipping service. However, this service is not specified directly through the API. Instead, you set the value of the ShippingDetails.GlobalShipping field to true for a listing, and the international shipping service is automatically set to InternationalPriorityShipping. For more information, see Working with Shipping in API Calls.

For more information about shipping services, see Shipping Carriers and Services.

Note: For the domestic leg of a Global Shipping Program shipment, sellers can use any carrier and service that is available to them for domestic shipping in the country from which the order will ship.

Required Domestic Shipping Service

Although requirements for specified shipping vary by site, sellers are strongly encouraged to add specified shipping to all listings. If items in a category require specified shipping, then GetCategoryFeatures returns true for Category.ShippingTermsRequired.

On the Germany (DE) and Spain (ES) sites, users must specify at least one domestic shipping service.

On the US site, sellers must specify at least one domestic shipping service, and must specify if the shipping is flat or calculated. The exception is freight shipping, and if freight shipping is specified, there is not a requirement to specify the cost.

In most cases, a seller specifies one or more shipping services for flat or calculated shipping (see Specifying Flat Rate Shipping, Specifying Calculated Shipping).

Sometimes, though, a seller does not wish to (and, in certain cases, cannot) select a shipping service for a particular shipping carrier. Consider these scenarios:

Specifying Local Pickup

Local pickup is an interesting case: there is a shipping service enumeration named LocalDelivery in the same list of enumerations as the USPSPriority service. Obviously, the seller pays no shipping carrier to handle local pickup. But the eBay API mechanism is to use the "shipping service" named LocalDelivery.

If a seller does not intend to ship an item, set Item.ShippingDetails.ShippingServiceOptions.ShippingService to LocalDelivery.

Note: There is slightly different behavior on the eBay website. First time sellers listing an item through eBay website must provide at least one domestic shipping service.

Specifying Free Shipping

(For the eBay US website only.) When ShippingServiceOption.FreeShipping is set to true, the cost of shipping is zero for the first domestic shipping service (for flat or calculated shipping).

If InsuranceOption is Required and FreeShipping is true, eBay changes the insurance cost to 0 for that shipping service. But if InsuranceOption is Optional, the cost of shipping insurance remains, for it is up to the buyer whether to buy shipping insurance, regardless of whether the seller specified free shipping.

This applies to the AddItem family of calls. This element is also returned by GetItem and GetItemShipping if the first domestic shipping service was marked as FreeShipping.

Specifying Other Shipping Solutions

In rare cases, no shipping service in eBay's ShippingServiceCodeType matches what the seller wants to do. The seller can add information to the item description (Item.Description) to explain the shipping situation to bidders.

Handling Time and Estimated Delivery Time

The handling time (also known as the dispatch time) refers to the following time period:

For most item categories, sellers are required to use DispatchTimeMax (in add, relist and revise calls) to specify an item's handling time in days (a positive integer) for domestic delivery.

Note: For the Global Shipping Program, the information here about handling time is applicable. eBay calculates the total estimated delivery time by adding the seller's stated handling time (DispatchTimeMax) to the seller's estimate of the delivery time for the shipping service used for the domestic leg, plus the international shipping provider's estimate for the international leg.

DispatchTimeMax does not apply when there is no shipping, or when using local pickup only or freight shipping. For example, when ShippingService=Pickup or ShipToLocations=None, then DispatchTimeMax is not required (or it can be empty).

DispatchTimeMax also does not apply to certain listing categories such as Vehicles, Real Estate, Specialty Services and Classified Ads listings. See HandlingTimeEnabled in GetCategoryFeatures to determine exactly which categories require this field.

Note: AddItem requires that you specify a DispatchTimeMax for items listed in certain categories. Calls will fail if the required dispatch time is not specified. See the eBay Developer Newsletter and the blog for details of this policy.

For a list of allowed DispatchTimeMax values on each eBay site, use DispatchTimeMaxDetails in GeteBayDetails. Typical values are 0, 1, 2, 3, 4, 5, 10, 15, or 20, but they can vary by site and may change over time.

Same Day Handling

You can specify same day handling by setting DispatchTimeMax to 0. This means that the seller commits to shipping the packaged order by the end of the business day.

The meaning of "business day" in this context depends on the locale of the listing site and the time the cleared payment is received. Each eBay site has a default order cut off time. For orders placed (and cleared payment received) before the local order cut off time, the order must be shipped by the end of the current day. For orders completed at or after the order cut off time, the order must be shipped by the end of the following day (excluding weekends and local holidays).

For example, the default order cut off time on the eBay US site is 2:00 pm PT. An order placed on that site on a Friday by 1:59 pm PT must be shipped by the end of business that day. However, an order placed on a Friday on or after 2:00 pm PT must be shipped by the end of business the following Monday (assuming Monday is not a local holiday), and the estimated delivery is calculated from that date.

Note: If a same day shipping carrier is selected, and the carrier delivers on one or both weekend days, sellers on the eBay US site are assumed to be open for business on the same days, and those days will be used when calculating total shipping time.

The following table lists default order cut off times for each active eBay site:

Table: Default Order Cut Off Times by eBay Site
Site ID Site Code Country Detail Default Order Cut Off Time
0 US US 2 PM PT (UTC/GMT -7 hours; DST: +1 hour)
2 CA Canada 2 PM ET (UTC/GMT -5 hours; DST: +1 hour)
210 CAFR Canada (French) 2 PM ET (UTC/GMT -5 hours; DST: +1 hour)
3 UK United Kingdom 2 PM BST (No UTC/GMT offset; DST: +1 hour)
15 AU Australia 2 PM AET (UTC/GMT +10 hours; DST: +1 hour)
16 AT Austria 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
23 BE_FR Belgium (French) 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
71 FR France 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
77 DE Germany 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
100 MOTORS US Motors 2 PM PT (UTC/GMT -7 hours; DST: +1 hour)
101 IT Italy 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
123 BE_NL Belgium (Dutch) 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
146 NL Netherlands 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
186 ES Spain 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
193 CH Switzerland 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
201 HK Hong Kong 2 PM HKT (UTC/GMT +8 hours; No DST)
205 IE Ireland 2 PM IST (No UTC/GMT offset; DST: +1 hour)
207 MY Malaysia 2 PM MYT (UTC/GMT +8 hours; No DST)
211 PH Philippines 2 PM PHT (UTC/GMT +8 hours; No DST)
212 PL Poland 2 PM CET (UTC/GMT +1 hour; DST: +1 hour)
216 SG Singapore 2 PM SGT (UTC/GMT +8 hours; No DST)

You can override the default order cut off time for individual users. Use the SetUserPreferences call and specify a new cut off time for the authenticated user in DispatchCutoffTimePreference.CutoffTime. Provide the time value in Universal Coordinated Time (UTC/GMT), accounting for any difference in daylight saving time between GMT and the seller's time zone if necessary.

You can inspect the currently set order cut off time for the authenticated user by calling GetUserPreferences and setting ShowDispatchCutoffTimePreferences to true. The response returns the cut off time in DispatchCutoffTimePreference.CutoffTime.

Combining Handling and Delivery Time

Optionally, you can estimate an item's total delivery time and display it in your application. For example, you could display "Estimated delivery: 5 to 7 days" for an item. To do this, you need to know the seller's handling time as well as the estimated shipping (transit) time for the shipping service. GeteBayDetails includes an estimated transit time range for most shipping services, specified by ShippingTimeMin and ShippingTimeMax.

To present a total estimated delivery time to your users, use the following calculations:

Low end of delivery time range = DispatchTimeMax + ShippingTimeMin

High end of delivery time range = DispatchTimeMax + ShippingTimeMax + buffer

The buffer can be set by the seller, or it can be determined by your application. For example, during the holiday season, the shipping carrier may recommend that you add 1 day as a buffer. (eBay does not provide a recommended buffer.)

Exception Handling Time

If GeteBayDetails returns a true value for DispatchTimeMaxDetails.ExtendedHandling, the seller has specified a default handling time of 4 business days or more (an exception handling time) in preferences. You might want to warn the seller that long handling times might discourage potential buyers.

Enabling Get It Fast

The Get It Fast feature and icon are no longer supported in eBay listings.

Requirements for Get It Fast

The Get It Fast feature and icon are no longer supported in eBay listings.

Get It Fast Shipping Details

The Get It Fast feature and icon are no longer supported in eBay listings.

Get It Fast Handling Details

The Get It Fast feature and icon are no longer supported in eBay listings.

Related API Functions and Tags

The Get It Fast feature and icon are no longer supported in eBay listings.

Site Help for Get It Fast

The Get It Fast feature and icon are no longer supported in eBay listings.

Deprecated Shipping Services

All valid shipping services for an eBay site will be indicated by a ShippingServiceDetails.ValidForSellingFlow flag in the GeteBayDetails output. If a shipping service returned in GeteBayDetails does not contain this flag, the shipping service is no longer available/valid, and the seller can not specify this shipping service as a shipping option for buyers.

API vs Web

Response to a user selecting a deprecated service is different in the API version of the Sell/Revise/Relist Your Item flows than it is in the eBay website version.

A new API listing that offers a to-be-deprecated shipping service will not be blocked; a warning will be returned that that particular shipping service will be deprecated.

A new API listing with an already-deprecated shipping service will not be blocked; that service will automatically be mapped by eBay to the service noted in MappedToShippingServiceID, and a warning will be returned about this action.

On the eBay website, the general behavior is to inform the buyer or seller and they must decide whether to keep the current service or go with a different service. If the service has been deprecated, the user either accepts the mapped service or selects some other service.

API Specifics

In the ShippingServiceDetails container returned by GeteBayDetails for each shipping service, you find DeprecationDetails and MappedToShippingServiceID only if the shipping service will be or has been deprecated:

DeprecationDetails ( AnnouncementMessageType )

AnnouncementStartTime ( dateTime )

EventTime ( dateTime )

MessageType ( None/Deprecation/Mapping/DeprecationAndMapping )

MappedToShippingServiceID

MappedToShippingServiceID identifies the numerical id of the service that is recommended as the replacement for the deprecated shipping service.

DeprecationDetails does not contain any message about deprecation. Rather, DeprecationDetails contains information about which messages are to be made available and when. It is part of a mechanism that enables eBay to decide, per country, for example, which messages to make available at what time.

EventTime is when the event will occur, which, in this context, is when the shipping service will be deprecated. AnnouncementStartTime is when messaging can begin about the upcoming EventTime.

MessageType identifies the kind of message that eBay wishes to make available for this particular event. Options are to have no messaging related to the event, to have messaging during the to-be-deprecated period (between AnnouncementStartTime and EventTime), to have messaging during the mapping period (any time after EventTime), and to have messaging in both the deprecation and mapping periods.

(At this time, DeprecationDetails can be returned empty. This happens when GeteBayDetails.ValidForSellingFlow is false for a shipping service and the shipping service is deprecated and there is no mapping for that deprecated shipping service. Interpret an empty DeprecationDetails as if it were a message that there is no mapping for that deprecated service, for eBay will not map the service—it will simply drop the shipping service and will not return a warning message.)

Example

You call GeteBayDetails and get this information as part of the ShippingServiceDetails container for a shipping service:

AnnouncementStartTime = June 1

EventTime = July 1

MessageType = DeprecationAndMapping

MappedToShippingServiceID = 123456

MessageType is set to DeprecationAndMapping which effectively uses both the Deprecation and the Mapping enumerations. Messages are to be issued during both the deprecation and the mapping periods.

If it is before June 1, no warning is returned because the announcement period has not started. Between June 1 and July 1, a warning is returned to those who create a new listing via API that includes the to-be-deprecated shipping service. After July 1, if someone lists via API with this deprecated service, eBay maps it to service 123456 and returns a warning that this has occurred.

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.