openapi: 3.0.0
info:
title: eBay Account Advertising_eligibility Fulfillment_policy API
description: The <b>Account API</b> gives sellers the ability to configure their eBay seller accounts, including the seller's policies (eBay business policies and seller-defined custom policies), opt in and out of eBay seller programs, configure sales tax tables, and get account information. <br><br>For details on the availability of the methods in this API, see <a href="/api-docs/sell/account/overview.html#requirements">Account API requirements and restrictions</a>.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: v1.9.2
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/account/v1
tags:
- name: Fulfillment_policy
paths:
/fulfillment_policy/:
post:
tags:
- Fulfillment_policy
description: '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. <br><br>Each policy targets a specific eBay marketplace and a category group type, and you can create multiple policies for each combination. <br><br>A successful request returns the <b>getFulfillmentPolicy</b> URI to the new policy in the <b>Location</b> response header and the ID for the new policy is returned in the response payload. <p class="tablenote"><b>Tip:</b> For details on creating and using the business policies supported by the Account API, see <a href="/api-docs/sell/static/seller-accounts/business-policies.html">eBay business policies</a>.</p> <p><b>Using the eBay standard envelope service (eSE)</b></p><p>The eBay standard envelope service (eSE) is a domestic envelope service with tracking through eBay. This service applies to specific sub-categories of <b>Trading Cards</b>, and to coins & paper money, postcards, stamps, patches, and similar <a href="https://www.ebay.com/sellercenter/shipping/choosing-a-carrier-and-service/ebay-standard-envelope#eligible-categories" target="_blank ">eligible categories</a>, and is only available on the US marketplace. To use this service, send envelopes using the USPS mail and set the <b>shippingServiceCode</b> field to <code>US_eBayStandardEnvelope</code>. See <a href="/api-docs/sell/static/seller-accounts/using-the-ebay-standard-envelope-service.html" target="_blank">Using eBay standard envelope (eSE) service</a> for details. See <a href="https://pages.ebay.com/seller-center/shipping/ebay-standard-envelope.html#lower-cost-way" target="_blank ">eBay standard envelope</a> for additional details, restrictions, and an <a href="https://ir.ebaystatic.com/pictures/sc/Shipping/ebay_standard_envelope_template.pdf" target="_blank ">envelope size template</a>. '
operationId: createFulfillmentPolicy
parameters:
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: Request to create a seller account fulfillment policy.
content:
application/json:
schema:
description: Request to create a seller account fulfillment policy.
$ref: '#/components/schemas/FulfillmentPolicyRequest'
required: true
responses:
'201':
description: Created
headers:
Location:
schema:
type: string
description: The <b>location</b> response header contains the URL to the newly created fulfillment policy. The URL includes the eBay-assigned <code>fulfillmentPolicyId</code>, which you can use to reference the policy.
content:
application/json:
schema:
$ref: '#/components/schemas/SetFulfillmentPolicyResponse'
x-response-codes:
errors:
'20200':
domain: API_ACCOUNT
category: BUSINESS
description: Warning. {additionalInfo}
'20201':
domain: API_ACCOUNT
category: BUSINESS
description: '{fieldName} (Click and Collect Program) can not be enabled for this seller or marketplace.'
'400':
description: Bad Request
x-response-codes:
errors:
'20400':
domain: API_ACCOUNT
category: REQUEST
description: Invalid request. {additionalInfo}
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20402':
domain: API_ACCOUNT
category: REQUEST
description: Invalid input. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
'20501':
domain: API_ACCOUNT
category: APPLICATION
description: Service unavailable. Please try again in next 24 hours.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
/fulfillment_policy/{fulfillmentPolicyId}:
get:
tags:
- Fulfillment_policy
description: This method retrieves the complete details of a fulfillment policy. Supply the ID of the policy you want to retrieve using the <b>fulfillmentPolicyId</b> path parameter.
operationId: getFulfillmentPolicy
parameters:
- name: fulfillmentPolicyId
in: path
description: This path parameter specifies the ID of the fulfillment policy you want to retrieve.<br><br> This ID can be retrieved for a fulfillment policy by using the <a href="/api-docs/sell/account/resources/fulfillment_policy/methods/getFulfillmentPolicies" target="_blank ">getFulfillmentPolicies</a> method.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillmentPolicy'
'400':
description: Bad Request
x-response-codes:
errors:
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20404':
domain: API_ACCOUNT
category: REQUEST
description: '{fieldName} not found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
'20501':
domain: API_ACCOUNT
category: APPLICATION
description: Service unavailable. Please try again in next 24 hours.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
- https://api.ebay.com/oauth/api_scope/sell.account.readonly
put:
tags:
- Fulfillment_policy
description: This method updates an existing fulfillment policy. Specify the policy you want to update using the <b>fulfillment_policy_id</b> path parameter. Supply a complete policy payload with the updates you want to make; this call overwrites the existing policy with the new details specified in the payload.
operationId: updateFulfillmentPolicy
parameters:
- name: fulfillmentPolicyId
in: path
description: This path parameter specifies the ID of the fulfillment policy you want to update.<br><br>This ID can be retrieved for a specific fulfillment policy by using the <a href="/api-docs/sell/account/resources/fulfillment_policy/methods/getFulfillmentPolicies" target="_blank ">getFulfillmentPolicies</a> method.
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: Fulfillment policy request
content:
application/json:
schema:
description: Fulfillment policy request
$ref: '#/components/schemas/FulfillmentPolicyRequest'
required: true
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/SetFulfillmentPolicyResponse'
x-response-codes:
errors:
'20200':
domain: API_ACCOUNT
category: BUSINESS
description: Warning. {additionalInfo}
'20201':
domain: API_ACCOUNT
category: BUSINESS
description: '{fieldName} (Click and Collect Program) can not be enabled for this seller or marketplace.'
'400':
description: Bad Request
x-response-codes:
errors:
'20400':
domain: API_ACCOUNT
category: REQUEST
description: Invalid request. {additionalInfo}
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20402':
domain: API_ACCOUNT
category: REQUEST
description: Invalid input. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20404':
domain: API_ACCOUNT
category: REQUEST
description: '{fieldName} not found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
'20501':
domain: API_ACCOUNT
category: APPLICATION
description: Service unavailable. Please try again in next 24 hours.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
delete:
tags:
- Fulfillment_policy
description: This method deletes a fulfillment policy. Supply the ID of the policy you want to delete in the <b>fulfillmentPolicyId</b> path parameter.
operationId: deleteFulfillmentPolicy
parameters:
- name: fulfillmentPolicyId
in: path
description: This path parameter specifies the ID of the fulfillment policy to delete.<br><br> This ID can be retrieved for a fulfillment policy by using the <a href="/api-docs/sell/account/resources/fulfillment_policy/methods/getFulfillmentPolicies" target="_blank ">getFulfillmentPolicies</a> method.
required: true
schema:
type: string
responses:
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20402':
domain: API_ACCOUNT
category: REQUEST
description: Invalid input. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20404':
domain: API_ACCOUNT
category: REQUEST
description: '{fieldName} not found.'
'404':
description: Not Found
'409':
description: Conflict
x-response-codes:
errors:
'20409':
domain: API_ACCOUNT
category: BUSINESS
description: Invalid default policy type. {additionalInfo}
'21409':
domain: API_ACCOUNT
category: BUSINESS
description: Invalid default for category type. {additionalInfo}
'22409':
domain: API_ACCOUNT
category: BUSINESS
description: Invalid target default policy. {additionalInfo}
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
'20501':
domain: API_ACCOUNT
category: APPLICATION
description: Service unavailable. Please try again in next 24 hours.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
/fulfillment_policy:
get:
tags:
- Fulfillment_policy
description: 'This method retrieves all the fulfillment policies configured for the marketplace you specify using the <code>marketplace_id</code> query parameter. <br><br><b>Marketplaces and locales</b> <br><br>Get the correct policies for a marketplace that supports multiple locales using the <code>Content-Language</code> request header. For example, get the policies for the French locale of the Canadian marketplace by specifying <code>fr-CA</code> for the <code>Content-Language</code> header. Likewise, target the Dutch locale of the Belgium marketplace by setting <code>Content-Language: nl-BE</code>. For details on header values, see <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank">HTTP request headers</a>.'
operationId: getFulfillmentPolicies
parameters:
- name: marketplace_id
in: query
description: This query parameter specifies the eBay marketplace of the policies you want to retrieve. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/account/types/ba:MarketplaceIdEnum
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillmentPolicyResponse'
'400':
description: Bad Request
x-response-codes:
errors:
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20404':
domain: API_ACCOUNT
category: REQUEST
description: '{fieldName} not found.'
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
'20501':
domain: API_ACCOUNT
category: APPLICATION
description: Service unavailable. Please try again in next 24 hours.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
- https://api.ebay.com/oauth/api_scope/sell.account.readonly
/fulfillment_policy/get_by_policy_name:
get:
tags:
- Fulfillment_policy
description: 'This method retrieves the details for a specific fulfillment policy. In the request, supply both the policy <code>name</code> and its associated <code>marketplace_id</code> as query parameters. <br><br><b>Marketplaces and locales</b> <br><br>Get the correct policy for a marketplace that supports multiple locales using the <code>Content-Language</code> request header. For example, get a policy for the French locale of the Canadian marketplace by specifying <code>fr-CA</code> for the <code>Content-Language</code> header. Likewise, target the Dutch locale of the Belgium marketplace by setting <code>Content-Language: nl-BE</code>. For details on header values, see <a href="/api-docs/static/rest-request-components.html#HTTP">HTTP request headers</a>.'
operationId: getFulfillmentPolicyByName
parameters:
- name: marketplace_id
in: query
description: This query parameter specifies the eBay marketplace of the policy you want to retrieve. For implementation help, refer to eBay API documentation at https://developer.ebay.com/api-docs/sell/account/types/ba:MarketplaceIdEnum
required: true
schema:
type: string
- name: name
in: query
description: This query parameter specifies the seller-defined name of the fulfillment policy you want to retrieve.<br><br>This value can be retrieved for a fulfillment policy by using the <a href="/api-docs/sell/account/resources/fulfillment_policy/methods/getFulfillmentPolicies" target="_blank ">getFulfillmentPolicies</a> method.
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/FulfillmentPolicy'
'400':
description: Bad Request
x-response-codes:
errors:
'20401':
domain: API_ACCOUNT
category: REQUEST
description: Missing field {fieldName}. {additionalInfo}
'20403':
domain: API_ACCOUNT
category: REQUEST
description: Invalid {fieldName}. {additionalInfo}
'20404':
domain: API_ACCOUNT
category: REQUEST
description: '{fieldName} not found.'
'500':
description: Internal Server Error
x-response-codes:
errors:
'20500':
domain: API_ACCOUNT
category: APPLICATION
description: System error.
'20501':
domain: API_ACCOUNT
category: APPLICATION
description: Service unavailable. Please try again in next 24 hours.
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.account
- https://api.ebay.com/oauth/api_scope/sell.account.readonly
components:
schemas:
ErrorParameter:
type: object
properties:
name:
type: string
description: Name of the parameter that caused the error.
value:
type: string
description: The value of the parameter that caused the error.
description: A complex type that indicates a parameter that caused an error and the value of the parameter which caused the error.
Region:
type: object
properties:
regionName:
type: string
description: A 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"), a country (represented with a two-letter country code), a state or province (represented with a two-letter code), or a special domestic region within a country. <br><br>The <a href="/devzone/xml/docs/reference/ebay/GeteBayDetails.html">GeteBayDetails</a> call in the Trading API can be used to retrieve the world regions and special domestic regions within a specific country. To get these enumeration values, call <b>GeteBayDetails</b> with the <b>DetailName</b> value set to <b>ExcludeShippingLocationDetails</b>.
regionType:
type: string
description: 'Reserved for future use. <!--The region''s type, which can be one of the following: ''COUNTRY'', ''COUNTRY_REGION'', ''STATE_OR_PROVINCE'', ''WORLD_REGION'', or ''WORLDWIDE''.--> For implementation help, refer to <a href=''https://developer.ebay.com/api-docs/sell/account/types/ba:RegionTypeEnum''>eBay API documentation</a>'
description: This type is used to define specific shipping regions. There are four 'levels' of shipping regions, including large geographical regions (like 'Asia', 'Europe', or 'Middle East'), individual countries, US states or Canadian provinces, and special locations/domestic regions within a country (like 'Alaska/Hawaii' or 'PO Box').
ShippingOption:
type: object
properties:
costType:
type: string
description: This field defines whether the shipping cost model is <code>FLAT_RATE</code> (the same rate for all buyers, or buyers within a region if shipping rate tables are used) or <code>CALCULATED</code> (the shipping rate varies by the ship-to location and size and weight of the package). <br><br>This field is conditionally required if any shipping service options are specified (domestic and/or international). For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ShippingCostTypeEnum'>eBay API documentation</a>
insuranceFee:
description: This field has been deprecated. <br><br>Shipping insurance is offered only via a shipping carrier's shipping services and is no longer available via eBay shipping policies.
$ref: '#/components/schemas/Amount'
insuranceOffered:
type: boolean
description: This field has been deprecated. <br><br>Shipping insurance is offered only via a shipping carrier's shipping services and is no longer available via eBay shipping policies.
optionType:
type: string
description: This field is used to indicate if the corresponding shipping service options (under <b>shippingServices</b> array) are domestic or international shipping service options. This field is conditionally required if any shipping service options are specified (domestic and/or international). For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ShippingOptionTypeEnum'>eBay API documentation</a>
packageHandlingCost:
description: This container is used if the seller adds handling charges to domestic and/or international shipments. <br><br>Sellers can not specify any domestic handling charges if they offered 'free shipping' in the policy.<br><br>This container will only be returned if set for the policy.
$ref: '#/components/schemas/Amount'
rateTableId:
type: string
description: This field is used if the seller wants to associate a domestic or international shipping rate table to the fulfillment business policy. The <a href="/api-docs/sell/account/resources/rate_table/methods/getRateTables">getRateTables</a> method can be used to retrieve shipping rate table IDs.<br><br>With domestic and international shipping rate tables, the seller can set different shipping costs based on shipping regions and shipping speed/level of service (one-day, expedited, standard, economy). There are also options to additional per-weight and handling charges.<br><br>Sellers need to be careful that shipping rate tables match the corresponding shipping service options. In other words, a domestic shipping rate table must not be specified in the same container where international shipping service options are being specified, and vice versa, and the shipping speed/level of service of the provided shipping service options should match the shipping speed/level of service options that are defined in the shipping rate tables. <br><br>For example, if the corresponding shipping rate table defines costs for one-day shipping services, there should be at least one one-day shipping service option specified under the <b>shippingServices</b> array.<br><br>This field is returned if set.
shippingDiscountProfileId:
type: string
description: 'This field is the unique identifier of a seller''s domestic or international shipping discount profile. If a buyer satisfies the requirements of the discount rule, this buyer will receive a shipping discount for the order. <br><br>The seller can create and manage shipping discount profiles using (Get/Set) <b>ShippingDiscountProfiles</b> calls in the <b>Trading API</b> or through the <b>Shipping Preferences</b> in <b>My eBay</b>. <br><br><span class="tablenote"><b>Note: </b>Initially, shipping discount profiles in the <b>Account API</b> will <i>not</i> be available to all sellers.</span>'
shippingPromotionOffered:
type: boolean
description: 'This boolean indicates whether or not the seller has set up a promotional shipping discount that will be available to buyers who satisfy the requirements of the shipping discount rule. <br><br>The seller can create and manage shipping promotional discounts using (Get/Set) <b>ShippingDiscountProfiles</b> calls in the <b>Trading API</b> or through the <b>Shipping Preferences</b> in <b>My eBay</b>. <br><br><span class="tablenote"><b>Note: </b>Initially, shipping discount profiles in the <b>Account API</b> will <i>not</i> be available to all sellers.</span>'
shippingServices:
type: array
description: This array consists of the domestic or international shipping services options that are defined for the policy. The shipping service options defined under this array should match what is set in the corresponding <b>shippingOptions.optionType</b> field (which controls whether domestic or international shipping service options are being defined). If a shipping rate table is being used, the specified shipping service options should also match the shipping rate table settings (domestic or international, shipping speed/level of service, etc.) <br><br>Sellers can specify up to four domestic shipping services and up to five international shipping service options by using separate <b>shippingService</b> containers for each. If the seller is using the Global Shipping Program as an international option, only a total of four international shipping service options (including GSP) can be offered. <br><br> See <a href="/api-docs/sell/static/seller-accounts/ht_shipping-setting-shipping-carrier-and-service-values.html" target="_blank">How to set up shipping carrier and shipping service values</a>. <br><br>To use the eBay standard envelope service (eSE), see <a href="/api-docs/sell/static/seller-accounts/using-the-ebay-standard-envelope-service.html" target="_blank">Using eBay standard envelope (eSE) service</a>.<br><br>This array is conditionally required if the seller is offering one or more domestic and/or international shipping service options.
items:
$ref: '#/components/schemas/ShippingService'
description: This type is used by the <b>shippingOptions</b> array, which is used to provide detailed information on the domestic and international shipping options available for the policy. A separate <b>ShippingOption</b> object covers domestic shipping service options and international shipping service options (if the seller ships to international locations).
Amount:
type: object
properties:
currency:
type: string
description: The base currency applied to the <b>value</b> field to establish a monetary amount. <br><br>The currency is represented as a 3-letter <a href="https://www.iso.org/iso-4217-currency-codes.html " title="https://www.iso.org " target="_blank">ISO 4217</a> currency code. For example, the code for the Canadian Dollar is <code>CAD</code>.<br><br><b>Default:</b> The default currency of the eBay marketplace that hosts the listing. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:CurrencyCodeEnum'>eBay API documentation</a>
value:
type: string
description: The monetary amount in the specified <b>currency</b>.
description: A complex type that describes the value of a monetary amount as represented by a global currency. When passing in an amount in a request payload, both <b>currency</b> and <b>value</b> fields are required, and both fields are also always returned for an amount in a response field.
FulfillmentPolicyRequest:
type: object
properties:
categoryTypes:
type: array
description: This container is used to specify whether the fulfillment business policy applies to motor vehicle listings, or if it applies to non-motor vehicle listings.
items:
$ref: '#/components/schemas/CategoryType'
description:
type: string
description: 'A seller-defined description of the fulfillment policy. This description is only for the seller''s use, and is not exposed on any eBay pages. <br><br><b>Max length</b>: 250'
freightShipping:
type: boolean
description: 'This field is included and set to <code>true</code> if freight shipping is available for the item. Freight shipping can be used for large items over 150 lbs.<br><br><b>Default</b>: false'
globalShipping:
type: boolean
description: 'This field is included and set to <code>true</code> if the seller wants to use the Global Shipping Program for international shipments. See the <a href="https://pages.ebay.com/help/sell/shipping-globally.html ">Global Shipping Program</a> help topic for more details and requirements on the Global Shipping Program.<br><br>It is possible for a seller to use a combination of the Global Shipping Program and other international shipping services. <br><br>If this value is set to <code>false</code> or if the field is omitted, the seller is responsible for manually specifying individual international shipping services (if the seller ships internationally)., as described in <a href="https://developer.ebay.com/api-docs/sell/static/seller-accounts/ht_shipping-worldwide.html ">Setting up worldwide shipping</a>. <br><br>Sellers can opt in or out of the Global Shipping Program through the Shipping preferences in My eBay.<br><br><span class="tablenote"><b>Note</b>: On the US marketplace, the <em><b>Global Shipping Program</b></em> is scheduled to be replaced by a new intermediated international shipping program called <em><b>eBay International Shipping</b></em>. US sellers who are opted in to the Global Shipping Program will be automatically opted in to eBay International Shipping when it becomes available to them. All US sellers will be migrated by March 31, 2023. <br><br>eBay International Shipping is an account level setting, and no field needs to be set in a Fulfillment business policy to enable it. As long as the US seller''s account is opted in to eBay International Shipping, this shipping option will be enabled automatically for all listings where international shipping is available. <br><br>A US seller who is opted in to eBay International Shipping can also specify individual international shipping service options for a Fulfillment business policy.</span><p><b>Default</b>: false</p>'
handlingTime:
description: 'This container is used to specify the maximum number of business days the seller commits to for preparing and shipping an order after receiving a cleared pay
# --- truncated at 32 KB (69 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-fulfillment-policy-api-openapi.yml