This doc page has moved! You should be automatically redirected to the new location. If you are not redirected automatically, follow this link to the new page.

You are here: Sell APIs > Selling Integration Guide > Configuring seller accounts > Establishing your business policies

eBay business policies

The Account API allows merchants to create business policies that describe how they conduct their customer-facing business.

These policies inform customers about their payment options, the different types of shipping services the merchant uses, and how they handle returns. Merchants who create multiple listings can simplify the process by creating a standardized set of business policies that they can apply to any, or all, of their listings.

By configuring policies, sellers don't have to re-enter the same information for each listing they create. Streamlining this part of the process lets sellers concentrate on the individualized content needed for their multiple listings. Also, using an establishing set of business policies gives sellers the ability to partially automate the process of listing, revising, and relisting their items.

Establishing your business policies

The Account API gives sellers a way to programmatically set-up and update the policies that describe how they do business. At a minimum, merchants should define a basic policy for each of the three policy types:

  • Payment policy - Payment policies lets merchants establish special payment instructions, define the types of payments they accept, outline the terms of payments, and details any deposits required if they sell on the MOTORS platform.
  • Fulfillment policy - Fulfillment policies define the type of shipping and pickup options a merchant offers their buyers. For example, a fulfillment policy describes whether or not a merchant charges for shipping and handling, and the locations to where the merchant does (or does not) ship. Merchants can also describe whether or not they allow for the local pick-up of items, and other details about how they fulfill orders.
  • Return policy - Return Policies describe how a merchant handles returns, and it details the methods of return a merchant accepts. Return policies answer the questions of whether or not a merchant charges a restocking fee, and who (by default) pays for the return shipping.

When you create a new policy, you assign to it a unique user-defined name, and you can use that name to refer to the policy when you list an item. In addition, eBay returns a unique policy ID value when you create a new policy, and you can also use that value to refer to the policy.

Multiple policies for a given policy type

Sellers should have a minimum of three business policies-one for each policy type (payment, fulfillment, and return). However, sellers can create multiple policies for each given policy type. For example, you might create several payment policies and apply them depending on the various item costs or promotions you offer, or perhaps you use multiple fulfillment policies that you apply depending on the size, weight and destination of the items you sell.

Because every business policy applies to a specific marketplace, the number of business policies compounds when a seller targets multiple marketplaces.

Business policy category types

Category types separate items into broad categories, and you must associate each business policy you create with a category type. eBay currently defines two category types, splitting item listings into ones that offer motor vehicles and all others that do not.

The CategoryTypeEnum data type declares the following two enum values:

  • ALL_EXCLUDING_MOTORS_VEHICLES
  • MOTORS_VEHICLES

Merchants often sell into only one category type (either they sell vehicles or they don't), and because of this it's likely all your business policies will target the same category type.

Note: For motor vehicle listings, all returns are handled at the seller's discretion and are processed outside of the eBay flow. Because of this, you cannot associate an eBay return policy with a motor vehicle item, which means all return policies have the same category type: ALL_EXCLUDING_MOTORS_VEHICLES

If a merchant sells into just one marketplace, but sells both category types, they should create a minimum of five business policies: a payment, fulfillment, and return policy for the ALL_EXCLUDING_MOTORS_VEHICLES category type, and payment and fulfillment policies for the MOTORS_VEHICLES category type (remember, you don't create return policies for motor vehicle listings).

Default policies

As stated above, when you create a new policy, you must specify the marketplace and the category type to which the policy applies. eBay lets you define a default category type for a marketplace, meaning that eBay will use that default policy when you create a listing without a specified category. Sellers can manage which policies are used by default through My eBay, or by programmatically setting the policy they want to be the default policy using the categoryTypes.default field.

To streamline the process of creating item listings, eBay assigns a default status to certain policies, and eBay automatically populates the respective policy settings with the default policies when a merchant creates listings through the Web flow.

Tip: While you can designate any policy to be the default policy for any marketplace/category type pair, eBay only uses default policy settings when you create item listings using the Web flow. eBay ignores the default policy settings when you programmatically create and manage item listings.

eBay sets the default status on the categoryTypes.default flag. When this flag is set to true on a policy, it means that the associated policy is the default policy for the specified categoryTypes and marketplace pair.

For example, suppose a merchant sells into one category type (ALL_EXCLUDING_MOTORS_VEHICLES) and one marketplace, and they have three fulfillment policies to cover different package sizes. The first fulfillment policy they create is automatically set to be the default policy for the category type, and eBay auto-populates the fulfillment policy fields with the values of this policy whenever they list an item that falls into ALL_EXCLUDING_MOTORS_VEHICLES category type. Each marketplace/categoryType pair can have only one default policy for each policy type, but you can designate any policy to be the default through the Web flow or programmatically using the Account API.

Using your configured policies

To take advantage of the business policies you create, you must opt-in to the SELLING_POLICY_MANAGEMENT seller program using the Opt-in to Program call in the Account API. Opting in to this program lets eBay associate the policies you create with the items you list.

Once you've opted in to the Selling Policy Management program, you can use any of the business policies you've created by referring to them when you list an item.

Note: Even though each policy type has a default policy for a marketplace and categoryType pair, you must specify each policy you want to use for the listing by referencing the policyId and name values. eBay uses the default policy only when you create items via the Web flow.

Using Create Offer to list items

If you use the Inventory API to create and publish item listings, use policy IDs to reference the policies you want to use for your item listings.

When you create a new policy (be it a payment policy, fulfillment policy, or return policy), eBay returns a unique policy ID for the newly created policy. Use these values to populate the listingPolicies container of the Create Offer call in the Inventory API:

"listingPolicies":
    { /* ListingPolicies */
    "fulfillmentPolicyId": string,
    "paymentPolicyId": string,
    "returnPolicyId": string,
    ...

Using AddItem to list items

When you use the Trading API AddItem call to create item listings, you can refer to the policy by the unique name you gave to the policy when you created it, or by the policy ID value that eBay returns after it creates the policy.

When you create a new listing with AddItem, specify the three policies you want to associate with the item, using either the unique name or policyId values, in the SellerProfiles container:

    <SellerProfiles>
      <SellerPaymentProfile>
        <PaymentProfileID>paymentPolicyId_Value</PaymentProfileID>
        <PaymentProfileName>User-Defined-Policy-Name</PaymentProfileName>
      </SellerPaymentProfile>
      <SellerReturnProfile>
        <ReturnProfileID>returnPolicyId_Value</ReturnProfileID>
        <ReturnProfileName>User-Defined-Policy-Name</ReturnProfileName>
      </SellerReturnProfile>
      <SellerShippingProfile>
        <ShippingProfileID>fulfillmentPolicyId_Value</ShippingProfileID>
        <ShippingProfileName>User-Defined-Policy-Name</ShippingProfileName>
      </SellerShippingProfile>
    </SellerProfiles>

Managing your business policies

Once you have established a set of business policies to use with your item listings, you can use the Account API to manage the policies. The API contains get, modify, and delete calls for each of the policy types.

Retrieving policies

There are several ways you can retrieve the business policies that you've created. Use the following operations for the type of policy you want to retrieve; either a payment, fulfillment, or return policy:

  • Get <Policy-Type> Policies by Marketplace operation retrieves all the payment, fulfillment, or return policies you've created for a single marketplace.
  • Get <Policy-Type> Policy by ID retrieves a policy by its eBay-assigned ID.
  • Get <Policy-Type> Policy by Name retrieves a policy by its user-defined name.

Modifying policies

Sellers can modify existing policies using the Update a Payment Policy, Update a Fulfillment Policy, and Update a Return Policy calls. In each call, specify the policy ID of the policy you want to update, and supply a complete policy payload to define the updated policy.

You can modify any value defined in a business policy, except for the policy name and policy ID fields. For example, you might want to update a policy by adding additional paymentMethod values for a payment policy, or modifying the text description of a return policy by updating the description field of the policy.

Modifying policies referenced by existing listings

When you modify a business policy, listings that reference that policy are updated with your new policy details. This is true for all listings, except for (1) those that are in the restricted revise mode (which includes listings that have existing bids or sales on them) and (2) those that fail the revise listing validation process as a result of your policy updates.

If your modified business policy cannot be inherited by all your active listings, eBay creates a 'clone' of the original policy, assigns it a new policy ID, and applies that new policy ID to the listings that cannot inherit the updated policy. This effectively leaves the policy details unchanged for any policies that cannot inherit your new policy updates.

For example, suppose you modify policy P1. Listings that reference that policy are modified according to your new policy updates. For these listings, the policy ID stays the same but the details of the policy are updated. However, if there are any active listings that cannot inherit the updates you make to P1, eBay creates a copy of P1 before it applies the updates and gives it a new policy ID. Let's call this new, unchanged policy P2. Any listings that cannot inherit the updates made to P1 are assigned the ID of policy P2 (which essentially leaves the policy details unchanged). Once all listings that point to policy P2 are completed, you can safely delete the obsolete P2 policy.

Managing default policies

Each fulfillment, payment, and return policy type has a default policy for each marketplaceId and categoryTypes.name combination. For example, you can have multiple payment policies applied to the ALL_EXCLUDING_MOTORS_VEHICLES category type in the US marketplace, but only one can be the default payment policy for that combination. Default policies simplify the process of creating listings when you use the eBay Web flow to create listings.

Important! The default status of a policy is considered only when you create item listings using the eBay Web flow. If you programmatically create listings, then you must specifically set the policies you want applied to the listing in the payload of the call that creates the listing.

For each policy type, eBay automatically assigns the default status to the first policy you create for each marketplaceId and categoryTypes.name combination. You can manage the default policy settings using either the Web flow or the Account API.

To programmatically manage the default policy settings, use the policy type's Update operation to change the default setting for a policy from false to true for a specific marketplaceId and categoryTypes.name combination. Do this by calling Update using the ID of the specific policy you want to set as the default, and set the default field to true. When you do so, eBay automatically updates the existing default policy for the same marketplaceId and categoryTypes.name combination to false. Note that you do not need to first set the current default policy to false (in fact, eBay prevents you from doing so).

Deleting a Business Policy

The Account API has a delete policy operation for each policy type: Delete a Payment Policy, Delete a Fulfillment Policy, and Delete a Return Policy. Supply the policy ID as a path parameter to delete the specified policy.

Identify the policies you want to delete using the get by marketplace calls (for example, Get Payment Policies by Marketplace).

Note: A business policy that is associated to one or more active listings cannot be deleted. Instead, you must reassign the policy in these listings to another active business policy using a ReviseItem call. Similarly, you cannot delete the default policy for a policy type (return, payment, shipping).

The Account API reference

Refer to the API Reference for the Account API calls that you can use to configure and manage your eBay seller account. 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, with descriptions of their meaning and behavior
  • Call samples that include both request and response bodies
  • Index of schema elements (types, fields, enumerations)
  • A Change History that details the release information for each call