Each policy targets a marketplaceId and
categoryTypes.name combination and you can create multiple policies for each combination. 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)
URI parameters
HTTP request headers
OAuth scope
This request requires an access token created with the authorization code grant flow, using one scope from the following list:
https://api.ebay.com/oauth/api_scope/sell.account
See OAuth access tokens for more information.
| Input container/field | Type | Description |
|---|---|---|
| categoryTypes | array of CategoryType | For return policies, this field can be set to only ALL_EXCLUDING_MOTORS_VEHICLES (returns on motor vehicles are not processed through eBay flows.) Default: ALL_EXCLUDING_MOTORS_VEHICLES (for return policies only) Occurrence: Optional |
| categoryTypes.default | boolean | Sellers 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.name | CategoryTypeEnum | The 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 |
| description | string | An optional seller-defined description of the return policy for internal use (this value is not displayed to end users). Max length: 250 Occurrence: Optional |
| extendedHolidayReturnsOffered | boolean | Important! This field has been deprecated as of version 1.2.0, released on May 31, 2018. Any value supplied in this field is ignored, it is neither read nor returned. If set to IMPORTANT: Extended Holiday Returns is a seasonally available feature that is offered on some eBay marketplaces. To see if the feature is enabled in any given year, check the Returns on eBay page before the holiday season begins. If the feature is not enabled for the season, this field is ignored. The extended holiday returns period is defined by three dates:
The above dates may vary by a few days each year. Sellers are notified of the current dates on their eBay marketplace before the holiday period starts. Sellers can specify Extended Holiday Returns (as well as their regular non-holiday returns period) for chosen listings at any time during the year. The Extended Holiday Returns offer is not visible in listings until the start date of current year's holiday returns period, at which point it overrides the non-holiday returns policy. Buyers can see the Extended Holiday Returns offer in listings displayed through the purchase cutoff date and are able to return those purchases until the end date of the period. After the purchase cutoff date, the Extended Holiday Returns offer automatically disappears from the listings and the seller's non-holiday returns period reappears. Purchases made from that point on are subject to the non-holiday returns period, while purchases made before the cutoff date still have until the end of the period to return under the program. If the value of holidayReturns is Occurrence: Optional |
| internationalOverride | InternationalReturnOverrideType | This container, if populated, specifies the seller's policies for international returns (items that require postage via an international shipping service). Buy default, the policies for international returns are inherited from the domestic return policy. This container allows the seller to customize the return policy for international returns. Occurrence: Optional |
| internationalOverride.returnMethod | ReturnMethodEnum | Valid in the US marketplace only, this optional field indicates additional services (other than money-back) that sellers can offer buyers for remorse returns. As of version 1.2.0, the only accepted value for this field is REPLACEMENT. This field is valid in only the US marketplace, any supplied value is ignored in other marketplaces. Occurrence: Optional |
| internationalOverride.returnPeriod | TimeDuration | Required if the internationalOverride.returnsAccepted field is set to true. Specifies the amount of time the buyer has to return an item. The return period begins when the item is marked "delivered" at the buyer's specified ship-to location. You must set the value to one that's accepted by the marketplace and category where the item is listed. Most categories support 30-day and 60-day return periods. For a definitive list of category return periods, call GeteBayDetails in the Trading API with DetailName set to ReturnPolicyDetails. In the response review the ReturnPolicyDetails.ReturnsWithin field to see the values supported in the different marketplace categories. Note: In version 1.2.0, the options for this field were reduced. See the Release Notes for details. Set this field using the TimeDuration complex type, where you set unit toDAY and value to either 30 or 60 (or other value, as appropriate). Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours. Occurrence: Conditional |
| internationalOverride.returnPeriod.unit | TimeDurationUnitEnum | Required in the TimeDuration container. A time-measurement unit used to specify a period of time. Time-measurement units can be years, months, days, hours, minutes, and other time units (see TimeDurationUnitEnum for a complete list of possible units). The unit is applied to the number in the value field to define a span of time. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| internationalOverride.returnPeriod.value | integer | Required in the TimeDuration container. An amount of time, as measured by the time-measurement units specified in the unit field. Supported values for this field vary according to the object using the time duration. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| internationalOverride.returnsAccepted | boolean | Required if the seller wants to set an international return policy that differs from their domestic return policy. If set to true, the seller allows international returns. If set to false, the seller does not accept international returns. Occurrence: Conditional |
| internationalOverride.returnShippingCostPayer | ReturnShippingCostPayerEnum | Required if the internationalOverride.returnsAccepted field is set to true. This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either BUYER or SELLER. Depending on the return policy and specifics of the return, either the buyer or the seller can be responsible for the return shipping costs. Note that the seller is always responsible for return shipping costs for SNAD-related issues. Occurrence: Conditional |
| marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace to which this return policy applies. If this value is not specified, value defaults to the seller's eBay registration site. Occurrence: Required |
| name | string | A user-defined name for this return policy. Names must be unique for policies assigned to the same marketplace. Max length: 64 Occurrence: Required |
| refundMethod | RefundMethodEnum | Important! this field has been deprecated as of version 1.2.0, released on May 31, 2018. Any value other than Note that each eBay marketplace can support different sets of refund methods. Also, each eBay marketplace has a default setting for this value and if you do not specifically set this value, sellers are obligated to honor the setting that displays in their listings. Call GeteBayDetails in the Trading API to see what refund methods the marketplaces you sell into support. We recommend you set this field to the value of your preferred refund method and that you use the description field to detail the seller's return policy (such as indicating how quickly the seller will process a refund, whether the seller must receive the item before processing a refund, and other similar useful details). You cannot modify this value in a Revise item call if (1) the listing has bids or (2) the listing ends within 12 hours. Occurrence: Optional |
| restockingFeePercentage | string | Important! This field has been deprecated as of version 1.2.0, released on May 31, 2018. Any value supplied in this field is ignored, it is neither read nor returned. Sellers who accept returns should include this field if they charge buyers a restocking fee when items are returned. A restocking fee comes into play only when an item is returned due to buyer remorse and/or a purchasing mistake, but sellers cannot charge a restocking fee for SNAD-related returns. The total amount returned to the buyer is reduced by the cost of the item multiplied by the percentage indicated by this field. Allowable restocking fee values are:
Occurrence: Optional |
| returnInstructions | string | Important! This field is being deprecated on many marketplaces. Once deprecated, this field will be ignored on marketplaces where it is not supported and it will neither be read nor returned. This optional field contains the seller's detailed explanation for their return policy and is displayed in the Return Policy section of the View Item page. This field is valid in only the following marketplaces (the field is otherwise ignored):
Max length: 5000 (8000 for DE) Occurrence: Optional |
| returnMethod | ReturnMethodEnum | Valid in the US marketplace only, this optional field indicates additional services (other than money-back) that sellers can offer buyers for remorse returns. As of version 1.2.0, the only accepted value for this field is REPLACEMENT. This field is valid in only the US marketplace, any supplied value is ignored in other marketplaces. Occurrence: Optional |
| returnPeriod | TimeDuration | Required if returnsAccepted is set to true. Specifies the amount of time the buyer has to return an item. The return period begins when the item is marked "delivered" at the buyer's specified ship-to location. You must set the value to one that's accepted by the marketplace and category where the item is listed. Most categories support 30-day and 60-day return periods. For a definitive list of category return periods, call GeteBayDetails in the Trading API with DetailName set to ReturnPolicyDetails. In the response review the ReturnPolicyDetails.ReturnsWithin field to see the values supported in the different marketplace categories. Note: In version 1.2.0, the options for this field were reduced. See the Release Notes for details. Set this field using the TimeDuration complex type, where you set unit toDAY and value to either 30 or 60 (or other value, as appropriate). Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours. Occurrence: Conditional |
| returnPeriod.unit | TimeDurationUnitEnum | Required in the TimeDuration container. A time-measurement unit used to specify a period of time. Time-measurement units can be years, months, days, hours, minutes, and other time units (see TimeDurationUnitEnum for a complete list of possible units). The unit is applied to the number in the value field to define a span of time. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| returnPeriod.value | integer | Required in the TimeDuration container. An amount of time, as measured by the time-measurement units specified in the unit field. Supported values for this field vary according to the object using the time duration. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| returnsAccepted | boolean | If set to true, the seller accepts returns. Call the getReturnPolicies in the Metadata API to see what categories require returns to be offered for listings in each category. Also, note that some European marketplaces (for example, UK, IE, and DE) require sellers to accept returns for fixed-price items and auctions listed with Buy It Now. For details, see Returns and the Law (UK). Note:Top-Rated sellers must accept item returns and the handlingTime should be set to zero days or one day for a listing to receive a Top-Rated Plus badge on the View Item or search result pages. For more information on eBay's Top-Rated seller program, see Becoming a Top Rated Seller and qualifying for Top Rated Plus benefits. Occurrence: Required |
| returnShippingCostPayer | ReturnShippingCostPayerEnum | Required if returnsAccepted is set to true. This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either BUYER or SELLER. Depending on the return policy and specifics of the return, either the buyer or the seller can be responsible for the return shipping costs. Note that the seller is always responsible for return shipping costs for SNAD-related issues. Occurrence: Conditional |
Output
HTTP response headers
See HTTP response headers for details.
| Header | Meaning |
|---|---|
| Location | The location response header contains the URL to the newly created return policy. The URL includes the eBay-assigned returnPolicyId, which you can use to reference the policy. |
| Output container/field | Type | Description |
|---|---|---|
| categoryTypes | array of CategoryType | For return policies, this field always returns ALL_EXCLUDING_MOTORS_VEHICLES (returns on motor vehicles are not processed through eBay flows.) Default: ALL_EXCLUDING_MOTORS_VEHICLES (for return policies only) Occurrence: Always |
| categoryTypes.default | boolean | Sellers 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.name | CategoryTypeEnum | The 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 |
| description | string | An optional seller-defined description of the return policy for internal use (this value is not displayed to end users). Occurrence: Conditional |
| extendedHolidayReturnsOffered | boolean | Important! This field has been deprecated as of version 1.2.0, released on May 31, 2018. Any value supplied in this field is ignored, it is neither read nor returned. If set to IMPORTANT: Extended Holiday Returns is a seasonally available feature that is offered on some eBay marketplaces. To see if the feature is enabled in any given year, check the eBay Seller Center Returns on eBay page of before the holiday season begins. Occurrence: Always |
| internationalOverride | InternationalReturnOverrideType | This container, if populated, specifies the seller's policies for international returns (items that require postage via an international shipping service). Buy default, the policies for international returns are inherited from the domestic return policy. This container allows the seller to customize the return policy for international returns. Occurrence: Conditional |
| internationalOverride.returnMethod | ReturnMethodEnum | Valid in the US marketplace only, this optional field indicates additional services (other than money-back) that sellers can offer buyers for remorse returns. As of version 1.2.0, the only accepted value for this field is REPLACEMENT. This field is valid in only the US marketplace, any supplied value is ignored in other marketplaces. Occurrence: Conditional |
| internationalOverride.returnPeriod | TimeDuration | Required if the internationalOverride.returnsAccepted field is set to true. Specifies the amount of time the buyer has to return an item. The return period begins when the item is marked "delivered" at the buyer's specified ship-to location. You must set the value to one that's accepted by the marketplace and category where the item is listed. Most categories support 30-day and 60-day return periods. For a definitive list of category return periods, call GeteBayDetails in the Trading API with DetailName set to ReturnPolicyDetails. In the response review the ReturnPolicyDetails.ReturnsWithin field to see the values supported in the different marketplace categories. Note: In version 1.2.0, the options for this field were reduced. See the Release Notes for details. Set this field using the TimeDuration complex type, where you set unit toDAY and value to either 30 or 60 (or other value, as appropriate). Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours. Occurrence: Conditional |
| internationalOverride.returnPeriod.unit | TimeDurationUnitEnum | Required in the TimeDuration container. A time-measurement unit used to specify a period of time. Time-measurement units can be years, months, days, hours, minutes, and other time units (see TimeDurationUnitEnum for a complete list of possible units). The unit is applied to the number in the value field to define a span of time. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| internationalOverride.returnPeriod.value | integer | Required in the TimeDuration container. An amount of time, as measured by the time-measurement units specified in the unit field. Supported values for this field vary according to the object using the time duration. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| internationalOverride.returnsAccepted | boolean | Required if the seller wants to set an international return policy that differs from their domestic return policy. If set to true, the seller allows international returns. If set to false, the seller does not accept international returns. Occurrence: Conditional |
| internationalOverride.returnShippingCostPayer | ReturnShippingCostPayerEnum | Required if the internationalOverride.returnsAccepted field is set to true. This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either BUYER or SELLER. Depending on the return policy and specifics of the return, either the buyer or the seller can be responsible for the return shipping costs. Note that the seller is always responsible for return shipping costs for SNAD-related issues. Occurrence: Conditional |
| marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace to which this return policy applies. If this value is not specified, value defaults to the seller's eBay registration site. Occurrence: Required |
| name | string | A user-defined name for this return policy. Names must be unique for policies assigned to the same marketplace. Max length: 64 Occurrence: Required |
| refundMethod | RefundMethodEnum | Important! This field has been deprecated as of version 1.2.0, released on May 31, 2018. Any value other than Occurrence: Always |
| restockingFeePercentage | string | Important! This field has been deprecated as of version 1.2.0, released on May 31, 2018. Any value supplied in this field is ignored, it is neither read nor returned. Optionally set by the seller, the percentage charged if the seller charges buyers a a restocking fee when items are returned due to buyer remorse and/or a purchasing mistake. The total amount charged to the buyer is the cost of the item multiplied by the percentage indicated in this field. Occurrence: Conditional |
| returnInstructions | string | This field contains the seller's detailed explanation for their return policy and is displayed in the Return Policy section of the View Item page. This field is valid in only the following marketplaces (the field is otherwise ignored):
Occurrence: Conditional |
| returnMethod | ReturnMethodEnum | This field indicates the method in which the seller handles non-money back return requests for remorse returns. This field is valid in only the US marketplace and the only valid value is REPLACEMENT. Occurrence: Always |
| returnPeriod | TimeDuration | Specifies the amount of time the buyer has to return an item. The return period begins when the item is marked "delivered" at the buyer's specified ship-to location. Occurrence: Always |
| returnPeriod.unit | TimeDurationUnitEnum | Required in the TimeDuration container. A time-measurement unit used to specify a period of time. Time-measurement units can be years, months, days, hours, minutes, and other time units (see TimeDurationUnitEnum for a complete list of possible units). The unit is applied to the number in the value field to define a span of time. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| returnPeriod.value | integer | Required in the TimeDuration container. An amount of time, as measured by the time-measurement units specified in the unit field. Supported values for this field vary according to the object using the time duration. See the containing object for details and call GeteBayDetails in the Trading API to get the allowable values for the specific object you're configuring. Occurrence: Conditional |
| returnPolicyId | string | A unique eBay-assigned ID for a return policy. This ID is generated when the policy is created. Occurrence: Required |
| returnsAccepted | boolean | If set to true, the seller accepts returns. If set to false, this field indicates that the seller does not accept returns. Occurrence: Always |
| returnShippingCostPayer | ReturnShippingCostPayerEnum | This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either BUYER or SELLER. Depending on the return policy and specifics of the return, either the buyer or the seller can be responsible for the return shipping costs. Note that the seller is always responsible for return shipping costs for SNAD-related issues. Occurrence: Always |
| warnings | array of ErrorDetailV3 | A list of warnings related to request. This field normally returns empty, which indicates the request did not generate any warnings. Occurrence: Always |
| warnings.category | string | The category type for this error or warning. It takes a string that can have one of three values:
Occurrence: Conditional |
| warnings.domain | string | Name of the domain containing the service or application. Occurrence: Conditional |
| warnings.errorId | integer | A 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.inputRefIds | array of string | Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation. Occurrence: Conditional |
| warnings.longMessage | string | An expanded version of message that should be around 100-200 characters long, but is not required to be such. Occurrence: Conditional |
| warnings.message | string | An end user and app developer friendly device agnostic message. It explains what the error or warning is, and how to fix it (in a general sense). Its value is at most 50 characters long. If applicable, the value is localized in the end user's requested locale. Occurrence: Conditional |
| warnings.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId. Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | This optional complex field type contains a list of one or more context-specific ErrorParameter objects, with each item in the list entry 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.name | string | Name of the entity that threw the error. Occurrence: Conditional |
| warnings.parameters.value | string | A description of the error. Occurrence: Conditional |
| warnings.subdomain | string | Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain. 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.
| Status | Meaning |
|---|---|
| 201 | Created |
| 400 | Bad Request |
| 500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 20400 | API_ACCOUNT | REQUEST | Invalid request. {additionalInfo} |
| 20401 | API_ACCOUNT | REQUEST | Missing field . |
| 20406 | API_ACCOUNT | REQUEST | Invalid return option |
| 20500 | API_ACCOUNT | APPLICATION | System error. |
| 20501 | API_ACCOUNT | APPLICATION | Service 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 domestic return policy
Note that while each return policy is set to a specific marketplace, the return policy schema does not provide for a categorytypes field, as do the other eBay business policies. With return policies, categorytypes is hard-set to
ALL_EXCEPT_MOTORS_VEHICLES because eBay does not provide return services for motor vehicle sales. eBay sets the first policy created for each marketplace to the default for that marketplace and this status is used when you set item policies via the eBay web flow. If needed, modify the default setting for a policy by calling updateReturnPolicy.
Input
Output
201 Created and a return policy object with an ID for the newly created resource in the returnPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.
Sample 2: A skeletal No Returns return policy
Input
Output
201 Created and a return policy object with an ID for the newly created resource in the returnPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.
Sample 3: A domestic and international return policy
Input
Output
201 Created and a return policy object with an ID for the newly created resource in the returnPolicyId field. In addition, the full URL to the newly created resource is returned in the Location HTTP response header.