eBay Business Policies Management API Users Guide Support     Knowledge Base     Forums     All Tutorials     All Code Samples Users Guide Call Reference Making a Call Tutorials Release Notes

• Introduction to Business Policies
• Overview of the Service
  • About categoryGroup and categoryGroups
  • Creating a Business Policies Profile
  • Modifying a Business Policies Profile
  • Retrieving Business Policies Profiles
  • Deleting a Business Policies Profile
• Business Policies Use Cases
  • Opting into the Business Policies Management Service
  • Mapping Business Policies Management API Fields to Trading API Fields
  • Plans to Deprecate CalculatedShippingRate Container in Trading API
  • Differences Between Business Policies Profiles and Trading API Listing Fields
• Working with the Business Policies Management API
  • API Call Limits
  • Sandbox Environment
  • API Reference
• Additional Resources
• User-Contributed Notes

Introduction to Business Policies

Business Policies Management API allows sellers to create and manage payment, return policy, and shipping profiles. Sellers can easily create these Business Policies profiles 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 Policies profile and immediately apply it 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. This API will help sellers save significant time in creating and updating their listings.  

Business Policies are not yet available to all sellers. Once Business Policies become available to a seller, that seller must opt in to Business Policies through the Sell tab 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. A seller cannot use the Business Policies Management API in the Production environment to create and manage profiles until their account has been opted in to Business Policies. Beginning in mid-June 2013, all sellers will be opted in to Business Policies automatically.

Once a seller is opted in to Business Policies, eBay will automatically create some Business Policies profiles 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 policy, and shipping profiles as they want, but there can only be one default profile for each policy type/category group pair. The seller can manage which profiles are used by default through My eBay. A seller can also discover which payment, return policy, and shipping profiles are default 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.SupportedSellerProfiles.SupportedSellerProfile.CategoryGroup.IsDefault field. If the seller had a default payment profile for Motor Vehicle listings and a default payment profile for all other listings, you might see the following nodes in the GetUserPreferences response:

...
<SupportedSellerProfile>
  <ProfileID>5195425014</ProfileID>
  <ProfileType>PAYMENT</ProfileType>
  <ProfileName>standardpaymentprofile</ProfileName>
  <ShortSummary>Default Payment Profile for all non-vehicle listings</ShortSummary>
  <CategoryGroup>
    <Name>ALL</Name>
    <IsDefault>true</IsDefault>
  </CategoryGroup>
</SupportedSellerProfile>
...

...
<SupportedSellerProfile>
  <ProfileID>5267672014</ProfileID>
  <ProfileType>PAYMENT</ProfileType>
  <ProfileName>vehiclepaymentprofile</ProfileName>
  <ShortSummary>Default Payment Profile for vehicle listings</ShortSummary>
  <CategoryGroup>
    <Name>MOTORS_VEHICLE</Name>
    <IsDefault>true</IsDefault>
  </CategoryGroup>
</SupportedSellerProfile>
...

Once a seller's account is opted into Business Policies, the payment, return policy, and shipping options/values set in the default profiles 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 the seller has the option of using/referencing another (non-default) Business Policies profile (in Web flow or through the Item.SellerProfiles container in an Add/Revise/Relist Trading API call).

Overview of the Service

The Business Policies Management API is a SOA service that is meant to be consumed by sellers who want to programmatically create and manage Business Policies profiles. The service allows you to create payment, return policy, and shipping Business Policies profiles. The settings/values captured in these profiles 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 the item belongs to (based on the eBay category the item is listed under), and then retrieves and applies the default Business Policies profile(s) for that Business Policies category group.

Previous to the concept of Business Policies profiles, a seller had to assign and update payment, return policy, 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 flor or through Trading API's Add/Revise/Relist calls) the process of listing, revising, or relisting an item.

About categoryGroup and categoryGroups

A categoryGroup is a group of eBay categories. A categoryGroup connects a group of categories to a Business Policies profile. This lets you create a Business Policies profile that can be applied to many categories. The relationship between a categoryGroup and a Business Policies profile is:

• One profile can be associated with multiple category groups.
• A categoryGroup can be associated with many profiles.

  Currently, the valid values for categoryGroup are ALL (all non- motor vehicle categories) and MOTORS_VEHICLE (all motor vehicle categories). In the future, there may be other valid values for categoryGroup.
  

  The first profile (payment, return policy, or shipping) you create (or eBay creates for you) for a categoryGroup becomes the default profile for that category group and profile type combination. However, you can modify the "default" payment, return policy, or shipping profile through My eBay or through the setSellerProfile call. Only one profile can be set as default for the category group and profile type combination at any given time.

Creating a Business Policies Profile

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

1. Assign a category group to which the profile will apply by setting the categoryGroup.name value to 'ALL' or 'MOTORS_VEHICLE'. Optionally, set the assigned category group as default by including and setting the categoryGroup.default value to 'true'. If the categoryGroup.default field is included and set to 'true', the profile (and its settings) will apply to all listings that fall under that category group. However, the seller cannot pass in a categoryGroup.default value of 'true' if a default profile already exists for that category group and profile type combination.
2. Define the profile type by including the profileType field and setting its value to 'PAYMENT', 'RETURN_POLICY' or 'SHIPPING'.
3. Assign a name to the profile through the profileName field. It is a good idea to give the profile a descriptive name so you can easily identify it.
4. Optionally, provide a text description of the profile 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 profile type that is being created through the paymentProfile.paymentInfo, returnPolicyProfile.returnPolicyInfo, and/or shippingPolicyProfile.shippingPolicyInfo containers.

Modifying a Business Policies Profile

To modify an existing Business Policies profile, you use the setSellerProfile call. First, you want to identify the payment, return policy, or shipping profile 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 profile or add fields to a profile. For example, you might want to add additional acceptedPaymentMethod values for a payment profile, 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 profile for a category group and profile type combination. It would actually require two setSellerProfile calls to perform this action. In the first call, you'd identify the current default profile through the profileId field, identify the category group that the profile 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 profile that you want set as the new default profile through the profileId field, identify the category group that the profile belongs to in the categoryGroup.name field, and then pass in a value of 'true' in the categoryGroup.default field.

Retrieving Business Policies Profiles

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

Deleting a Business Policies Profile

To delete one Business Policies profile, you use the removeProfile call. To identify the profile to delete, the seller passes in the profileId value.

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.

Plans to Deprecate CalculatedShippingRate Container in Trading API

With Business Policies coming online, there are plans to deprecate the CalculatedShippingRate container and replace it with the ShippingPackageDetails container. The table belows maps the "old" Trading API fields with the "new" Trading API fields:

Differences Between Business Policies Profiles and Trading API Listing Fields

In addition to the new ShippingPackageDetails container replacing the CalculatedShippingRate, Business Policies is also introducing a few more changes when listing an item. The new fields and changes are summarized below:

• dispatchTimeReason: this new shipping profile field allows the seller to provide a text description that provides more detail about handling time and the shipping of an item.
• separate enumeration values used to specify domestic and international shipping services: shippingPolicyInfo.domesticShippingType and shippingPolicyInfo.intlShippingType values in a Business Policies shipping profile will replace the enumeration value specified in the Trading API through the Item.ShippingDetails.ShippingType field.
• shippingOption: this new shipping profile enumeration value allows the seller to to summarize which regions/countries he/she is willing to ship to.
• buyerResponsibleForPickup: this new shipping profile boolean field allows the seller to communicate to the buyer that the buyer is responsible for the pickup of the vehicle.
• freightShipping: this container allows the seller to provide more information to the buyer regarding freight shipping details.

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

For more information about testing, refer to Testing Overview in the Making a Business Policies Management API Call document.

API Reference

Refer to the Call Reference [(https://go.developer.com/developers/ebay/products/business-policies-api)]for a list of calls in the Business Policies Management API. The Call 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
• Call Reference
• Release Notes

Back to top

User-Contributed Notes

Share tips or code samples related to this call or topic. Questions or observations are welcome, too.

eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.

Copyright © 2009–2013 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.