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

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).

Using configured policies

To take advantage of the business policies you create, you must opt-in to the SELLING_POLICY_MANAGEMENT seller program using the optInToProgram 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.

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 createOffer 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 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 operation retrieves all the payment, fulfillment, or return policies you've created for a single marketplace.
• get<Policy-Type>Policy retrieves a policy by its eBay-assigned ID.
• get<Policy-Type>PolicyByName retrieves a policy by its user-defined name.

Modifying policies

Sellers can modify existing policies using the updatePaymentPolicy, updateFulfillmentPolicy, and updateReturnPolicy 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.

Deleting a Business Policy

The Account API has a delete policy operation for each policy type: deletePaymentPolicy, deleteFulfillmentPolicy, and deleteReturnPolicy. 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, getPaymentPolicies).

The Account API reference

Refer to the Account API Reference for the 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)