Migrating AddItem business policies to the Account API

This topic describes how to migrate the business-policy configurations you create in the Trading API to the business policies that you create and manage with the Account API.

When you create an item listing by calling AddItem, you can configure payment, return, and shipping policies within the payload of the call. These business policies are not saved to your user account, but instead are business policies that are tied to that specific item instance. If you've configured item-centric business policies using AddItem, this topic can help you migrate those policies to the Account API where you can save and maintain the policies you create.

The Account API is a RESTful API that lets you configure a set of reusable business policies to suit the various needs of a seller. You can create multiple policies for a single marketplace, which gives you flexibility in the policies you assign to the different item listings you create.

Using the migration tables

The Account API lets you create and manage three types of business policies and this topic has a mapping table for each policy type:

In each table:

  • The left column lists the fields you need to configure to create a new Account API business policy. Unless a field is optional, you must supply values for each of the fields listed in left column to create a new Account API business policy.
  • The right column shows the mapping, if one exists, between a policy field in an AddItem call and the associated field in the Account API business policy. This column shows whether their is an equivalent field in AddItem and if not, it gives a brief description of what is needed to configure the field in the new Account API business policy.

Refer to the Account API Reference for the details on configuring the settings for each business policy.

Getting your current item business policies

Using the Trading API, call GetMyeBaySelling to retrieve multiple active and completed listings. From there, inspect the Item objects in the response payload to review the policy configurations that you've previously set up, and use these settings as a base when you create new Account API policies.

Using the Account API business policies in AddItem calls

When you create either a fulfillment, payment, or return business policy with the Account API, the new policy is assigned a policy ID that uniquely identifies the policy. In an AddItem call, specify the ID of the policy you want to reference using the following fields:

  • Item.SellerProfiles.SellerPaymentProfile.PaymentProfileID
  • Item.SellerProfiles.SellerReturnProfile.ReturnProfileID
  • Item.SellerProfiles.ShippingPaymentProfile.ShippingProfileID

Fulfillment policy migration

The table below lists the mappings between the Trading API's AddItem call and the fields needed to create a new fulfillment policy using the createFulfillmentPolicy method in the Account API.

Fulfillment Policy Field

Fulfillment Policy Field Equivalent in AddItem

categoryTypes.default No equivalent. This Boolean value defaults to true if it's the first fulfillment policy created for the category type and marketplace, otherwise defaults to false.
categoryTypes.name No equivalent. Set to either MOTORS_VEHICLES or ALL_EXCLUDING_MOTORS_VEHICLES.
description No equivalent. Optional seller-defined policy description for seller's internal use.
freightShipping No direct equivalent. Set this Boolean value to true if this fulfillment policy applies to freight shipments. Note that in AddItem, seller's indicate freight shipping by setting Item.ShippingDetails.ShippingType to Freight or FreightFlat.
globalShipping Equals Item.ShippingDetails.GlobalShipping.
handlingTime.unit No equivalent. Set to DAYS.
handlingTime.value Equals Item.DispatchTimeMax.
localPickup No equivalent. Set to true if the seller offers only local pickup, usually from a non-business address (used for customer-to-customer sales).
marketplaceId No direct equivalent, use the marketplaceId equivalent of the site indicated by Item.Site.
name No equivalent. This is a seller-defined policy name for seller's internal use. Roughly equal to Item.SellerShippingProfile.ShippingProfileName, but designed for a seller's own use.
pickupDropOff Not used (deprecated).
shippingOptions All shippingOptions settings apply to either DOMESTIC or INTERNATIONAL shipping policy, as specified by the optionType setting in the associated shippingOptions container. When mapping fields from AddItem, make sure to map the domestic and international field values to the correct shippingOptions container in your fulfillment policy.
shippingOptions.costType No direct equivalent, roughly equals Item.ShippingDetails.ShippingType. Set to either FLAT_RATE, CALCULATED, or NOT_SPECIFIED in either your DOMESTIC or INTERNATIONAL shippingOptions containers.
shippingOptions.insuranceFee Not used (deprecated).
shippingOptions.insuranceOffered Not used (deprecated).
shippingOptions.optionType No equivalent. Set to either DOMESTIC or INTERNATIONAL. Note that in AddItem, seller's use the following containers to indicate domestic and international shipping policies:
  • Item.ShippingDetails.ShippingServiceOptions
  • Item.ShippingDetails.internationalShippingServiceOptions
shippingOptions.packageHandlingCost.currency Equals the following fields for either a domestic or international shipping policy:
  • Item.ShippingDetails.CalculatedShippingRate.PackagingHandlingCosts currencyId
  • Item.ShippingDetails.CalculatedShippingRate.InternationalPackagingHandlingCosts currencyId
shippingOptions.packageHandlingCost.value Equals the following fields for either a domestic or international shipping policy:
  • Item.ShippingDetails.CalculatedShippingRate.PackagingHandlingCosts
  • Item.ShippingDetails.CalculatedShippingRate.InternationalPackagingHandlingCosts
shippingOptions.rateTableId Equals the following fields for either a domestic or international shipping policy:
  • Item.ShippingDetails.DomesticRateTableId
  • Item.ShippingDetails.InternationalRateTableId
shippingOptions.shippingServices.additionalShippingCost.currency Equals Item.ShippingDetails.ShippingServiceOptions.ShippingServiceAdditionalCost currencyId.
shippingOptions.shippingServices.additionalShippingCost.value Equals Item.ShippingDetails.ShippingServiceOptions.ShippingServiceAdditionalCost.
shippingOptions.shippingServices.buyerResponsibleForPickup No equivalent. This Boolean value defaults to false and applies only to motor vehicles sales.
shippingOptions.shippingServices.buyerResponsibleForShipping Equals Item.BuyerResponsibleForShipping. This Boolean value defaults to false and applies only to motor vehicles sales. If set to true, seller should detail the shipping requirements in the item description.
shippingOptions.shippingServices.cashOnDeliveryFee.currency Equals Item.ShippingDetails.CODCost currencyId.
shippingOptions.shippingServices.cashOnDeliveryFee.value Equals Item.ShippingDetails.CODCost.
shippingOptions.shippingServices.freeShipping Equals Item.ShippingDetails.ShippingServiceOptions.FreeShipping.
shippingOptions.shippingServices.shippingCarrierCode No direct equivalent. Set to the shipping carrier associated with the shippingServiceCode.
shippingOptions.shippingServices.shippingCost.currency Equals Item.ShippingDetails.ShippingServiceOptions.ShippingServiceCost currencyId, used for flat-rate shipping.
shippingOptions.shippingServices.shippingCost.value Equals Item.ShippingDetails.ShippingServiceOptions.ShippingServiceCost.
shippingOptions.shippingServices.shippingServiceCode Equals the following fields for either a domestic or international shipping policy:
  • Item.ShippingDetails.ShippingServiceOptions.ShippingService
  • Item.ShippingDetails.InternationalShippingServiceOptionShippingService
shippingOptions.shippingServices.shipToLocations.regionExcluded.regionName Not applicable at this level.
shippingOptions.shippingServices.shipToLocations.regionExcluded.regionType Not applicable at this level.
shippingOptions.shippingServices.shipToLocations.regionIncluded.regionName Equals Item.ShipToLocation.
shippingOptions.shippingServices.shipToLocations.regionIncluded.regionType Reserved for future use.
shippingOptions.shippingServices.sortOrder Equals the following fields for either a domestic or international shipping policy:
  • Item.ShippingDetails.ShippingServiceOptions.ShippingServicePriority
  • Item.ShippingDetails.ShippingServiceOptions.InternationalShippingServicePriority
shippingOptions.shippingServices.surcharge.currency Equals Item.ShippingDetails.ShippingServiceOptions.ShippingSurcharge currencyId.
shippingOptions.shippingServices.surcharge.value Equals Item.ShippingDetails.ShippingServiceOptions.ShippingSurcharge.
shipToLocations.regionExcluded.regionName Equals Item.ShippingDetails.ExcludeShipToLocation.
shipToLocations.regionExcluded.regionType Reserved for future use.
shipToLocations.regionIncluded.regionName Not applicable at this level.
shipToLocations.regionIncluded.regionType Not applicable at this level.

 

Payment policy migration

The table below lists the mappings between the Trading API's AddItem call and the fields needed to create a new payment policy using the createPaymentPolicy method in the Account API.

Payment Policy Field

Payment Policy Field Equivalent in AddItem

categoryTypes.default No equivalent. Boolean value defaults to true if it's the first payment policy created for the category type and marketplace, otherwise defaults to false.
categoryTypes.name No equivalent. Set to either MOTORS_VEHICLES or ALL_EXCLUDING_MOTORS_VEHICLES.
deposit.amount.currency Equals Item.PaymentDetails.DepositAmount currencyId (deposits apply to motor vehicle listings).
deposit.amount.value Equals Item.PaymentDetails.DepositAmount.
deposit.dueIn.unit No equivalent. Set to HOURS.
deposit.dueIn.value Equals Item.PaymentDetails.HoursToDeposit.
deposit.paymentMethods.brands Not applicable at this level.
deposit.paymentMethods.paymentMethodsType Equals Item.PaymentMethods (for vehicle deposits, must be set to PAYPAL).
deposit.paymentMethods.recipientAccountReference.referenceId Equals Item.PayPalEmailAddress.
deposit.paymentMethods.recipientAccountReference.referenceType No equivalent. If deposit.paymentMethods.paymentMethodsType is set to PAYPAL, set this value to PAYPAL_EMAIL.
description No equivalent. Optional seller-defined policy description for seller's internal use.
fullPayments.dueIn.unit No equivalent. Set to DAYS.
fullPayments.dueIn.value Equals Item.PaymentDetails.DaysToFullPayment.
immediatePay Equals Item.AutoPay.
marketplaceId No direct equivalent, use the marketplaceId equivalent of the site indicated by Item.Site.
name No equivalent. Seller-defined policy name for seller's internal use.
paymentInstructions Equals Item.PaymentInstructions.
paymentMethods.brands Equals Item.PaymentMethods (credit card-brand options only).
paymentMethods.paymentMethodsType Equals Item.PaymentMethods (minus credit-card brand options).
paymentMethods.recipientAccountReference.referenceId Equals Item.PayPalEmailAddress.
paymentMethods.recipientAccountReference.referenceType No equivalent. If in the return policy deposit.paymentMethods.paymentMethodsType is set to PAYPAL, set this value to PAYPAL_EMAIL.

 

Return policy migration

The table below lists the mappings between the Trading API's AddItem call and the fields needed to create a new return policy using the createReturnPolicy method in the Account API.

Return Policy Field

Return Policy Field Equivalent in AddItem

categoryTypes.default No equivalent. Boolean value defaults to true if it's the first payment policy created for the category type and marketplace, otherwise defaults to false.
categoryTypes.name No equivalent. Set to either MOTORS_VEHICLES or ALL_EXCLUDING_MOTORS_VEHICLES.
description No equivalent. Optional seller-defined policy description for seller's internal use.
extendedHolidayReturnsOffered Not used (deprecated).
internationalOverride.returnMethod No direct equivalent, but similar to Item.ReturnPolicy.InternationalRefundOption, and can be set to REPLACEMENT on the US marketplace.
internationalOverride.returnPeriod.unit No equivalent. Set to DAYS.
internationalOverride.returnPeriod.value No direct equivalent, equals the integer value of days as indicated by Item.ReturnPolicy.InternationalReturnsWithinOption.
internationalOverride.returnsAccepted Equals Item.ReturnPolicy.InternationalReturnsAcceptedOption.
internationalOverride.returnShippingCostPayer Equals Item.ReturnPolicy.InternationalCostPaidByOption.
marketplaceId No direct equivalent, use the marketplaceId equivalent of the site indicated by Item.Site.
name No equivalent. Seller-defined policy name for seller's internal use.
refundMethod Equals Item.ReturnPolicy.RefundOption. Must be set to MONEY_BACK.
restockingFeePercentage Not used (deprecated).
returnInstructions Equals Item.ReturnPolicy.Description. Valid for only sales in following countries: AT, DE, ES FR, and IT.
returnMethod No direct equivalent, but similar to Item.ReturnPolicy.RefundOption, and can be set to REPLACEMENT on the US marketplace.
returnPeriod.unit No equivalent. Set to DAYS.
returnPeriod.value No direct equivalent, equals the integer value of days as indicated by Item.ReturnPolicy.ReturnsWithinOption.
returnsAccepted Equals Item.ReturnPolicy.ReturnsAcceptedOption.
returnShippingCostPayer Equals Item.ReturnPolicy.CostPaidByOption.