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:

1. 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.
2. Define the policy type by including the profileType field and setting its value to 'PAYMENT', 'RETURN_POLICY' or 'SHIPPING'.
3. 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).
4. Optionally, provide a text description of the business policy through the profileDesc field.
5. 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.
6. 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.

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.

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.

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.

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.

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

Back to top

Additional Resources

You can get more information about the eBay Business Policies Management API at these locations:

• Making an API Call
• API Reference
• Release Notes