Mục Lục

eBay Business Policies Management API: Users Guide

Important! eBay recommends that you use the Account API to set up all your fulfillment, payment, and return business policies. This guide remains active for archival purposes only.

The Business Policies Management API allows sellers to create and manage business policies (payment, return, and shipping). Sellers can easily create these business policies
and associate them to an eBay category group. Since every listing on eBay is linked to a
category, this API will allow you to create a business policy and immediately apply it to all
listings for a group of categories. By using the Business Policies Management API, sellers
will no longer have to recreate, reassign, and update the same payment, return policy,
and shipping settings/values for each individual listing. Managing business policies through this API will help sellers save
significant time in creating and updating their listings.

Business Policies are now available on all eBay sites. A seller can opt in to Business Policies through the
Sell section in My eBay. A seller can verify whether or not their account
is opted in to Business Policies by making a call to Trading API’s
GetUserPreferences,
and including the ShowSellerProfilePreferences flag in the call request.
In the GetUserPreferences response, the seller will look for a ‘true’
value in the SellerProfilePreferences.SellerProfileOptedIn field. Regardless of opt-in status, a seller can actually use the Business Policies Management API to create and manage business policies, but that same seller will not be able to access the Business Policies Management UI on the eBay site nor apply specific business policies to listings until the account has been opted-in to Business Policies.

Once a seller is opted in to Business Policies, eBay will automatically extract and create all business policies for the seller’s account based on listings created by that
seller in the last 90 days. The seller then has the option to tweak (change name, change
values, assign to new category groups, etc.) these existing policies or leave as is.
A seller can create as many payment, return, and shipping policies as they wish. If the seller had a payment policy for Motor Vehicle listings and a
payment policy for all other listings, you might see the following nodes in the
GetUserPreferences response:

…
<SupportedSellerProfile> <ProfileID>5********4</ProfileID> <ProfileType>PAYMENT</ProfileType> <ProfileName>standardpaymentprofile</ProfileName> <ShortSummary>Payment policy for all non-vehicle listings</ShortSummary> <CategoryGroup> <Name>ALL</Name> </CategoryGroup> </SupportedSellerProfile>
…

…
<SupportedSellerProfile> <ProfileID>5********4</ProfileID> <ProfileType>PAYMENT</ProfileType> <ProfileName>vehiclepaymentprofile</ProfileName> <ShortSummary>Payment policy for vehicle listings</ShortSummary> <CategoryGroup> <Name>MOTORS_VEHICLE</Name> </CategoryGroup> </SupportedSellerProfile>
…

Once a seller’s account is opted into Business Policies, the payment, return, and
shipping options/values set in the default business policies will automatically be set whenever the
seller lists an item. It is then at the seller’s discretion to modify, delete, or add new
settings/values in Web flow or by using an addSellerProfile or setSellerProfile call. The seller also has the option of using/referencing another
(non-default) business policy (in Web flow or through the
Item.SellerProfiles container in an Add/Revise/RelistItem Trading API call).

Overview of the Service

The Business Policies Management API is a SOA service that is meant to be consumed by
users who want to programmatically create and manage business policies. The
API allows you to create payment, return, and shipping business policies. The settings/values captured in these business policies can then be automatically
applied to eBay listings.

When a seller lists an item, the Business Policies Management API verifies which
Business Policies category group that the item belongs to (based on the eBay category the
item is listed under), and then retrieves and applies the default business policies
for that Business Policies category group.

Previous to the concept of business policies, a seller
had to specify and update payment, return, and shipping settings/values for
each individual listing. This meant that the seller had to enter the same information
repeatedly for each listing. With Business Policies, a seller can partially automate
(through Web flow or through Trading API’s Add/Revise/Relist calls) the process of
listing, revising, or relisting an item.

About Category Groups

The categoryGroup container in Business Policies Management API calls defines a group of eBay categories and connects this category group to a business policy. This
allows seller to create one business policy that can be applied to many categories. The
relationship between a categoryGroup container and a business policy is:

One business policy can be associated with multiple category groups.
A category group can be associated with many business policies.
Currently, the valid values for a category group names are ‘ALL’ (all non-
motor vehicle categories) and ‘MOTORS_VEHICLE’ (all motor vehicle categories). The ‘MOTORS_VEHICLE’ category group is not valid for return policies, as return policies cannot be used with motor vehicle listings. In the
future, there may be other valid values for category group names.

The first business policy (payment, return, or shipping) that the seller creates (or eBay creates for the seller) for a category group becomes the default policy for that
category group and policy type combination.

Creating a Business Policy

When a seller creates a business policy, the seller provides a name for the
policy and eBay assigns a unique ID number (profileId) to a
successfully created policy. Other data that the seller provides for the business policy is the
category group(s) to which the business policy will apply, the eBay site where the items will be
sold, and all applicable settings/values for buyer payment (for payment policies),
return policy details (for return policies), and the shipping details (for
shipping policies). Here are the high-level steps for creating a business policy
through an addSellerProfile call:

Assign a category group to which the business policy will apply by setting the
categoryGroup.name value to ‘ALL’ or ‘MOTORS_VEHICLE’. The ‘MOTORS_VEHICLE’ category group is not valid for return business policies, as return business policies cannot be used with motor vehicle listings.
Define the policy type by including the profileType field and
setting its value to ‘PAYMENT’, ‘RETURN_POLICY’ or ‘SHIPPING’.
Assign a name to the business policy through the profileName field. It is
a good idea to give the business policy a descriptive name so you can easily identify it. All business policy names should be unique within each policy type (payment, return, shipping).
Optionally, provide a text description of the business policy through the
profileDesc field.
Optionally, provide the siteId value of the listing site. If this
field is not provided, the siteId value defaults to the seller’s
registration site.
Specify the details of each policy type that is being created through the
paymentProfile.paymentInfo, returnPolicyProfile.returnPolicyInfo,
and/or shippingPolicyProfile.shippingPolicyInfo containers.

Modifying a Business Policy

To modify an existing business policy, you use the
setSellerProfile call. First, you want to identify the payment, return, or
shipping business policy to modify by providing a
valid value in the profileName and/or profileId field in
the request. Then, you can modify any existing value defined for a business policy or add fields to
a business policy. For example, you might want to add additional acceptedPaymentMethod
values for a payment business policy, or add a text description of the return policy through the
returnPolicyInfo.description field, or add an additional domestic
shipping service through an additional domesticShippingPolicyInfoService
container.

Note: Modifying an existing business policy creates a ‘clone’ of that business policy, and all listings that referenced the previous business policy are reassigned to the new business policy. Active listings that are in restricted revise mode will be assigned to the new business policy, but values/settings will remain unchanged.

Another use case for using the setSellerProfile call is to change the
default business policy for a category group and policy type combination. It would actually require
two setSellerProfile calls to perform this action. In the first call, you’d
identify the current default business policy through the profileId field, identify the
category group that the business policy belongs to in the categoryGroup.name field, and
then pass in a value of ‘false’ in the categoryGroup.default field. In the
second call, you’d identify the business policy that you want set as the new default business policy through the
profileId field, identify the category group that the business policy belongs to in the
categoryGroup.name field, and then pass in a value of ‘true’ in the
categoryGroup.default field.

Retrieving Business Policies

To retrieve one or more business policies, you use the getSellerProfiles
call. The seller has the option of retrieving all existing business policies (no
input parameters), specific business policies identified
by profileId and/or profileName value(s), or business policies
matching the specified profileType value(s).

Deleting a Business Policy

To delete one business policy, you use the removeProfile call. To identify the business policy to delete, the seller passes in the profileId value. To delete multiple business policies, you use the removeSellerProfiles call. To identify the business policies to delete, the seller passes in multiple profileIds values.

Note: A business policy that is associated to one or more active listings cannot be deleted. Instead, these listings have to be reassigned to other active business policies first using a ReviseItem call or the Business Policies Management UI.

Consolidating Similar Shipping Policies

Shipping business policies that have identical shipping services (with the exception of shipping costs) and identical settings (such as domestic and international shipping types, handling times, ship-to locations, rate tables, etc.) can be consolidated using the consolidateShippingProfiles call. When shipping business policies are consolidated, the shipping business policy that is used/referenced by the seller most frequently is kept, and the others are removed from the seller’s account. Active or scheduled listings inherit the shipping business policy (and all its values/settings) that is kept after the consolidation, but the shipping costs that were specified for each shipping service in the newly deleted shipping policies are kept on the respective listings.

The consolidateShippingProfiles call runs asynchronously. The status of a shipping policy consolidation job can be retrieved by using the getConsolidationJobStatus call.

Note: As a seller continues to create numerouse listings, there’s a good chance that permutations in shipping settings will continue to accumulate. Due to this reason, it is recommended that client applications are set up to execute regular consolidateShippingProfiles calls.

Overriding Shipping Costs at the Listing Level

The shipping costs for all domestic and international shipping services, that are defined in the domesticShippingPolicyInfoService and intlShippingPolicyInfoService containers of the shipping policy, can be overridden by supplying a ShippingServiceCostOverrideList.ShippingServiceCostOverride container for each domestic and international shipping service defined through the shipping policy.

Shipping costs include the shipping cost to ship one item (ShippingServiceCost in Trading API), the shipping cost to ship each additional identical item for a multi-quantity listing (ShippingServiceAdditionalCost in Trading API), and a shipping surcharge if one is applicable for the shipping service (ShippingSurcharge in Trading API).

For all domestic shipping services defined in the shipping business policy, the ShippingServiceType field in the ShippingServiceCostOverrideList.ShippingServiceCostOverride container should be set to ‘Domestic’, and for all international shipping services defined in the shipping business policy, the ShippingServiceType field should be set to ‘International’. For both domestic and international shipping services, the ShippingServicePriority value in the ShippingServiceCostOverrideList.ShippingServiceCostOverride container should match the sortOrderId value for the matching shipping service in the shipping business policy.

Note: Once a shipping cost value is overridden on an active listing, it remains overridden, even if its respective value is changed in the shipping business policy that is associated to that listing.

Business Policies Eligible for eTRS

If the seller meets all Top-Rated Seller requirements, and the business policy meets all Top-Rated Plus listing requirements for the listing category, an ETRS flag is returned in the output under the categoryGroup container. For more information on Top-Rated Seller and Top-Rated Plus listings, see the Becoming a Top Rated Seller and qualifying for Top Rated Plus help topic.

Mapping Business Policies Management API Fields to Trading API Fields

In most cases, the names of data fields in the Business Policies Management API directly map to the names of data fields in the Trading API listing calls. The main difference is the initial character is lowercase in the Business Policies Management API, and the initial character is uppercase in the Trading API listing calls. The following table maps payment, return policy, and shipping-related fields in the Business Policies Management API to payment, return policy, and shipping-related fields in the Trading API listing calls.

Business Policies Management API Field
Trading API Listing Field

Payment Fields

paymentProfile.profileId
Item.SellerProfiles.SellerPaymentProfile.PaymentProfileID

paymentProfile.profileName
Item.SellerProfiles.SellerPaymentProfile.PaymentProfileName

paymentProfile.siteId
X-EBAY-API-SITEID HTTP header; and
siteid URL parameter

paymentInfo.acceptedPaymentMethod (deprecated)
Item.PaymentMethods

paymentInfo.depositDetails.daysToFullPayment
Item.PaymentDetails.DaysToFullPayment

paymentInfo.depositDetails.depositAmount
Item.PaymentDetails.DepositAmount

paymentInfo.depositDetails.hoursToDeposit
Item.PaymentDetails.HoursToDeposit

paymentInfo.immediatePay
Item.AutoPay

paymentInfo.paymentInstructions (deprecated)
Item.ShippingDetails.PaymentInstructions (deprecated)

paymentInfo.paypalEmailAddress (deprecated)
Item.PayPalEmailAddress (deprecated)

Return Policy Fields

returnPolicyProfile.profileId
Item.SellerProfiles.SellerPaymentProfile.PaymentProfileID

returnPolicyProfile.profileName
Item.SellerProfiles.SellerReturnProfile.ReturnProfileName

returnPolicyProfile.siteId
X-EBAY-API-SITEID HTTP header; and
siteid URL parameter

returnPolicyInfo.description
Item.ReturnPolicy.Description

returnPolicyInfo.refundOption
Item.ReturnPolicy.RefundOption

returnPolicyInfo.restockingFeeValue (deprecated)
Item.ReturnPolicy.RestockingFeeValueOption (deprecated)

returnPolicyInfo.returnsAcceptedOption
Item.ReturnPolicy.ReturnsAcceptedOption

returnPolicyInfo.returnsWithinOption
Item.ReturnPolicy.ReturnsWithinOption

returnPolicyInfo.shippingCostPaidByOption
Item.ReturnPolicy.ShippingCostPaidByOption

returnPolicyInfo.warrantyDurationOption (deprecated)
Item.ReturnPolicy.WarrantyDurationOption (deprecated)

returnPolicyInfo.warrantyOfferedOption (deprecated)
Item.ReturnPolicy.WarrantyOfferedOption (deprecated)

returnPolicyInfo.warrantyTypeOption (deprecated)
Item.ReturnPolicy.WarrantyTypeOption (deprecated)

Shipping Fields

shippingPolicyProfile.profileId
Item.SellerProfiles.SellerShippingProfile.ShippingProfileID

shippingPolicyProfile.profileName
Item.SellerProfiles.SellerShippingProfile.ShippingProfileName

shippingPolicyProfile.siteId
X-EBAY-API-SITEID HTTP header; and
siteid URL parameter

shippingPolicyInfo.dispatchTimeMax
Item.DispatchTimeMax

shippingPolicyInfo.dispatchTimeReason
No equivalent field in Trading API

shippingPolicyInfo.domesticRateTable
Item.ShippingDetails.RateTableDetails.DomesticRateTable

shippingPolicyInfo.domesticShippingType
No equivalent field in Trading API

shippingPolicyInfo.excludeShipToLocation
Item.ShippingDetails.ExcludeShipToLocation

shippingPolicyInfo.GlobalShipping
Item.ShippingDetails.GlobalShipping

shippingPolicyInfo.internationalPackagingHandlingCosts
Item.ShippingDetails.CalculatedShippingRate.InternationalPackagingHandlingCosts

shippingPolicyInfo.intlRateTable
Item.ShippingDetails.RateTableDetails.InternationalRateTable

shippingPolicyInfo.intlShippingType
No equivalent field in Trading API

shippingPolicyInfo.packagingHandlingCosts
Item.ShippingDetails.CalculatedShippingRate.PackagingHandlingCosts

shippingPolicyInfo.shippingOption
No equivalent field in Trading API

shippingPolicyInfo.shippingPolicyCurrency
currencyID attribute (in multiple shipping cost-related fields)

shippingPolicyInfo.shippingPolicyName
No equivalent field in Trading API

shippingPolicyInfo.shipToLocations
Item.ShipToLocations

shippingPolicyInfo.domesticShippingPolicyInfoService.buyerResponsibleForPickup
No equivalent field in Trading API

shippingPolicyInfo.domesticShippingPolicyInfoService.buyerResponsibleForShipping
Item.BuyerResponsibleForShipping

shippingPolicyInfo.domesticShippingPolicyInfoService.fastShipping
Item.GetItFast

shippingPolicyInfo.domesticShippingPolicyInfoService.freeShipping
Item.ShippingDetails.ShippingServiceOptions.FreeShipping

shippingPolicyInfo.domesticShippingPolicyInfoService.shippingService
Item.ShippingDetails.ShippingServiceOptions.ShippingService

shippingPolicyInfo.domesticShippingPolicyInfoService.shippingServiceAdditionalCost
Item.ShippingDetails.ShippingServiceOptions.ShippingServiceAdditionalCost

shippingPolicyInfo.domesticShippingPolicyInfoService.shippingServiceCost
Item.ShippingDetails.ShippingServiceOptions.ShippingServiceCost

shippingPolicyInfo.domesticShippingPolicyInfoService.shippingSurcharge (deprecated)
Item.ShippingDetails.ShippingServiceOptions.ShippingSurcharge (deprecated)

shippingPolicyInfo.domesticShippingPolicyInfoService.shipToLocation
No equivalent field in Trading API

shippingPolicyInfo.domesticShippingPolicyInfoService.sortOrderId
Item.ShippingDetails.ShippingServiceOptions.ShippingServicePriority

shippingPolicyInfo.freightShipping.commodityType
No equivalent field in Trading API

shippingPolicyInfo.freightShipping.destPickupInside
No equivalent field in Trading API

shippingPolicyInfo.freightShipping.destPickupLocationType
No equivalent field in Trading API

shippingPolicyInfo.freightShipping.freightShippingClass
No equivalent field in Trading API

shippingPolicyInfo.freightShipping.originPickupInside
No equivalent field in Trading API

shippingPolicyInfo.freightShipping.originPickupLocationType
No equivalent field in Trading API

shippingPolicyInfo.freightShipping.packagingHelpRequired
No equivalent field in Trading API

shippingPolicyInfo.insurance.domesticInsuranceFee (deprecated)
Item.ShippingDetails.InsuranceDetails.InsuranceFee (deprecated)

shippingPolicyInfo.insurance.domesticInsuranceOption (deprecated)
Item.ShippingDetails.InsuranceDetails.InsuranceOption (deprecated)

shippingPolicyInfo.insurance.intlInsuranceFee (deprecated)
Item.ShippingDetails.InternationalInsuranceDetails.InsuranceFee (deprecated)

shippingPolicyInfo.insurance.intlInsuranceOption (deprecated)
Item.ShippingDetails.InternationalInsuranceDetails.InsuranceOption (deprecated)

shippingPolicyInfo.intlShippingPolicyInfoService.buyerResponsibleForPickup
No equivalent field in Trading API

shippingPolicyInfo.intlShippingPolicyInfoService.buyerResponsibleForShipping
Item.BuyerResponsibleForShipping

shippingPolicyInfo.intlShippingPolicyInfoService.codFee
Item.ShippingDetails.CODCost

shippingPolicyInfo.intlShippingPolicyInfoService.shippingService
Item.ShippingDetails.InternationalShippingServiceOption.ShippingService

shippingPolicyInfo.intlShippingPolicyInfoService.shippingServiceAdditionalCost
Item.ShippingDetails.InternationalShippingServiceOption.ShippingServiceAdditionalCost

shippingPolicyInfo.intlShippingPolicyInfoService.shippingServiceCost
Item.ShippingDetails.InternationalShippingServiceOption.ShippingServiceCost

shippingPolicyInfo.intlShippingPolicyInfoService.shippingSurcharge (deprecated)
No equivalent field in Trading API

shippingPolicyInfo.intlShippingPolicyInfoService.shipToLocation
Item.ShippingDetails.InternationalShippingServiceOption.ShipToLocation

shippingPolicyInfo.intlShippingPolicyInfoService.sortOrderId
Item.ShippingDetails.InternationalShippingServiceOption.ShippingServicePriority

shippingPolicyInfo.shippingProfileDiscountInfo.applyDomesticPromoShippingProfile
Item.ShippingDetails.PromotionalShippingDiscount

shippingPolicyInfo.shippingProfileDiscountInfo.applyIntlPromoShippingProfile
Item.ShippingDetails.InternationalPromotionalShippingDiscount

shippingPolicyInfo.shippingProfileDiscountInfo.domesticFlatCalcDiscountProfileId
Item.ShippingDetails.ShippingDiscountProfileID

shippingPolicyInfo.shippingProfileDiscountInfo.intlFlatCalcDiscountProfileId
Item.ShippingDetails.InternationalShippingDiscountProfileID

Working with the Business Policies Management API

API Call Limits

Please refer to the API

Call Limits page on the eBay Developers Program site for
current default call limits and call limits for applications that
have completed the Compatible Application Check, which is a free service that the eBay
Developers Program provides to its members.

Sandbox Environment

Customers can enable Business Policies in their Sandbox account by going to the Business Policies Sandbox Opt-in page. For more information about testing Business Policies, refer to Testing Overview in
the Making a Business Policies Management API Call document.

API Reference

Refer to the API Reference index for
a list of calls in the Business Policies Management API. The API Reference includes the following information:

Prototypes of the request and response structure for each call
Comprehensive list of inputs and outputs supported by each
call and descriptions of their meaning and behavior
Call samples (request and response)
Index of schema elements (types, fields, enumerations)
Change history information for each call