eBay Merchant Data APIVersion 1255
 

ShippingDetailsType

Type defining the ShippingDetails container, which contains the shipping-related details for an order line item (pre-checkout) or order (post-checkout).

IMPORTANT: To avoid loss of shipping details when revising a listing, you must include all ShippingDetails fields that were originally provided. Do not omit any tag, even if its value does not change. Omitting a shipping field when revising an item will remove that detail from the listing.

Types that use ShippingDetailsType:

Calls that use ShippingDetailsType:

Fields



AllowPaymentEdit ( boolean ) [0..1]
Not used by any call.

This field is deprecated and has been replaced by the ShippingDetails.PaymentEdited field.
See the Field Index to learn which calls use AllowPaymentEdit.

ApplyShippingDiscount ( boolean ) [0..1]
Not used by any call.

This field is deprecated.
See the Field Index to learn which calls use ApplyShippingDiscount.

CalculatedShippingDiscount ( CalculatedShippingDiscountType ) [0..1]
Not used by any call.

If a calculated shipping discount was offered for the domestic shipping services, this contains the details of the calculated shipping discount. Otherwise, it is not returned. Only returned if the calling user is the seller.
See the Field Index to learn which calls use CalculatedShippingDiscount.

CalculatedShippingRate ( CalculatedShippingRateType ) [0..1]
Details pertinent to one or more items for which calculated shipping has been offered by the seller, such as package dimension and weight and packaging/handling costs. If your call specifies a large-dimension item listed with UPS, see Dimensional Weight limit on UPS shipping services results in failure of shipping calculator.

Note: The CalculatedShippingRate container should only be used to specify values for the InternationalPackagingHandlingCosts, OriginatingPostalCode, and/or PackagingHandlingCosts fields. The rest of the fields in the CalculatedShippingRate container are used to specify package dimensions and package weight, and these values should now be specified in the ShippingPackageDetails container instead.
See the Field Index to learn which calls use CalculatedShippingRate.

ChangePaymentInstructions ( boolean ) [0..1]
Not used by any call.

Whether the seller specified payment and shipping instructions during checkout (for example, to update the details of an order). Valid for flat and calculated shipping.
See the Field Index to learn which calls use ChangePaymentInstructions.

CODCost ( AmountType (double) ) [0..1]
This dollar value indicates the money due from the buyer upon delivery of the item.

This field should only be specified in the request if 'COD' (cash-on-delivery) is a valid payment method for the site and listing category, and it is included as a PaymentMethods value in the same request.

This field is only returned if set for the listing.

To see if 'COD' is a supported payment method for a site and category, call GetCategoryFeatures, specifying the listing category ID, and including the FeatureID field set to PaymentMethods. Look for a value of 'CashOnPickup' in one of the Category.PaymentMethod fields in the response. For some eBay sites, the 'COD' enum may also get returned.
See the Field Index to learn which calls use CODCost.

DefaultShippingCost ( AmountType (double) ) [0..1]
Not used by any call.

The field is deprecated.
See the Field Index to learn which calls use DefaultShippingCost.

ExcludeShipToLocation ( string ) [0..*]
Use this field to specify an international country or region, or a special domestic location, such as 'PO Box' (in US) or 'Packstation' (in DE), to where you will not ship the associated item. Repeat this element in the call request for each location that you want to exclude as a shipping destination for your item.

Set ShipToRegistrationCountry to true to have your ExcludeShipToLocation settings applied to your listing. The locations you have excluded display in the Shipping and Handling section of your item listing.

If a buyer's primary ship-to location is a location that you have listed as an excluded ship-to location (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on your item.

The exclude ship-to location values are eBay regions and countries. To see the valid exclude ship-to locations for a specified site, call GeteBayDetails with DetailName set to ExcludeShippingLocationDetails, and then look for the ExcludeShippingLocationDetails.Location fields in the response. Repeat GeteBayDetails for each site on which you list.

This field works in conjunction with Item.ShipToLocations to create a set of international countries and regions to where you will, and will not, ship. You can list a region in the ShipToLocations field, then exclude specific countries within that region with this field (for example, you can specify Africa in ShipToLocations, yet exclude Chad with a ExcludeShipToLocation setting). In addition, if your ShipToLocations is Worldwide, you can use this field to specify both regions and countries that you want to exclude from your shipping destinations.

You can specify a default set of locations to where you will not ship in My eBay. If you create an Exclude Ship-To List, it is, by default, in effect when you list items. However, if you specify any value in this field on input, it nullifies the default settings in your Exclude Ship-To List. (If you use ExcludeShipToLocation when you list an item, you will need to list all the locations to where you will not ship the associated item, regardless of the default settings in your Exclude Ship-To List.)

Specify none in this field to override the default Exclude Ship-To List you might have set up in My eBay and indicate that you do not want to exclude any shipping locations from the respective item listing.

Note: To enable your default Exclude Ship-To List, you must enable Exclude Shipping Locations and Buyer Requirements in your My eBay Site Preferences. For details, see the KnowledgeBase Article HowTo: ExcludeShipToLocation.
See the Field Index to learn which calls use ExcludeShipToLocation.

FlatShippingDiscount ( FlatShippingDiscountType ) [0..1]
Not used by any call.

If a flat rate shipping discount was offered for the domestic shipping services, this contains the details of the flat rate shipping discount. Otherwise, it is not returned. Only returned if the calling user is the seller.
See the Field Index to learn which calls use FlatShippingDiscount.

GetItFast ( boolean ) [0..1]
Not used by any call.

This field is deprecated.
See the Field Index to learn which calls use GetItFast.

GlobalShipping ( boolean ) [0..1]
Indicates whether eBay's Global Shipping Program is offered for the listing. If the value of GlobalShipping is True, international shipping through the Global Shipping Program is available for the listing, and eBay automatically sets one of the available shipping service options to International Priority Shipping. If the value of GlobalShipping is false, the seller is responsible for specifying one or more international shipping service options if the seller is willing to ship internationally.

When calling RelistFixedPriceItem, RelistItem, ReviseFixedPriceItem or ReviseItem, you can omit this field if its value doesn't need to change.

Before using this field for a listing, ensure that the seller and the item being listed are eligible for the Global Shipping Program.
See the Field Index to learn which calls use GlobalShipping.

InsuranceWanted ( boolean ) [0..1]
Not used by any call.

Whether or not the buyer selected to pay for insurance as an option offered by the seller. This only has a value after the buyer has gone through checkout and selected the insurance preference.

Valid only on the following sites: FR and IT
See the Field Index to learn which calls use InsuranceWanted.

InternationalCalculatedShippingDiscount ( CalculatedShippingDiscountType ) [0..1]
Not used by any call.

This value is returned only if the seller is making the call. If a calculated shipping discount was offered for the international shipping services, this contains the details of the calculated shipping discount. Otherwise, it is not returned.
See the Field Index to learn which calls use InternationalCalculatedShippingDiscount.

InternationalFlatShippingDiscount ( FlatShippingDiscountType ) [0..1]
Not used by any call.

This value is returned only if the seller is making the call. If a flat rate shipping discount was offered for the international shipping services, this contains the details of the flat rate shipping discount. Otherwise, it is not returned.
See the Field Index to learn which calls use InternationalFlatShippingDiscount.

InternationalPromotionalShippingDiscount ( boolean ) [0..1]
On input, this specifies whether to offer the promotional shipping discount for the listing's international shipping services (only applicable if the seller has a promotional shipping discount in effect at the moment).

Returned on output only if the seller is making the call. This value indicates whether the promotional shipping discount is being offered for the international shipping services of this listing (if the listing is still active—this is only possible if the seller has a promotional shipping discount in effect at the moment) or whether the discount was offered at the time the listing ended.
See the Field Index to learn which calls use InternationalPromotionalShippingDiscount.

InternationalShippingDiscountProfileID ( string ) [0..1]
On input, this is the ID of the shipping discount to offer for the international shipping services (where the shipping discount is either of type FlatShippingDiscount or CalculatedShippingDiscount).

In the RelistItem and ReviseItem family of calls, you can remove the existing InternationalShippingDiscountProfileID associated with the item by supplying a value of 0 (zero).

Returned on output only if the seller is making the call. The value is the ID of the shipping discount offered and corresponds to whichever is returned: FlatShippingDiscount or CalculatedShippingDiscount.

If the user created a shipping discount profile, use InternationalShippingDiscountProfileID.
See the Field Index to learn which calls use InternationalShippingDiscountProfileID.

InternationalShippingServiceOption ( InternationalShippingServiceOptionsType ) [0..*]
Shipping costs and options related to an international shipping service. If used, at least one domestic shipping service must also be provided in ShippingServiceOptions.

If you specify multiple InternationalShippingServiceOption nodes, the repeating nodes must be contiguous. That is, you cannot insert other nodes between InternationalShippingServiceOption nodes.

All specified domestic and international shipping services must be the same shipping type (for example, Flat versus Calculated).

A seller can offer up to four domestic shipping services and up to five international shipping services. However, if the seller is opted in to the Global Shipping Program, only four other international shipping services may be offered (regardless of whether or not Global Shipping is offered for the listing).

If you specify ShippingDetails when you revise or relist an item but you omit InternationalShippingServiceOption, eBay will drop the international shipping services (except the Global Shipping Program) from the listing. This may also have unintended side effects, as other fields that depend on this data may be dropped as well. To retain the shipping services and dependent fields when you modify other shipping details, it may be simplest to specify all ShippingDetails that you still want to include in the listing.

For GetItemShipping, results are filtered: if any service is not available in the buyer's region, it is removed. If no services remain after this filtering, a warning is returned.
See the Field Index to learn which calls use InternationalShippingServiceOption.

PaymentEdited ( boolean ) [0..1]
Not used by any call.

Whether the seller allows the buyer to edit the payment amount for the order. (Sellers enable this property in their My eBay user preferences on the eBay site.)
See the Field Index to learn which calls use PaymentEdited.

PaymentInstructions ( string ) [0..1]
Not used by any call.

This free-form string field gives sellers the ability to add detailed payment instructions to their listings.
See the Field Index to learn which calls use PaymentInstructions.

PromotionalShippingDiscount ( boolean ) [0..1]
On input, this specifies whether to offer the promotional shipping discount for the domestic shipping services of this listing (only applicable if the seller has a promotional shipping discount in effect at the moment).

Returned on output only if the seller is making the call. This indicates whether the promotional shipping discount is being offered for the domestic shipping services of this listing (if the listing is still active—this is only possible if the seller has a promotional shipping discount in effect at the moment) or whether the discount was offered at the time the listing ended.
See the Field Index to learn which calls use PromotionalShippingDiscount.

PromotionalShippingDiscountDetails ( PromotionalShippingDiscountDetailsType ) [0..1]
Not used by any call.

This value is returned only if the seller is making the call. Contains details of the promotional shipping discount, if such is being offered while the listing is active or if it was offered at the time the listing ended.
See the Field Index to learn which calls use PromotionalShippingDiscountDetails.

RateTableDetails ( RateTableDetailsType ) [0..1]
This container is used to reference and apply a seller's domestic and/or international shipping rate tables to a listing. Shipping rate tables allow sellers to configure specific shipping costs based on the shipping destinations and level of service (e.g. economy, standard, expedited, and one-day). Generally speaking, sellers want to use these shipping rate tables so they can charge a higher shipping cost to the buyer whenever shipping costs are higher for them as well. For example, shipping to Alaska or Hawaii is generally more expensive than shipping to any other of the 48 US states, or in regards to international shipping, shipping to some regions and countries are more expensive than others.

Sellers configure domestic and international shipping rate tables in My eBay Shipping Preferences. To apply shipping rate tables to a listing, the shipping cost type must be flat-rate.

For domestic shipping rate tables, the three supported domestic regions are Alaska & Hawaii, US Protectorates (e.g. Puerto Rico and Guam), and APO/FPO destinations, which are US military bases/locations outside of the continental US. In addition to setting one flat rate based on the destination and service level, the seller also has the option of adding an extra charge based on the weight of the shipping package, or they can add a surcharge instead. To determine if a domestic shipping rate table is set up for the seller's account, the GetUser call can be used, and then the seller will look for a value of true in the User.SellerInfo.DomesticRateTable field. Although the GetUser call can be used to see if a domestic shipping rate table exists for the seller's account, details of the shipping rate table, including all specified costs for the different regions, can only be viewed and modified in My eBay Shipping Preferences. This functionality is not yet available in any public APIs.

For international shipping rate tables, specific rates may be set up for any and all of the nine geographical regions and individual countries within those regions. Similar to domestic shipping rate tables, the seller has the option of adding an extra charge based on the weight of the shipping package. Sellers cannot add a surcharge for international shipping. To determine if a international shipping rate table is set up for the seller's account, the GetUser call can be used, and then the seller will look for a value of true in the User.SellerInfo.InternationalRateTable field. Although the GetUser call can be used to see if an international shipping rate table exists for the seller's account, details of the shipping rate table, including all specified costs for the different regions/countries, can only be viewed and modified in My eBay Shipping Preferences. This functionality is not yet available in any public APIs.

If you are applying a domestic or international shipping rate table that specifies a surcharge by weight, you must specify the item weight in the ShippingPackageDetails container's WeightMajor and WeightMinor fields, even though the listing is using flat-rate shipping. Do not use any other fields in the ShippingPackageDetails container because none of those fields are applicable in this use case.

This container is only returned in the 'Get' calls if one or more shipping rate tables have been applied to the listing, and if the call is being made by the seller who listed the item.

Note: The capability to create and use multiple domestic and international shipping rate tables (up to 40 per seller account) has rolled out to the US, Australia, Canada (English and French), Italy, UK, and Germany sites. For other sites, only one domestic and one international shipping rate table may be set up per seller. Whether a seller is using the old default domestic and international shipping rate tables or the new shipping rate tables, these shipping rate tables are set up in My eBay Shipping Preferences or as part of a Shipping Business Policy. If using the Trading API to create a listing that will use the new shipping rate tables, the DomesticRateTableId and InternationalRateTableId fields are used to reference and apply these new shipping rate tables to the listing. If desired, sellers can still use the old default shipping rate tables, but they are not allowed to mix and match old and new shipping rate tables, meaning that they will get an error if they pass in both the old fields (DomesticRateTable and InternationalRateTable) and the new fields (DomesticRateTableId and InternationalRateTableId). The new shipping rate tables have all of the functionality of the old shipping rate tables, plus the seller has access to all domestic regions and not just the special regions (such as Alaska & Hawaii, US Protectorates, and APO/FPO locations in US).
See the Field Index to learn which calls use RateTableDetails.

SalesTax ( SalesTaxType ) [0..1]
This container shows sales tax information for an item in a specific tax jurisdiction. The concept of 'sales tax' is only applicable to eBay US and Canada (English and French) sites.

This container can be used in an Add/Revise/Relist/Verify call to set sales tax settings for a specific tax jurisdiction, but it is actually a better practice if a user sets up sales tax rates through the Sales Tax Table tool in My eBay (or by using the SetTaxTable call). A seller's Sales Tax Table is applied to the listing by including the UseTaxTable field in the request and setting its value to true. The GetTaxTable call can be used to retrieve the current sales tax rates for different tax jurisdictions.

This container is only returned in order management 'Get' calls if sales tax is applicable to the order line item. For eBay Collect and Remit states, the sales tax information is displayed in the Transaction.Taxes container instead.

Note: As of November 2021, buyers in all US states except for Missouri (and several US territories), will automatically be charged sales tax for purchases, and the seller does not set this rate. eBay will collect and remit this sales tax to the proper taxing authority on the buyer's behalf. For more US state-level information on sales tax, see the eBay sales tax collection help topic.
See the Field Index to learn which calls use SalesTax.

SellerExcludeShipToLocationsPreference ( boolean ) [0..1]
Not used by any call.

Sellers can set up a global Exclude Ship-To List through their My eBay account. The Exclude Ship-To List defines the countries to where the seller does not ship, by default.

This flag returns true if the Exclude Ship-To List is enabled by the seller for the associated item. If false, the seller's Exclude Ship-To List is either not set up, or it has been overridden by the seller when they listed the item with ExcludeShipToLocation fields.

In the response, ExcludeShipToLocation fields detail the locations to where the seller will not ship the item, regardless of the value returned in this field.
See the Field Index to learn which calls use SellerExcludeShipToLocationsPreference.

SellingManagerSalesRecordNumber ( int ) [0..1]
The sale record ID. Applicable to Selling Manager users. When an item is sold, Selling Manager generates a sale record. A sale record contains buyer information, shipping, and other information. A sale record is displayed in the Sold view in Selling Manager. Each sale record has a sale record ID.

In the following calls, the value for the sale record ID is in the SellingManagerSalesRecordNumber field: GetItemTransactions, GetSellerTransactions, GetOrders, GetOrderTransactions.

For GetOrders, GetOrderTransactions, and GetItemTransactions only: If using Trading WSDL Version 1019 or above, this field will only be returned to the buyer or seller, and no longer returned at all to third parties. If using a Trading WSDL older than Version 1019, the real record number is only returned to the buyer or seller, and a dummy value of 0 will be returned to all third parties.

The sale record ID can be for a single or a multiple line item order.

Note: For the GetItemTransactions, GetOrders, and GetOrderTransactions calls, this field is only returned to the seller of the order; this field is not returned for the buyer or third party.
See the Field Index to learn which calls use SellingManagerSalesRecordNumber.

ShipmentTrackingDetails ( ShipmentTrackingDetailsType ) [0..*]
Not used by any call.

Container for the shipping carrier and tracking information associated with the shipment of an order.

As each package has a unique tracking number, this container should be repeated for each package in the order.

Note: Top-rated sellers must have a record of uploading shipment tracking information (through site or through API) for at least 90 percent of their order line items (purchased by U.S. buyers) to keep their status as Top-rated sellers. For more information on eBay's Top-rated seller program, see the Becoming a Top Rated Seller and qualifying for Top Rated Plus page.
Note: Shipment tracking information does not appear in Merchant Data API's OrderReport responses, because once shipment tracking information is provided to the buyer, the order/order line item is considered acknowledged, and acknowledged orders do not show up in OrderReport responses.
See the Field Index to learn which calls use ShipmentTrackingDetails.

ShippingDiscountProfileID ( string ) [0..1]
On input, this is the ID of the shipping discount to offer for the domestic shipping services (where the shipping discount is either of type FlatShippingDiscount or CalculatedShippingDiscount).

On output, this is the ID of the shipping discount offered and corresponds to whichever is returned: FlatShippingDiscount or CalculatedShippingDiscount. Only returned if the calling user is the seller.

If the user created a shipping discount profile, use the ShippingDiscountProfileID.

In the RelistItem and ReviseItem family of calls, you can remove the existing ShippingDiscountProfileID associated with the item by supplying a value of 0 (zero).

Only returned if the calling user is the seller.
See the Field Index to learn which calls use ShippingDiscountProfileID.

ShippingRateErrorMessage ( string ) [0..1]
Not used by any call.

For most applicable calls, returns the words No Error or returns an error message related to an attempt to calculate shipping rates. For calculated shipping only.

The message text explains that a postal code is needed to calculate shipping. Only returned when ItemDetails is set to Fine.
See the Field Index to learn which calls use ShippingRateErrorMessage.

ShippingRateType ( ShippingRateTypeCodeType ) [0..1]
Not used by any call.

A shipping rate scale for shipping through USPS that affects the shipping cost calculated for USPS (lower if ShippingRateType is DailyPickup). ShippingRateType is returned only if the value of ShippingService is one of the USPS shipping services. For calculated shipping only.
See the Field Index to learn which calls use ShippingRateType.

ShippingServiceOptions ( ShippingServiceOptionsType ) [0..*]
This container is used to provide details on a specific domestic shipping service option, including the unique identifier of the shipping service option and the costs related to domestic shipping service. A separate ShippingServiceOptions container is needed for each domestic shipping service option that is available to ship the item. Unless a fulfillment business policy is being used, generally at least one ShippingServiceOptions container will be required.

If you specify multiple ShippingServiceOptions nodes, the repeating nodes must be contiguous. For example, you can insert InternationalShippingServiceOption nodes after a list of repeating ShippingServiceOptions nodes, but not between them:

<ShippingServiceOptions>...</ShippingServiceOptions>
<ShippingServiceOptions>...</ShippingServiceOptions>
<ShippingServiceOptions>...</ShippingServiceOptions>
<InternationalShippingServiceOption>...</InternationalShippingServiceOption>
<InternationalShippingServiceOption>...</InternationalShippingServiceOption>


If you specify ShippingDetails when you revise or relist an item but you omit ShippingServiceOptions, eBay will drop the domestic shipping services from the listing. This may also have unintended side effects, as other fields that depend on this data may be dropped as well.

To retain the shipping services and dependent fields when you modify other shipping details, it may be simplest to specify all ShippingDetails that you still want to include in the listing.

A seller can offer up to four domestic shipping services and up to five international shipping services. However, if the seller is opted in to the Global Shipping Program, only four other international shipping services may be offered (regardless of whether or not Global Shipping is offered for the listing). All specified domestic and international shipping services must be the same shipping type (for example, Flat versus Calculated).

Note: If the seller has set the shipping cost model to 'Flat' or 'Calculated' (ShippingDetails.ShippingType field), at least one actual shipping service option must be specified through a ShippingServiceOptions container. In the past, eBay allowed users to set the shipping cost model to 'Flat' or 'Calculated', and then just pass in one ShippingServiceOptions container with the ShippingServiceOptions.ShipppingService value set to a 'Local Pickup' option. Now, sellers must pass in at least one actual domestic shipping service option in addition to any 'Local Pickup' option, or the listing will be blocked with the following error: 17510 - You must specify at least one domestic shipping service, other than or in addition to Local Pickup.
For GetItemShipping, results are filtered: if any service is not available in the buyer's region, it is removed. If no services remain after this filtering, a warning is returned.
See the Field Index to learn which calls use ShippingServiceOptions.

ShippingServiceUsed ( token ) [0..1]
Not used by any call.

The shipping service actually used by the seller to ship the item(s) to the buyer.
See the Field Index to learn which calls use ShippingServiceUsed.

ShippingType ( ShippingTypeCodeType ) [0..1]
The shipping cost model offered by the seller. This is not returned for various calls since shipping type can be deduced: if a CalculatedShippingRate structure is returned by the call, the shipping type is Calculated. Otherwise, it is one of the other non-Calculated shipping types.

GetItemShipping and GetItemTransactions: If the type was a mix of flat and calculated services, this is set simply to Flat or Calculated because it is the buyer's selection that results in one of these.

GetMyeBayBuying: If the seller has set the ShipToLocation to Worldwide for an item, but has not specified any international shipping service options, NotSpecified is returned as the ShippingType value.
See the Field Index to learn which calls use ShippingType.

TaxTable ( TaxTableType ) [0..1]
Tax details for a jurisdiction, such as a state or province. If no tax table is associated with the item, a tax table is not returned.

For GetItem, a tax table is returned if it exists when:
  • DetailLevel is set to ReturnAll or ItemReturnDescription (in this case, the value of IncludeTaxTable does not matter)
  • IncludeTaxTable is set to true and DetailLevel is not set or it is set to ItemReturnAttributes
See the Field Index to learn which calls use TaxTable.

ThirdPartyCheckout ( boolean ) [0..1]
Not used by any call.

This field is deprecated.
See the Field Index to learn which calls use ThirdPartyCheckout.