account APIv1.4.0

createFulfillmentPolicy

POST
/fulfillment_policy
This method creates a new fulfillment policy where the policy encapsulates seller's terms for fulfilling item purchases. Fulfillment policies include the shipment options that the seller offers to buyers.

Each policy targets a marketplaceId and categoryTypes.name combination and you can create multiple policies for each combination. Be aware that some marketplaces require a specific fulfillment policy for vehicle listings.

A successful request returns the URI to the new policy in the Location response header and the ID for the new policy is returned in the response payload.

Tip: For details on creating and using the business policies supported by the Account API, see eBay business policies.

Marketplaces and locales

Policy instructions can be localized by providing a locale in the Accept-Language HTTP request header. For example, the following setting displays field values from the request body in German: Accept-Language: de-DE.

Target the specific locale of a marketplace that supports multiple locales using the Content-Language request header. For example, target the French locale of the Canadian marketplace by specifying the fr-CA locale for Content-Language. Likewise, target the Dutch locale of the Belgium marketplace by setting Content-Language: fr-BE.

Tip: For details on headers, see HTTP request headers.

Input

Resource URI (production)

POST https://api.ebay.com/sell/account/v1/fulfillment_policy

URI parameters

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.account

See OAuth access tokens for more information.

{ /* FulfillmentPolicyRequest */
"name" : "string",
}
Input container/fieldTypeDescription
categoryTypesarray of CategoryTypeThe CategoryTypeEnum value to which this policy applies. Used to discern accounts that sell motor vehicles from those that don't. (Currently, each policy can be set to only one categoryTypes value at a time.)

Occurrence: Required

categoryTypes.defaultbooleanSellers can create multiple policies for any marketplaceId and categoryTypes.name combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type name. However, only one policy can be the default for any marketplaceId and name combination, and eBay designates the first policy created for a combination as the default.

If set to true, this policy is the default policy for the associated categoryTypes.name and marketplaceId pair.

Note: eBay considers the status of this field only when you create listings through the Web flow. If you create listings using the APIs, you must specifically set the policies you want applied to a listing in the payload of the call you use to create the listing. If you use the Web flow to create item listings, eBay uses the default policy for the marketplace and category type specified, unless you override the default.

For more on default policies, see Changing the default policy for a category type.

Occurrence: Optional

categoryTypes.nameCategoryTypeEnumThe category type to which the policy applies (motor vehicles or non-motor vehicles).

Note for return policies: The 'MOTORS_VEHICLES' category type is not valid for return policies because eBay flows do not support the return of motor vehicles.

Occurrence: Required

descriptionstringAn optional seller-defined description of the fulfillment policy for internal use (this value is not displayed to end users).

Max length: 250

Occurrence: Optional

freightShippingbooleanIf set to true, the seller offers freight shipping. Freight shipping can be used for large items over 150 lbs.

Default: false

Occurrence: Optional

globalShippingbooleanIf set to true, the seller has opted-in to the eBay Global Shipping Program and that they use that service for their international shipments. Setting this value automatically sets the international shipping service for the policy to International Priority Shipping and the buyer does not need to set any other shipping services for their INTERNATIONAL shipping options (unless they sell items not covered by the Global Shipping Program).

If this value is set to false, the seller is responsible for manually specifying the international shipping services, as described in Setting up worldwide shipping.

To opt-in to the Global Shipping Program, log in to eBay and navigate to My Account > Site Preferences > Shipping preferences.

Default: false

Occurrence: Optional

handlingTimeTimeDurationSpecifies the maximum number of business days the seller commits to for preparing and shipping an order after receiving a cleared payment for the order. This time does not include the transit time it takes the shipping carrier to deliver the order.

Valid values can vary by site and by category. To obtain the supported values for a site, call GeteBayDetails in the Trading API with DetailName set to DispatchTimeMaxDetails, then inspect the DispatchTimeMaxDetails container in the response for the time values supported by the site (typical handling times are 0, 1, 2, 3, 4, 5, 10, 15, and 20, but these can vary by site and may change over time.)

This field is required when the seller uses a flat or calculated shipping service, and it does not apply when there is no shipping service specified (for example, if the policy specifies only localPickup or freightShipping). In these cases, this field is not used and you can set it to 0.

Note that Top-Rated sellers must offer same-day or one-day handling for a listing in order for that listing to receive a Top Rated Plus seal on the View Item or Search Results pages. To offer zero-day or one-day handling, set field to '0' or '1', respectively.

Min: 0 Max: 30

Occurrence: Required

handlingTime.unitTimeDurationUnitEnumA time-measurement unit that specifies a singular period of time.

A span of time is defined when you apply the value specified in the value field to the value specified for unit.

Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Required

handlingTime.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Required

localPickupbooleanIf set to true, no shipping is offered by this policy and the seller offers only local pickup of the item (normally from a non-business location). This option is most often used for customer-to-customer sales and if set, costType should be set to NOT_SPECIFIED.

Default: false

Occurrence: Optional

marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace to which this fulfillment policy applies. If this value is not specified, value defaults to the seller's eBay registration site.

Occurrence: Required

namestringA user-defined name for this fulfillment policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Required

pickupDropOffbooleanIf set to true, the seller offers the "Click and Collect" feature. Click and Collect is supported by the Inventory API, and it can be used with Add/Revise/Relist calls.

To enable "Click and Collect", a seller (1) must be eligible for Click and Collect and (2) must set this boolean field to 'true'. Currently, Click and Collect is available to only large retail merchants selling in the eBay AU and UK marketplaces.

In addition to setting this field, the merchant must also do the following to enable the "Click and Collect" option on a listing:

  • Have inventory for the product at one or more physical stores tied to the merchant's account.

    Sellers can use the createInventoryLocaion method in the Inventory API to associate physical stores to their account and they can then can add inventory to specific store locations.

  • Set an immediate payment requirement on the item. The immediate payment feature requires the seller to:
    • Set the immediatePay flag in the payment policy to 'true'.
    • Include only one paymentMethods field in the payment policy and set its value to PAYPAL.
    • Include a valid PayPal contact in the recipientAccountReference.referenceId field of the payment policy.
    • Have a valid store location with a complete street address.

When a UK merchant successfully lists an item with Click and Collect, prospective buyers within a reasonable distance from one of the merchant's stores (that has stock available) will see the "Available for Click and Collect" option on the listing, along with information on the closest store that has the item.

Default: false

Occurrence: Optional

shippingOptionsarray of ShippingOptionA list that defines the seller's shipping configurations for DOMESTIC and INTERNATIONAL order shipments.

shippingOptions is a list with a single element if the seller ships to only domestic locations. If the seller also ships internationally, the list contains a second element that defines their international shipping options.

Shipping options configure the high-level shipping settings that apply to orders, such as flat-rate or calculated shipping, any rate tables the seller wants to associate with the shipping services, plus other details (such as the shippingServices offered for domestic or international shipments).

Occurrence: Conditional

shippingOptions.costTypeShippingCostTypeEnumDefines whether the shipping cost is FLAT_RATE (the same rate for all buyers), CALCULATED (the shipping rate varies by the ship-to location and size and weight of the package, as defined by the item), or NOT_SPECIFIED (for use with local pickup).

Required if the policy offers shipping options using a shippingOptions container.

Occurrence: Conditional

shippingOptions.insuranceFeeAmountSellers can offer buyer-paid shipping insurance only when they ship to AU, FR, or IT. This value indicates the cost the buyer must pay to purchase shipping insurance for the items being shipped.

Required if shippingOptions.insuranceOffered is set to true.

Occurrence: Conditional

shippingOptions.insuranceFee.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Optional

shippingOptions.insuranceFee.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.insuranceOfferedbooleanIf set to true, the seller offers buyer-paid shipping insurance. The optionType shows whether this is for either a domestic or international shipment.

Buyer-paid shipping insurance is currently supported in only Australia (AU), France (FR), and Italy (IT).

Occurrence: Optional

shippingOptions.optionTypeShippingOptionTypeEnumUse this field to set the ShippingOption element to either DOMESTIC or INTERNATIONAL.

Required if the policy offers shipping options using a shippingOptions container.

Occurrence: Conditional

shippingOptions.packageHandlingCostAmountApplicable to only CALCULATED shipping, an amount a seller can add to cover packaging, handling, and insurance costs. This cost is an addition to the selected shipping service cost and is included in the sum of the final shipping service costs in the output. This field must specify a zero value if freeShipping is set to true.

If the seller offers domestic and international calculated shipping but sets this field for only domestic shipping, eBay also applies the cost to all international shipments. To specify a fee for only international shipments, set the a domestic packagingHandlingCost to 0.

Occurrence: Optional

shippingOptions.packageHandlingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Optional

shippingOptions.packageHandlingCost.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.rateTableIdstringA unique eBay-assigned ID associated with a user-created shipping rate table. The locality of a shipping rate table can be either DOMESTIC or INTERNATIONAL and you must ensure the value specified in this field references a shipping rate table that matches the type specified in the shippingOptions.optionType field. If you mismatch the types, eBay responds with a 20403 error.

Call getRateTable to retrieve information (including rateTableId values) on the rate tables configured by a seller. For information on creating rate tables, see Using shipping rate tables.

Occurrence: Optional

shippingOptions.shippingServicesarray of ShippingServiceContains a list of shipping services offered for either DOMESTIC or INTERNATIONAL shipments.

Sellers can specify up to four domestic shipping services and up to five international shipping services by using separate shippingService containers for each. Note that if the seller is opted in to the Global Shipping Program, they can specify only four other international shipping services, regardless of whether or not Global Shipping is offered as one of the services.

Required if the policy offers shipping options using a shippingOptions container.

Occurrence: Conditional

shippingOptions.shippingServices.additionalShippingCostAmountThe cost of shipping each additional item if the same buyer purchases a multiple quantity of the same line item. This field is applicable for policies that cover multiple-quantity, fixed-price listings and is not applicable for policies that apply to single-quantity listings.

Sellers can encourage buyers to purchase multiple items and by offering a shipping discount on added items. The value for this field should be lower than the value set for shippingCost and you can set this value to 0 to offer free shipping on added items. If this value is not set, it defaults to the value set for shippingCost.

Occurrence: Optional

shippingOptions.shippingServices.additionalShippingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Optional

shippingOptions.shippingServices.additionalShippingCost.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.shippingServices.buyerResponsibleForPickupbooleanThis field is only applicable to vehicle categories on eBay Motors (US and Canada). If set to true, the buyer is responsible for picking up the vehicle. Otherwise, the seller should specify the vehicle pickup arrangements in the item description.

The seller cannot modify this flag if the vehicle has bids or if the listing ends within 12 hours.

Default: false

Occurrence: Optional

shippingOptions.shippingServices.buyerResponsibleForShippingbooleanThis field is applicable for only items listed in vehicle categories on eBay Motors (US and Canada). If set to true, the buyer is responsible for the shipment of the vehicle. Otherwise, the seller should specify the vehicle shipping arrangements in the item description.

The seller cannot modify this flag if the vehicle has bids or if the listing ends within 12 hours.

Default: false

Occurrence: Optional

shippingOptions.shippingServices.cashOnDeliveryFeeAmountThe value indicates the Cash on Delivery (COD) fee that the seller charges if the buyer uses the CASH_ON_DELIVERY payment method. This fee is added to the total cost of the item, and the total cost is due from the buyer upon the delivery of the item. This field is applicable only if the buyer-selected payment method is 'COD' and the selected shipping service option supports a Cash on Delivery option.

To see if a domestic shipping service supports the Cash on Delivery option, call GeteBayDetails with DetailName set to ShippingServiceDetails, then review the response to see if CODService is set to true for the targeted shipping service.

Occurrence: Optional

shippingOptions.shippingServices.cashOnDeliveryFee.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Optional

shippingOptions.shippingServices.cashOnDeliveryFee.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.shippingServices.freeShippingbooleanIf set to true, the seller offers free shipping to the buyer. This field can only be included and set to 'true' for the first domestic shipping service option specified in the shippingServices container (it is ignored if set for subsequent shipping services). The first specified shipping service option has a sortOrder value of 1 or (if the sortOrderId field is not used) it is the shipping service option that's specified first in the shippingServices container.

Occurrence: Optional

shippingOptions.shippingServices.shippingCarrierCodestringThe shipping carrier, such as 'USPS', 'FedEx', 'UPS', and so on.

Occurrence: Optional

shippingOptions.shippingServices.shippingCostAmountFor FLAT_RATE shipping options, the amount specified in this field is the shipping cost for the selected shipping carrier and service. The amount supplied must exclude any additional shipping charges (such as the seller's handling charges or insurance).

This field is not applicable in CALCULATED shipping services (the cost for a calculated shipping service cannot be determined until the listing has ended and the buyer has specified a postal code).

This value is automatically set to '0.0' if freeShipping is set to true.

Required if the shipping option uses a FLAT_RATE cost type and freeShipping is false.

Occurrence: Conditional

shippingOptions.shippingServices.shippingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Optional

shippingOptions.shippingServices.shippingCost.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.shippingServices.shippingServiceCodestringThe shipping service that the shipping carrier uses to ship an item. For example, an overnight, two-day delivery, or other type of service. For details on configuring shipping services, see Setting the shipping carrier and shipping service values.

Occurrence: Optional

shippingOptions.shippingServices.shipToLocationsRegionSetThis object contains the regionIncluded and regionExcluded fields, which define the geographical regions that a seller does and does not cover by the associated shipping policy.

shipToLocations appears at both the top-level of the fulfillment policy as well as here, within the shippingOptions.shippingServices container. Within individual shippingServices containers, use the regionIncluded container to specify the list of regions to where a seller ships using that particular shipping service (you can use different shipping services to cover different regions).

Note that you do not populate the regionExcluded field at this level. Instead, excluded shipping regions using the top-level shipToLocations container to define the regions to where a seller does not ship with this fulfillment policy.

Every eBay marketplace supports its own set of regions that you can use in the regionIncluded field. To determine the valid 'Ship-To' values for a marketplace, call GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings that you use in the regionIncluded.regionName field.

When returned at this level, this container lists only the regionIncluded areas defined for the associated shippingService container.

For more details, see The shipToLocations container.

Occurrence: Optional

shippingOptions.shippingServices.shipToLocations.regionExcludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller does not ship. Populate regionExcluded in only the top-level shipToLocations container (do not populate this field within the shippingOptions container).

Normally a seller ships to as many areas as possible using both DOMESTIC and INTERNATIONAL shipping options and they don't have a need to exclude any regions from their ship-to locations. With this, there's no reason to set regionExclude fields. However, it makes sense to set the regionExcluded field when a seller wants to exclude a small area that's located within a larger area they service. For example, suppose a seller indicates they ship 'Worldwide', but for some reason must exclude a specific country, or world region, from the larger world area they ship to.

To retrieve the regions you can specify in the associated regionName field, call GeteBayDetails with DetailName set to ExcludeShippingLocationDetails, then review the Location fields in the response for the strings that you can specify regionExcluded.regionName.

Note that if a buyer's primary ship-to location is a region that a seller has excluded in their fulfillment policy (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on an item that uses that fulfillment policy.

For details on setting this field, see Excluding specific regions from included shipping areas.

Occurrence: Optional

shippingOptions.shippingServices.shipToLocations.regionExcluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Optional

shippingOptions.shippingServices.shipToLocations.regionExcluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Optional

shippingOptions.shippingServices.shipToLocations.regionIncludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller ships.

Important: Populate this field only when the parent shipToLocations object is located within a shippingOptions container (that is, the parent shipTolocations object must not be the one at the top-level of the policy). Also, this field needs to be populated only when the associated shippingOptions container has optionType set to INTERNATIONAL.

Withing an international shipping option, set this value to Worldwide to indicate the seller ships to all world regions. If needed, use the regionExcluded field to exclude any regions in the world to where the seller does not ship.

Each eBay marketplace supports its own set of allowable shipping locations. Obtain the valid 'Ship-To Locations' for a marketplace by calling GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings that you can specify in the regionIncluded.regionName field.

For DOMESTIC shipping options, eBay automatically uses the seller's listing country as the default regionIncluded country. For details on setting this field, see How to set up worldwide shipping.

This field is always returned in the shipping policy response.

Required if optionType set to INTERNATIONAL.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocations.regionIncluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Optional

shippingOptions.shippingServices.shipToLocations.regionIncluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Optional

shippingOptions.shippingServices.sortOrderintegerThis integer value controls the order that this shipping service option appears in the View Item and Checkout pages, as related to the other specified shipping service options.

Sellers can specify up to four domestic shipping services (in four separate shippingService containers), so valid values are 1, 2, 3, and 4. A shipping service option with a sortOrder value of '1' appears at the top of View Item and Checkout pages. Conversely, a shipping service option with a sortOrder value of '4' appears at the bottom of the list.

Sellers can specify up to five international shipping services (in five separate shippingService containers, so valid values for international shipping services are 1, 2, 3, 4, and 5. Similarly to domestic shipping service options, the sortOrder value of a international shipping service option controls the placement of that shipping service option in the View Item and Checkout pages. Set up different domestic and international services by configuring two shippingOptions containers, where you set shippingOptions.optionType to either DOMESTIC or INTERNATIONAL to indicate the area supported by the listed shipping services.

If the sortOrder field is not supplied, the order of domestic and international shipping service options is determined by the order in which they are listed in the API call.

Min: 1. Max: 4 (for domestic shipping service) or 5 (for international shipping service).

Occurrence: Optional

shippingOptions.shippingServices.surchargeAmountA fee that can be charged to US buyers when they have an item shipped via UPS or FedEx to Alaska, Hawaii or Puerto Rico.

Use this element only if the shipping option specifies a flat-rate service and the policy targets the MOTORS_VEHICLES category type in the US marketplace.

If some line items in an order have a surcharge, the surcharge amount is added only for those line items. This value is returned only when set. Note that you cannot add a surcharge to items shipped via the Global Shipping Program.

Occurrence: Optional

shippingOptions.shippingServices.surcharge.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Optional

shippingOptions.shippingServices.surcharge.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shipToLocationsRegionSetThis object contains the regionIncluded and regionExcluded fields, which define the geographical regions that a seller does and does not cover by the associated fulfillment policy.

shipToLocations appears at both the top-level of the fulfillment policy as well as within the shippingOptions.shippingServices container. Here at the top level, use the regionExcluded field to specify a list of regions that a seller does not ship to with this particular fulfillment policy.

Note that you don't populate the regionIncluded field at this level. Instead, specify the regions that are covered by this fulfillment policy in each of the shippingServices.shipToLocations.regionIncluded containers you configure.

Every eBay marketplace supports its own set of regions that you can use in the regionExcluded field. To determine the valid values for a marketplace, call GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings you use in regionExcluded.regionName fields.

Configuring shipToLocations can be tricky because the regionIncluded and regionExcluded fields are valid in different parts of the schema, and their allowable settings vary upon the context. For details on configuring these fields, see The shipToLocations container.

Occurrence: Optional

shipToLocations.regionExcludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller does not ship. Populate regionExcluded in only the top-level shipToLocations container (do not populate this field within the shippingOptions container).

Normally a seller ships to as many areas as possible using both DOMESTIC and INTERNATIONAL shipping options and they don't have a need to exclude any regions from their ship-to locations. With this, there's no reason to set regionExclude fields. However, it makes sense to set the regionExcluded field when a seller wants to exclude a small area that's located within a larger area they service. For example, suppose a seller indicates they ship 'Worldwide', but for some reason must exclude a specific country, or world region, from the larger world area they ship to.

To retrieve the regions you can specify in the associated regionName field, call GeteBayDetails with DetailName set to ExcludeShippingLocationDetails, then review the Location fields in the response for the strings that you can specify regionExcluded.regionName.

Note that if a buyer's primary ship-to location is a region that a seller has excluded in their fulfillment policy (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on an item that uses that fulfillment policy.

For details on setting this field, see Excluding specific regions from included shipping areas.

Occurrence: Optional

shipToLocations.regionExcluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Optional

shipToLocations.regionExcluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Optional

shipToLocations.regionIncludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller ships.

Important: Populate this field only when the parent shipToLocations object is located within a shippingOptions container (that is, the parent shipTolocations object must not be the one at the top-level of the policy). Also, this field needs to be populated only when the associated shippingOptions container has optionType set to INTERNATIONAL.

Withing an international shipping option, set this value to Worldwide to indicate the seller ships to all world regions. If needed, use the regionExcluded field to exclude any regions in the world to where the seller does not ship.

Each eBay marketplace supports its own set of allowable shipping locations. Obtain the valid 'Ship-To Locations' for a marketplace by calling GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings that you can specify in the regionIncluded.regionName field.

For DOMESTIC shipping options, eBay automatically uses the seller's listing country as the default regionIncluded country. For details on setting this field, see How to set up worldwide shipping.

This field is always returned in the shipping policy response.

Required if optionType set to INTERNATIONAL.

Occurrence: Conditional

shipToLocations.regionIncluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Optional

shipToLocations.regionIncluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Optional

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationThe location response header contains the URL to the newly created fulfillment policy. The URL includes the eBay-assigned fulfillmentPolicyId, which you can use to reference the policy.
{ /* SetFulfillmentPolicyResponse */
"name" : "string",
}
Output container/fieldTypeDescription
categoryTypesarray of CategoryTypeThe CategoryTypeEnum value to which this policy applies. Used to discern accounts that sell motor vehicles from those that don't. (Currently, each policy can be set to only one categoryTypes value at a time.)

Occurrence: Always

categoryTypes.defaultbooleanSellers can create multiple policies for any marketplaceId and categoryTypes.name combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type name. However, only one policy can be the default for any marketplaceId and name combination, and eBay designates the first policy created for a combination as the default.

If set to true, this policy is the default policy for the associated categoryTypes.name and marketplaceId pair.

Note: eBay considers the status of this field only when you create listings through the Web flow. If you create listings using the APIs, you must specifically set the policies you want applied to a listing in the payload of the call you use to create the listing. If you use the Web flow to create item listings, eBay uses the default policy for the marketplace and category type specified, unless you override the default.

For more on default policies, see Changing the default policy for a category type.

Occurrence: Always

categoryTypes.nameCategoryTypeEnumThe category type to which the policy applies (motor vehicles or non-motor vehicles).

Note for return policies: The 'MOTORS_VEHICLES' category type is not valid for return policies because eBay flows do not support the return of motor vehicles.

Occurrence: Always

descriptionstringAn optional seller-defined description of the fulfillment policy for internal use (this value is not displayed to end users).

Max length: 250

Occurrence: Conditional

freightShippingbooleanIf set to true, the seller offers freight shipping. Freight shipping can be used for large items over 150 lbs.

Occurrence: Always

fulfillmentPolicyIdstringA unique eBay-assigned ID for a fulfillment policy. This ID is generated when the policy is created.

Occurrence: Required

globalShippingbooleanIf set to true, the seller has opted-in to the Global Shipping Program and eBay automatically sets the international shipping service options to International Priority Shipping.

If the value of globalShipping is false, the seller is responsible for specifying one or more international shipping service options if they want to ship internationally.

Occurrence: Always

handlingTimeTimeDurationSpecifies the maximum number of business days the seller commits to for preparing and shipping an order after receiving a cleared payment for the order. This time does not include the transit time it takes the shipping carrier to deliver the order.

Note that Top-Rated sellers must offer same-day or one-day handling for a listing in order for that listing to receive a Top Rated Plus seal on the View Item or Search Results pages.

This field is required when the seller uses a flat or calculated shipping service, and it does not apply when there is no shipping service specified (for example, if the policy specifies only localPickup or freightShipping). In these cases, this field is not used and you can set it to 0.



Min: 0 Max: 30

Occurrence: Always

handlingTime.unitTimeDurationUnitEnumA time-measurement unit that specifies a singular period of time.

A span of time is defined when you apply the value specified in the value field to the value specified for unit.

Time-measurement units can be YEAR, MONTH, DAY, and so on. See TimeDurationUnitEnum for a complete list of possible time-measurement units.

Occurrence: Conditional

handlingTime.valueintegerAn integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

localPickupbooleanIf set to true, no shipping is offered by this policy and the seller offers only local pickup of the item (normally from a non-business location). This option is most often used for customer-to-customer sales and if set, costType should be set to NOT_SPECIFIED.

Occurrence: Always

marketplaceIdMarketplaceIdEnumThe ID of the eBay marketplace to which this fulfillment policy applies. If this value is not specified, value defaults to the seller's eBay registration site.

Occurrence: Required

namestringA user-defined name for this fulfillment policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Required

pickupDropOffbooleanIf set to true, the seller offers the "Click and Collect" option.

Currently, "Click and Collect" is available only to large retail merchants the eBay AU and UK marketplaces.

Occurrence: Always

shippingOptionsarray of ShippingOptionA list that defines the seller's shipping configurations for DOMESTIC and INTERNATIONAL order shipments.

The list has a single element if the seller ships to only domestic locations. If the seller also ships internationally, a second element defines their international shipping options.

Shipping options configure the high-level shipping settings that apply to orders, such as flat-rate or calculated shipping, and any rate tables the seller wants to associate with the shipping services.

Each shippingOption element has a shippingServices container that defines the list of shipping services (domestic or international) offered with this fulfillment policy.

Occurrence: Conditional

shippingOptions.costTypeShippingCostTypeEnumDefines whether the shipping cost is FLAT_RATE (the same rate for all buyers), CALCULATED (the shipping rate varies by the ship-to location and size and weight of the package, as defined by the item), or NOT_SPECIFIED (for use with local pickup).

Required if the policy offers shipping options using a shippingOptions container.

Occurrence: Conditional

shippingOptions.insuranceFeeAmountSellers can offer buyer-paid shipping insurance only when they ship to AU, FR, or IT. This value indicates the cost the buyer must pay to purchase shipping insurance for the items being shipped.

Required if shippingOptions.insuranceOffered is set to true.

Occurrence: Conditional

shippingOptions.insuranceFee.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.insuranceFee.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.insuranceOfferedbooleanIf set to true, the seller offers buyer-paid shipping insurance. The optionType shows whether this is for either a domestic or international shipment.

Buyer-paid shipping insurance is currently supported in only Australia (AU), France (FR), and Italy (IT).

Occurrence: Conditional

shippingOptions.optionTypeShippingOptionTypeEnumUse this field to set the ShippingOption element to either DOMESTIC or INTERNATIONAL.

Required if the policy offers shipping options using a shippingOptions container.

Occurrence: Conditional

shippingOptions.packageHandlingCostAmountApplicable to only CALCULATED shipping, an amount a seller can add to cover packaging, handling, and insurance costs. This cost is an addition to the selected shipping service cost and is included in the sum of the final shipping service costs in the output. This field must specify a zero value if freeShipping is set to true.

If the seller offers domestic and international calculated shipping but sets this field for only domestic shipping, eBay also applies the cost to all international shipments. To specify a fee for only international shipments, set the a domestic packagingHandlingCost to 0.

Occurrence: Conditional

shippingOptions.packageHandlingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.packageHandlingCost.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.rateTableIdstringA unique eBay-assigned ID associated with a user-created shipping rate table. The locality of a shipping rate table can be either DOMESTIC or INTERNATIONAL and you must ensure the value specified in this field references a shipping rate table that matches the type specified in the shippingOptions.optionType field. If you mismatch the types, eBay responds with a 20403 error.

Call getRateTable to retrieve information (including rateTableId values) on the rate tables configured by a seller. For information on creating rate tables, see Using shipping rate tables.

Occurrence: Conditional

shippingOptions.shippingServicesarray of ShippingServiceContains a list of shipping services offered for either DOMESTIC or INTERNATIONAL shipments.

Sellers can specify up to four domestic shipping services and up to five international shipping services by using separate shippingService containers for each. Note that if the seller is opted in to the Global Shipping Program, they can specify only four other international shipping services, regardless of whether or not Global Shipping is offered as one of the services.

Required if the policy offers shipping options using a shippingOptions container.

Occurrence: Conditional

shippingOptions.shippingServices.additionalShippingCostAmountThe cost of shipping each additional item if the same buyer purchases a multiple quantity of the same line item. This field is applicable for policies that cover multiple-quantity, fixed-price listings and is not applicable for policies that apply to single-quantity listings.

Sellers can encourage buyers to purchase multiple items and by offering a shipping discount on added items. The value for this field should be lower than the value set for shippingCost and you can set this value to 0 to offer free shipping on added items. If this value is not set, it defaults to the value set for shippingCost.

Occurrence: Conditional

shippingOptions.shippingServices.additionalShippingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.shippingServices.additionalShippingCost.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.shippingServices.buyerResponsibleForPickupbooleanThis field is only applicable to vehicle categories on eBay Motors (US and Canada). If set to true, the buyer is responsible for picking up the vehicle. Otherwise, the seller should specify the vehicle pickup arrangements in the item description.

The seller cannot modify this flag if the vehicle has bids or if the listing ends within 12 hours.

Default: false

Occurrence: Conditional

shippingOptions.shippingServices.buyerResponsibleForShippingbooleanThis field is applicable for only items listed in vehicle categories on eBay Motors (US and Canada). If set to true, the buyer is responsible for the shipment of the vehicle. Otherwise, the seller should specify the vehicle shipping arrangements in the item description.

The seller cannot modify this flag if the vehicle has bids or if the listing ends within 12 hours.

Default: false

Occurrence: Conditional

shippingOptions.shippingServices.cashOnDeliveryFeeAmountThe value indicates the Cash on Delivery (COD) fee that the seller charges if the buyer uses the CASH_ON_DELIVERY payment method. This fee is added to the total cost of the item, and the total cost is due from the buyer upon the delivery of the item. This field is applicable only if the buyer-selected payment method is 'COD' and the selected shipping service option supports a Cash on Delivery option.

To see if a domestic shipping service supports the Cash on Delivery option, call GeteBayDetails with DetailName set to ShippingServiceDetails, then review the response to see if CODService is set to true for the targeted shipping service.

Occurrence: Conditional

shippingOptions.shippingServices.cashOnDeliveryFee.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.shippingServices.cashOnDeliveryFee.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.shippingServices.freeShippingbooleanIf set to true, the seller offers free shipping to the buyer. This field can only be included and set to 'true' for the first domestic shipping service option specified in the shippingServices container (it is ignored if set for subsequent shipping services). The first specified shipping service option has a sortOrder value of 1 or (if the sortOrderId field is not used) it is the shipping service option that's specified first in the shippingServices container.

Occurrence: Conditional

shippingOptions.shippingServices.shippingCarrierCodestringThe shipping carrier, such as 'USPS', 'FedEx', 'UPS', and so on.

Occurrence: Conditional

shippingOptions.shippingServices.shippingCostAmountFor FLAT_RATE shipping options, the amount specified in this field is the shipping cost for the selected shipping carrier and service. The amount supplied must exclude any additional shipping charges (such as the seller's handling charges or insurance).

This field is not applicable in CALCULATED shipping services (the cost for a calculated shipping service cannot be determined until the listing has ended and the buyer has specified a postal code).

This value is automatically set to '0.0' if freeShipping is set to true.

Required if the shipping option uses a FLAT_RATE cost type and freeShipping is false.

Occurrence: Conditional

shippingOptions.shippingServices.shippingCost.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.shippingServices.shippingCost.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shippingOptions.shippingServices.shippingServiceCodestringThe shipping service that the shipping carrier uses to ship an item. For example, an overnight, two-day delivery, or other type of service. For details on configuring shipping services, see Setting the shipping carrier and shipping service values.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocationsRegionSetThis object contains the regionIncluded and regionExcluded fields, which define the geographical regions that a seller does and does not cover by the associated shipping policy.

shipToLocations appears at both the top-level of the fulfillment policy as well as here, within the shippingOptions.shippingServices container. Within individual shippingServices containers, use the regionIncluded container to specify the list of regions to where a seller ships using that particular shipping service (you can use different shipping services to cover different regions).

Note that you do not populate the regionExcluded field at this level. Instead, excluded shipping regions using the top-level shipToLocations container to define the regions to where a seller does not ship with this fulfillment policy.

Every eBay marketplace supports its own set of regions that you can use in the regionIncluded field. To determine the valid 'Ship-To' values for a marketplace, call GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings that you use in the regionIncluded.regionName field.

When returned at this level, this container lists only the regionIncluded areas defined for the associated shippingService container.

For more details, see The shipToLocations container.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocations.regionExcludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller does not ship. Populate regionExcluded in only the top-level shipToLocations container (do not populate this field within the shippingOptions container).

Normally a seller ships to as many areas as possible using both DOMESTIC and INTERNATIONAL shipping options and they don't have a need to exclude any regions from their ship-to locations. With this, there's no reason to set regionExclude fields. However, it makes sense to set the regionExcluded field when a seller wants to exclude a small area that's located within a larger area they service. For example, suppose a seller indicates they ship 'Worldwide', but for some reason must exclude a specific country, or world region, from the larger world area they ship to.

To retrieve the regions you can specify in the associated regionName field, call GeteBayDetails with DetailName set to ExcludeShippingLocationDetails, then review the Location fields in the response for the strings that you can specify regionExcluded.regionName.

Note that if a buyer's primary ship-to location is a region that a seller has excluded in their fulfillment policy (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on an item that uses that fulfillment policy.

For details on setting this field, see Excluding specific regions from included shipping areas.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocations.regionExcluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocations.regionExcluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocations.regionIncludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller ships.

Important: Populate this field only when the parent shipToLocations object is located within a shippingOptions container (that is, the parent shipTolocations object must not be the one at the top-level of the policy). Also, this field needs to be populated only when the associated shippingOptions container has optionType set to INTERNATIONAL.

Withing an international shipping option, set this value to Worldwide to indicate the seller ships to all world regions. If needed, use the regionExcluded field to exclude any regions in the world to where the seller does not ship.

Each eBay marketplace supports its own set of allowable shipping locations. Obtain the valid 'Ship-To Locations' for a marketplace by calling GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings that you can specify in the regionIncluded.regionName field.

For DOMESTIC shipping options, eBay automatically uses the seller's listing country as the default regionIncluded country. For details on setting this field, see How to set up worldwide shipping.

This field is always returned in the shipping policy response.

Required if optionType set to INTERNATIONAL.

Occurrence: Always

shippingOptions.shippingServices.shipToLocations.regionIncluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Conditional

shippingOptions.shippingServices.shipToLocations.regionIncluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Conditional

shippingOptions.shippingServices.sortOrderintegerThis integer value controls the order that this shipping service option appears in the View Item and Checkout pages, as related to the other specified shipping service options.

Sellers can specify up to four domestic shipping services (in four separate shippingService containers), so valid values are 1, 2, 3, and 4. A shipping service option with a sortOrder value of '1' appears at the top of View Item and Checkout pages. Conversely, a shipping service option with a sortOrder value of '4' appears at the bottom of the list.

Sellers can specify up to five international shipping services (in five separate shippingService containers, so valid values for international shipping services are 1, 2, 3, 4, and 5. Similarly to domestic shipping service options, the sortOrder value of a international shipping service option controls the placement of that shipping service option in the View Item and Checkout pages. Set up different domestic and international services by configuring two shippingOptions containers, where you set shippingOptions.optionType to either DOMESTIC or INTERNATIONAL to indicate the area supported by the listed shipping services.

If the sortOrder field is not supplied, the order of domestic and international shipping service options is determined by the order in which they are listed in the API call.

Min: 1. Max: 4 (for domestic shipping service) or 5 (for international shipping service).

Occurrence: Conditional

shippingOptions.shippingServices.surchargeAmountA fee that can be charged to US buyers when they have an item shipped via UPS or FedEx to Alaska, Hawaii or Puerto Rico.

Use this element only if the shipping option specifies a flat-rate service and the policy targets the MOTORS_VEHICLES category type in the US marketplace.

If some line items in an order have a surcharge, the surcharge amount is added only for those line items. This value is returned only when set. Note that you cannot add a surcharge to items shipped via the Global Shipping Program.

Occurrence: Conditional

shippingOptions.shippingServices.surcharge.currencyCurrencyCodeEnumThe base currency applied to the value field to establish a monetary amount.

The currency is represented as a 3-letter ISO4217 currency code. For example, the code for the Canadian Dollar is CAD.

Default: The currency of the authenticated user's country.

Occurrence: Conditional

shippingOptions.shippingServices.surcharge.valuestringThe monetary amount in the specified currency.

Required in the amount container.

Occurrence: Conditional

shipToLocationsRegionSetThis object contains the regionIncluded and regionExcluded fields, which defines the areas where the seller does and doesn't ship to with this fulfillment policy.

shipToLocations appears at both the top-level of the fulfillment policy as well as within the individual shippingOptions.shippingService containers. Here at the top level, this field returns the list of regionExclude areas that have been defined at this level, plus a complete list of regionIncluded fields that have been defined in all the policy's shippingOptions.shippingServices.shipToLocations containers.

For details on configuring this field, see The shipToLocations container.

Occurrence: Always

shipToLocations.regionExcludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller does not ship. Populate regionExcluded in only the top-level shipToLocations container (do not populate this field within the shippingOptions container).

Normally a seller ships to as many areas as possible using both DOMESTIC and INTERNATIONAL shipping options and they don't have a need to exclude any regions from their ship-to locations. With this, there's no reason to set regionExclude fields. However, it makes sense to set the regionExcluded field when a seller wants to exclude a small area that's located within a larger area they service. For example, suppose a seller indicates they ship 'Worldwide', but for some reason must exclude a specific country, or world region, from the larger world area they ship to.

To retrieve the regions you can specify in the associated regionName field, call GeteBayDetails with DetailName set to ExcludeShippingLocationDetails, then review the Location fields in the response for the strings that you can specify regionExcluded.regionName.

Note that if a buyer's primary ship-to location is a region that a seller has excluded in their fulfillment policy (or if the buyer does not have a primary ship-to location), they will receive an error message if they attempt to buy or place a bid on an item that uses that fulfillment policy.

For details on setting this field, see Excluding specific regions from included shipping areas.

Occurrence: Conditional

shipToLocations.regionExcluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Conditional

shipToLocations.regionExcluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Conditional

shipToLocations.regionIncludedarray of RegionA list of one or more regionsName fields that specify the areas to where a seller ships.

Important: Populate this field only when the parent shipToLocations object is located within a shippingOptions container (that is, the parent shipTolocations object must not be the one at the top-level of the policy). Also, this field needs to be populated only when the associated shippingOptions container has optionType set to INTERNATIONAL.

Withing an international shipping option, set this value to Worldwide to indicate the seller ships to all world regions. If needed, use the regionExcluded field to exclude any regions in the world to where the seller does not ship.

Each eBay marketplace supports its own set of allowable shipping locations. Obtain the valid 'Ship-To Locations' for a marketplace by calling GeteBayDetails with DetailName set to ShippingLocationDetails, then review the ShippingLocation fields in the response for the strings that you can specify in the regionIncluded.regionName field.

For DOMESTIC shipping options, eBay automatically uses the seller's listing country as the default regionIncluded country. For details on setting this field, see How to set up worldwide shipping.

This field is always returned in the shipping policy response.

Required if optionType set to INTERNATIONAL.

Occurrence: Always

shipToLocations.regionIncluded.regionNamestringA string that indicates the name of a region, as defined by eBay. A "region" can be either a 'world region' (e.g., the "Middle East" or "Southeast Asia") or a country, as represented with a two-letter country code. Use GeteBayDetails to get the values accepted by this field.

The values that you're allowed to use for a specific regionName field depend on the context in which you are setting the value. For details on how to set the values for this field, see The shipToLocations container.

Occurrence: Conditional

shipToLocations.regionIncluded.regionTypeRegionTypeEnumReserved for future use.

Occurrence: Conditional

warningsarray of ErrorDetailV3A list of warnings that were generated during the processing of the request. This field normally returns empty, which indicates the request did not generate any warnings.

Occurrence: Always

warnings.categorystringThe category type for this error or warning. It is a string that can have one of three values:
  • Application: Indicates an exception or error occurred in the application code or at runtime. Examples include catching an exception in a service's business logic, system failures, or request errors from a dependency.
  • Business: Used when your service or a dependent service refused to continue processing on the resource because of a business rule violation such as "Seller does not ship item to Antarctica" or "Buyer ineligible to purchase an alcoholic item". Business errors are not syntactical input errors.
  • Request: Used when there is anything wrong with the request, such as authentication, syntactical errors, rate limiting or missing headers, bad HTTP header values, and so on.

Occurrence: Conditional

warnings.domainstringName of the domain ,or primary system, of the service or application where the error occurred.

Occurrence: Conditional

warnings.errorIdintegerA positive integer that uniquely identifies the specific error condition that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

warnings.inputRefIdsarray of stringIdentifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.

Occurrence: Conditional

warnings.longMessagestringA more detailed explanation of the error than given in the message error field.

Occurrence: Conditional

warnings.messagestringInformation on how to correct the problem, in the end user's terms and language where applicable. Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale.

Occurrence: Conditional

warnings.outputRefIdsarray of stringIdentifies specific response elements associated with the error, if any. Path format is the same as inputRefId.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3This optional list of name/value pairs that contain context-specific ErrorParameter objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.

Occurrence: Conditional

warnings.parameters.namestringName of the parameter that caused the error.

Occurrence: Conditional

warnings.parameters.valuestringThe value of the parameter that caused the error.

Occurrence: Conditional

warnings.subdomainstringIf present, indicates the subsystem in which the error occurred.

Occurrence: Conditional

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

StatusMeaning
201Created
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
20400API_ACCOUNTREQUESTInvalid request. {additionalInfo}
20401API_ACCOUNTREQUESTMissing field {fieldName}. {additionalInfo}
20402API_ACCOUNTREQUESTInvalid input. {additionalInfo}
20403API_ACCOUNTREQUESTInvalid {fieldName}. {additionalInfo}
20500API_ACCOUNTAPPLICATIONSystem error.
20501API_ACCOUNTAPPLICATIONService unavailable. Please try again in next 24 hours.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: A fulfillment policy with free domestic shipping

Sellers can create one or more fulfillment policies where each fulfillment policy is specific to a marketplace and categoryType.name. You can set categoryType.name to one either ALL_EXCLUDING_MOTORS_VEHICLES or MOTORS_VEHICLES.

You can create multiple policies for each marketplace and categoryType.name combination, with each having a different set of shipping options. You can then select the fulfillment policy that is appropriate for each item in your inventory.

Input

The following fulfillment policy provides all the required fields and sets up a streamlined "free shipping" policy for domestic-only shipments. The policy uses a flat-rate service that is supplied by the United States Post Office. For more details on this example, see How to set up seller-pays free shipping.
POST
https://api.sandbox.ebay.com/sell/account/v1/fulfillment_policy

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and an ID for the created resource in the fulfillmentPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.

Sample 2: A fulfillment policy for Worldwide shipping

This sample creates a basic fulfillment policy that includes both DOMESTIC and INTERNATIONAL (Worldwide) shipping options.

Input

This sample sets up a fulfillment policy that requires the buyer to pay for the shipping. The buyer pays a flat rate for domestic orders and calculated shipping for international orders (the cost of the international shipping can be determined at checkout when the buyer indicates the destination to where the order is to be shipped). For more details on this example, see How to set up worldwide shipping.
POST
https://api.sandbox.ebay.com/sell/account/v1/fulfillment_policy

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and an ID for the created resource in the fulfillmentPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.

Sample 3: A detailed fulfillment policy

This sample creates a fulfillment policy that includes both DOMESTIC and INTERNATIONAL shipping options, but it excludes certain regions to where the seller does not ship.

Input

This sample sets up free shipping for domestic orders and calculated shipping for international orders. The input shows how to set up multiple shipping services where each provides service to a different region. The example also shows how to exclude specific regions for the areas that would otherwise be included by a configured shipping service. It also sets up an "additional cost" amount, which is the price the seller pays for adding additional items to the order. For more details on this example, see How to exclude specific regions from included shipping areas.
POST
https://api.sandbox.ebay.com/sell/account/v1/fulfillment_policy

Output

If the call is successful, eBay returns an HTTP status code of 201 Created and an ID for the created resource in the fulfillmentPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.