Other Shipping Features


Ensuring PayPal Seller Protection

Shipping Cost Discount Profiles

Specifying the Cash on Delivery Option in Shipping Details

Shipping Insurance

Ensuring PayPal Seller Protection

To ensure that a seller is covered by PayPal Seller Protection, the seller should ship to the address specified on the Transaction Details page of their PayPal account.

See also:

PayPal seller protection for eBay


PayPal Seller Protection


Shipping Cost Discount Profiles

In this section:


eBay enables a seller to offer various kinds of shipping cost discounts on orders (items purchased separately from the same seller and now combined for payment and shipping).

Note: The shipping costs of orders shipped through the Global Shipping Program are consolidated into a single value consisting partly of domestic shipping and handling charges, and partly of international shipping and handling charges that are controlled by the international shipping provider. Sellers can discount only the domestic portion of the total shipment.

The kind of discount that an item can receive in that order is determined by what shipping cost discount profile was assigned to the item when it was listed, and, if the seller defined a global promotional discount and it was in effect at the time the order line item was created, the order can also benefit from a promotional discount. The discounts "applied to the item" are only realized when the item is combined in an order—no shipping discount is applied to the item if it the item is purchased and shipped by itself.

A user can also offer a packaging/handling cost discount and can specify shipping insurance costs for Combined Invoice orders.

Discount Rules and Discount Profiles

In the API, discount rules are the kinds of discounts that are made available to sellers. The following are loose descriptions of the discount rules that are available for flat rate shipping.

These descriptions reflect amounts and percentages. If a user wishes to signify that an item qualifies for a shipping discount, the user must first create a shipping discount profile. That profile will be based on one of the shipping discount rules made available by eBay. Rules are provided by eBay; profiles are created by users and are based on such rules.

The profile definition would need to include any amount or percentage that corresponds to the rule. For example, the API rule corresponding to the first description above is named EachAdditionalAmount. A user can create a flat rate shipping discount profile (and make up a name for the profile, such as "flat ship 2") whose DiscountName is EachAdditionalAmount, and the user specifies the fee in DiscountProfile.EachAdditionalAmount. A user can create additional profiles for this same rule, each with a unique fee.

Profile Areas

These are the major areas for which profiles can be created: calculated shipping discounts, flat rate shipping discounts, packaging/handling cost discounts, and promotional discount.

A user can define, at most, one promotional shipping cost discount.

A user can define, at most, one packaging/handling cost discount.

A user can have zero or more profiles for each of the other profile areas (if the profile is based on a variable rule, as discussed in Variable Rules and Fixed Rules).

In the profile areas for which a user can have multiple discount profiles, all profiles must be based on the same underlying rule. For example, FlatShippingDiscount has several rules, one of which is EachAdditionalAmountOff. The user can have multiple profiles based on that rule. If the user wishes to create flat rate shipping discount profiles based on the EachAdditionalPercentOff discount rule, the user would first need to delete the other profiles for flat rate shipping discounts.

Variable Rules and Fixed Rules

A variable rule is a rule which can be used in a discount profile only if accompanied by a value for amount or percentage. For example, for a user to create a calculated shipping discount profile based on the WeightOff rule, a variable rule, the user must specify the amount of weight in the WeightOff field.

In contrast, no additional value is needed when the profile is based on a fixed rule. For example, if the user creates a profile based on the fixed rule named CombinedItemWeight and then assigns that profile to several listings, the user is designating that the calculated shipping cost for Combined Invoice orders would be based on the combined weights of all items.

This distinction is important because a user can have one or more profiles based on the same variable rule, or the user can have one profile based on a fixed rule, but the user cannot have both. If the user has several profiles based on a variable rule and now the user wishes to switch to a fixed rule for subsequent item listings, the user must first delete all profiles based on the variable rule before the user can create the profile based on the fixed rule.

Creating Shipping Discount Profiles

A user can define shipping discount profiles on the eBay web site using the My eBay SetShippingDiscountProfiles page. (Once a user has defined profiles, the user can assign one or more to listings. See Assigning Shipping Discount Profiles.)

When creating profiles via SetShippingDiscountProfiles, the user always identifies the underlying discount rule by name. If it is a variable rule, the user can create as many profiles at the same time via SetShippingDiscountProfiles as he wishes, provided they are all based on the same rule. The user must set the value of whatever field corresponds to the choice of variable rule. For example, if the user selected WeightOff as the rule for a new calculated shipping cost discount profile, the user would also need to set the number of ounces in DiscountProfile.WeightOff.

The SetShippingDiscountProfiles has a DiscountProfile.DiscountProfileID field. This field is not used when a user creates a profile but only when modifying or deleting a profile. eBay assigns a unique ID to every new profile. You can get the IDs for a user's profiles by calling GetShippingDiscountProfiles.

The user can create, at most, one profile based on a fixed rule (provided the user has first deleted all profiles for that profile area that are based on a variable rule).

If this is the first and only profile the user is creating for a particular profile area in the call to SetShippingDiscountProfiles, the user cannot assign a name to the profile.

At least one profile must exist for that profile area for the user to be able to assign unique names to subsequent profiles in that profile area. The name that the user assigns to a profile is completely up to the user.

To "rename" the first "nameless" profile after additional profiles have been created, the user must create a new profile whose characteristics match those of the first profile plus include a name, and then the user must delete the original profile.

Shipping Insurance Requirement for Combined Invoice Orders

Shipping insurance cost must be specified for Combined Invoice orders if the user wishes to define either flat rate shipping cost discount profiles or a promotional shipping discount profiles. Either the user must define both domestic and international shipping insurance costs before creating any of those profiles, or the user must define those insurance costs in the same call of SetShippingDiscountProfiles that creates the new profiles. (This requirement does not apply for eBay sites for which shipping insurance does not apply.)

Packaging/Handling Discount Profile Requirement for Calculated Shipping

A packaging/handling profile must be created if a calculated shipping cost discount profile is to be created. Either the user must define it before creating any calculated shipping cost discount profile, or the user must define it at the same time the first calculated shipping cost discount profile is created.

Assigning Shipping Discount Profiles

Once shipping cost discount profiles have been defined, a seller can assign them to listings, and relisted and revised listings. If a listing offers flat rate shipping services, the seller can assign, at most, one flat rate shipping cost discount profile. Similarly, a seller can assign one calculated shipping cost discount profile to a listing that offers calculate shipping. Regardless of whether any flat rate or calculated shipping cost discount profile has been assigned to the listing, the seller can apply the promotional shipping cost discount, if such has been defined. The seller can also assign a packaging/handling cost discount profile.

In order to assign a shipping cost discount profile, the seller must have the ID of the profile. You can get the names and IDs of available shipping cost discount profiles with GetShippingDiscountProfiles, a call that returns details about the shipping cost discount profiles defined by the user.

When listing or relisting or revising a listing, set the appropriate ShippingDetails members:

If the seller sets ShippingDiscountProfileID to a calculated shipping cost discount profile, the current profile for packaging/handling cost discount is applied. (There is therefore no field in AddItem for identifying the packaging/handling cost discount profile.)

Miscellaneous Related Topics

Shipping discount profiles can be assigned to multi-quantity listings. The buyer receives whatever works out to be the best combination of values. For example, if the non-discounted packaging/handling fee for individual items would be $5 for the first item and $4 for each additional item, and if a packaging/handling cost discount applies, one for which the cost is $3 for each additional item, the better of these, $3, is the fee for additional items, in the context of Combined Invoice orders.

GetItem returns shipping cost discount details for those items and orders for which shipping cost discounts were applied.

The amount saved in an order for which shipping cost discounts apply is returned in the AmountSaved field of GetOrders and GetOrderTransactions.

If an order qualifies for shipping discounts and was created via the eBay web site, one more shipping service is presented to the buyer (in addition to whatever shipping services the seller is offering to the buyer for the order). This additional shipping service is named Promotional Shipping Service. This service is added by eBay when order details are retrieved for the buyer (it is not, for example, something that the seller can select somewhere). A buyer can select one or none of the services being offered. Thus, if the buyer selects Promotional Shipping Service, the buyer is selecting the discounted shipping cost and the choice of shipping carrier is up to the seller. Conversely, if the buyer selects one of the other shipping services, the buyer does not get the shipping discount.

Modifying Shipping Discount Profiles

To modify a shipping discount profile, call SetShippingDiscountProfiles with ModifyActionCode set to Update and provide all details for the updated profile. If part of the modification is to change from a variable rule to a fixed rule, you must first delete all profiles based on the variable rule. See Variable Rules and Fixed Rules.

Deleting Shipping Discount Profiles

To delete a flat rate or calculated shipping discount profile, first call GetShippingDiscountProfiles to obtain valid DiscountProfileIDs, and then call SetShippingDiscountProfiles with ModifyActionCode set to Delete and set DiscountProfileID to the DiscountProfileID of the profile to be deleted. When you delete a profile, the only listings that are affected are active listings for which no bids have been made and which were associated with the discount profile that is being deleted. Listings for which at least one bid has been made remain unaffected: they continue with the discount that was originally assigned to the listing. For those active listings for which no bids have been made, you can set MappedDiscountProfileID to the ID of the profile that is to be used in place of the profile being deleted.

Once a user has defined a packaging/handling profile, the user cannot delete it. However, the user can change the underlying rule in CalculatedHandlingDiscount.DiscountName to CombinedHandlingFee or IndividualHandlingFee. Call SetShippingDiscountProfiles with ModifyActionCode set to Update.

To "delete" the shipping insurance for Combined Invoice orders, set InsuranceOption to NotOffered. It is not necessary to redefine the range/cost pairs.

Promotional discounts may not be deleted through the API. To delete a promotional discount, use the Offer combined payments and shipping pages under My eBay on the site.

Deleting a Shipping Discount Profile from an Item When Relisting or Revising

If a listed item has a Shipping Discount Profile defined, you can remove that discount profile in the Relist or Revise item family of calls. To do this, supply the entire shipping container (ShippingDetails) and for the ShippingDiscountProfileID or InternationalShippingDiscountProfileID supply the value 0 (zero). This will result in the removal of that shipping discount profile from that item.

Key API Mechanisms








Shipping Insurance for Combined Invoice Orders

The ShippingInsurance and InternationalShippingInsurance in SetShippingDiscountProfiles (for domestic and international orders, respectively) enable the user to pair ranges of item price with shipping insurance fee. See:



Packaging/Handling Cost for Combined Invoice Orders

The user can specify how packaging/handling cost is to be determined globally for orders via the CalculatedHandlingDiscount field of SetShippingDiscountProfiles. See:


Specifying the Cash on Delivery Option in Shipping Details

On the Italy site (site ID 101), a seller can provide an improved Cash on Delivery (COD) option. Using AddItem, a seller can enable a buyer to choose COD as the shipping method.

To list with COD for shipping requires the following:

A seller who is using AddItem to enable the COD shipping option would include the following in the AddItem request:

Example: Including Cash on Delivery as a Shipping Option
    <CODCost currencyID="EUR">2.0</CODCost>

A seller can specify COD as a shipping option in the following calls:

The following calls can include COD as the shipping method for a listing:

Shipping Insurance

Note:With request version 635 and higher, the international and domestic shipping insurance option is available only on the following sites: AU, FR, and IT. If you attempt to list an item with a shipping insurance option on a site that does not support the shipping insurance option, the shipping insurance option is removed and a warning is issued.

Setting Insurance Costs for Flat Rate Shipping

Domestic insurance is represented by this container:


International insurance is represented by this container:


Note that if you include buyer-paid shipping insurance on an item (listed on one of the sites that supports the shipping insurance option), a buyer on a site that does not support buyer-paid shipping insurance can still purchase that item. In these cases, the buyer is responsible for all the shipping insurance terms that have been outlined in the item listing.

It's worth mentioning that eBay has found that buyer-paid shipping insurance causes negative experiences for both buyers and sellers alike. Buyers are confused as to why they need to purchase shipping insurance, especially in light of PayPal's Buyer Protection service (which applies whether or not a seller uses shipping insurance). Note that sellers are responsible for the items they sell until they safely arrive in their customers' hands. Offering buyer-paid insurance (either as an optional or required service) infers that the buyer is somehow responsible for the safe delivery of the items they purchase. This notion can reduce buyer confidence in the marketplace.

eBay understands that it is in the seller's best interest to insure certain shipments (for example, antiques, fragile items, and so on). If appropriate for the items they sell, and for the business they run, sellers can choose to purchase insurance for the items they ship. While completely optional, sellers can fold any insurance costs into the price of their items, either by adding the cost to the item price or by adding it as a handling charge. In these cases, sellers can include a statement in their item descriptions that clarify the shipping details (for example, "shipping insurance provided").

Requirements and restrictions:

See also Shipping Insurance for Combined Invoice Orders.

Revising an item

If the item already has insurance and no additional insurance details are provided, the existing insurance values are not modified.

If the item already has insurance and additional insurance tags are passed in, only the corresponding values are updated.

If the seller revises the listing to remove domestic or international shipping services, InsuranceOption is set to NotOffered and InsuranceFee is not returned in the Get calls.

Retrieving Insurance Costs for Flat Rate Shipping

If shipping services were offered, GetItem returns the following tags and containers:





InsuranceDetails and its tags represents insurance for the domestic shipping services. InternationalInsuranceDetails and its tags represents insurance for the international shipping services.

If domestic insurance was not specified for the item, InsuranceDetails.InsuranceOption is set to NotOffered and InsuranceDetails.InsuranceFee will not be returned. Similar is true for international insurance.

Retrieving Insurance Costs for Calculated Shipping

GetItemTransactions: The insurance cost returned for the shipping service is for a single item. Therefore, if the buyer purchased multiple items, you must multiply ShippingInsuranceCost by the number of items to arrive at the total shipping cost. See Shipping Insurance.

GetOrders: The insurance cost returned for the shipping service is for the entire order. See Shipping Insurance.

Automatic Shipping Insurance

There is a condition in which a buyer receives shipping insurance for free. If the buyer was anticipating that he could request shipping insurance for the item and then does not find this choice, this may confuse the buyer. This section describes that condition so that you can consider how to make this clear to a buyer when this condition arises.

If the seller selects calculated shipping when listing the item, the cost of shipping insurance is determined as part of the shipping cost calculations that occur when the item has been sold (the point when the final item value and the buyer's zip code are known).

Some shipping carriers (such as USPS and UPS) automatically include free shipping insurance for items with a value below a certain carrier-set amount, regardless of whether the seller specified that insurance is required, optional or not offered. eBay, working with the shipping carrier, automatically detects whether the item price is less than the carrier's threshold value and whether shipping insurance should automatically be made part of the order line item (at no additional charge). Since this might happen when a buyer is anticipating the option to request shipping insurance, this is a point of potential confusion for the buyer. Thus, it is worth your considering how to make this clear to the buyer when the situation arises.

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.