Business Policies API

Business Policies Users Guide

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. Managing Business Policies through 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.

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 wish, 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 users who want to programmatically create and manage Business Policies profiles. The API 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 flow 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:

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. The 'MOTORS_VEHICLE' category group is not valid for Return Policy profiles, as Return Policy profiles cannot be used with motor vehicle listings.
  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. To delete multiple Business Policies profiles, you use the removeSellerProfiles call. To identify the profiles to delete, the seller passes in multiple profileIds values.

Consolidating Similar Shipping Profiles

Shipping profiles 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 profiles are consolidated, the shipping profile 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 profile (and all its values/settings) that is kept after the consolidation, but the shipping costs specified for each shipping service in the newly deleted shipping profiles are kept.

The status of a shipping profiles 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 profile, can be overridden by supplying a ShippingServiceCostOverrideList.ShippingServiceCostOverride container for each domestic and international shipping service defined through the shipping profile.

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

For all domestic shipping services defined in the shipping profile, the ShippingServiceType field in the ShippingServiceCostOverrideList.ShippingServiceCostOverride container should be set to 'Domestic', and for all international shipping services defined in the shipping profile, 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 profile.

Business Policies Profiles Eligible for eTRS

If the seller meets all Top-Rated Seller requirements, and the Business Policies profile 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 <a href="http://pages.ebay.com/help/sell/top-rated.html" target="_blank">Becoming a Top Rated Seller and qualifying for Top Rated Plus</a> 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.

ID
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 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 Item.ShippingDetails.PaymentInstructions
paymentInfo.paypalEmailAddress Item.PayPalEmailAddress
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 Item.ReturnPolicy.RestockingFeeValueOption
returnPolicyInfo.returnsAcceptedOption Item.ReturnPolicy.ReturnsAcceptedOption
returnPolicyInfo.returnsWithinOption Item.ReturnPolicy.ReturnsWithinOption
returnPolicyInfo.shippingCostPaidByOption Item.ReturnPolicy.ShippingCostPaidByOption
returnPolicyInfo.warrantyDurationOption Item.ReturnPolicy.WarrantyDurationOption
returnPolicyInfo.warrantyOfferedOption Item.ReturnPolicy.WarrantyOfferedOption
returnPolicyInfo.warrantyTypeOption Item.ReturnPolicy.WarrantyTypeOption
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 Item.ShippingDetails.ShippingServiceOptions.ShippingSurcharge
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 Item.ShippingDetails.InsuranceDetails.InsuranceFee
shippingPolicyInfo.insurance.domesticInsuranceOption Item.ShippingDetails.InsuranceDetails.InsuranceOption
shippingPolicyInfo.insurance.intlInsuranceFee Item.ShippingDetails.InternationalInsuranceDetails.InsuranceFee
shippingPolicyInfo.insurance.intlInsuranceOption Item.ShippingDetails.InternationalInsuranceDetails.InsuranceOption
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 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

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:

These Current Trading API fields... ...are being replaced by these fields
Item.ShippingDetails.CalculatedShippingRate.MeasurementUnit Item.ShippingPackageDetails. MeasurementUnit
Item.ShippingDetails.CalculatedShippingRate.PackageDepth
Item.ShippingPackageDetails. PackageDepth
Item.ShippingDetails.CalculatedShippingRate.PackageLength
Item.ShippingPackageDetails. PackageLength
Item.ShippingDetails.CalculatedShippingRate.PackageWidth
Item.ShippingPackageDetails. PackageWidth
Item.ShippingDetails.CalculatedShippingRate.ShippingIrregular
Item.ShippingPackageDetails. ShippingIrregular
Item.ShippingDetails.CalculatedShippingRate.ShippingPackage
Item.ShippingPackageDetails. ShippingPackage
Item.ShippingDetails.CalculatedShippingRate.WeightMajor
Item.ShippingPackageDetails.WeightMajor
Item.ShippingDetails.CalculatedShippingRate.WeightMinor
Item.ShippingPackageDetails.WeightMinor
Item.ShippingDetails.CalculatedShippingRate.OriginatingPostalCode Item.PostalCode

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:

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 API Reference index for a list of calls in the Business Policies Management API. The API Reference includes the following information:

Back to top

Additional Resources

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

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–2014 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.