POST/return_policy
This method creates a new return policy where the policy encapsulates seller's terms for returning items.
Each policy targets a specific marketplace, and you can create multiple policies for each marketplace. Return policies are not applicable to motor-vehicle listings.
A successful request returns the getReturnPolicy 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.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com
URI parameters
This method has no URI parameters.
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
| Header | Type | Description |
|---|---|---|
| Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required |
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.
Request payload
Copy complete valid JSON to clipboardRequest fields
| Input container/field | Type | Description |
|---|---|---|
| categoryTypes | array of CategoryType | This container indicates which category group that the return policy applies to. Occurrence: Required |
| categoryTypes.default | boolean | Note: This field has been deprecated and is no longer used. Occurrence: Optional |
| categoryTypes.name | CategoryTypeEnum | The category type to which the policy applies (motor vehicles or non-motor vehicles). Occurrence: Required |
| description | string | A seller-defined description of the return business policy. This description is only for the seller's use, and is not exposed on any eBay pages. Occurrence: Optional |
| extendedHolidayReturnsOffered | boolean | Important! This field is deprecated, since eBay no longer supports extended holiday returns. Any value supplied in this field is neither read nor returned. Occurrence: Optional |
| internationalOverride | InternationalReturnOverrideType | This container is used by the seller to specify a separate international return policy. If a separate international return policy is not defined by a seller, all of the domestic return policy settings will also apply to international orders. Occurrence: Optional |
| internationalOverride.returnMethod | ReturnMethodEnum | This field sets/indicates if the seller offers replacement items to the buyer in the case of an international return. The buyer must be willing to accept a replacement item; otherwise, the seller will need to issue a refund for a return. Occurrence: Optional |
| internationalOverride.returnPeriod | TimeDuration | This container indicates the number of calendar days that 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: Conditional |
| internationalOverride.returnPeriod.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| internationalOverride.returnPeriod.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| internationalOverride.returnsAccepted | boolean | If set to Occurrence: Conditional |
| internationalOverride.returnShippingCostPayer | ReturnShippingCostPayerEnum | This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either Occurrence: Conditional |
| marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace to which this return business policy applies. Occurrence: Required |
| name | string | A seller-defined name for this return business policy. Names must be unique for policies assigned to the same marketplace. Occurrence: Required |
| refundMethod | RefundMethodEnum | This value indicates the refund method that will be used by the seller for buyer returns. Important! If this field is not included in a return business policy, it will default to MONEY_BACK. Occurrence: Optional |
| restockingFeePercentage | string | Important! This field is deprecated, since eBay no longer allows sellers to charge a restocking fee for buyer remorse returns. If this field is included, it is ignored. Occurrence: Optional |
| returnInstructions | string | This text-based field provides more details on seller-specified return instructions. Important! This field is no longer supported on many eBay marketplaces. To see if a marketplace and eBay category does support this field, call getReturnPolicies method of the Metadata API. Then you will look for the policyDescriptionEnabled field with a value of Max length: 5000 (8000 for DE) Occurrence: Optional |
| returnMethod | ReturnMethodEnum | This field can be used if the seller is willing and able to offer a replacement item as an alternative to 'Money Back'. Occurrence: Optional |
| returnPeriod | TimeDuration | This container is used to specify the number of days that 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: Conditional |
| returnPeriod.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| returnPeriod.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| returnsAccepted | boolean | If set to 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 | This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either 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. |
Response payload
Response fields
| Output container/field | Type | Description |
|---|---|---|
| categoryTypes | array of CategoryType | This field always returns Occurrence: Always |
| categoryTypes.default | boolean | Note: This field has been deprecated and is no longer used. Occurrence: Conditional |
| categoryTypes.name | CategoryTypeEnum | The category type to which the policy applies (motor vehicles or non-motor vehicles). Occurrence: Always |
| description | string | A seller-defined description of the return business policy. This description is only for the seller's use, and is not exposed on any eBay pages. This field is returned if set for the policy. Occurrence: Conditional |
| extendedHolidayReturnsOffered | boolean | Important! This field is deprecated, since eBay no longer supports extended holiday returns. This field should no longer be returned. Occurrence: Conditional |
| internationalOverride | InternationalReturnOverrideType | This container is used by the seller to specify a separate international return policy, and will only be returned if the seller has set a separate return policy for international orders. If a separate international return policy is not defined by a seller, all of the domestic return policy settings will also apply to international orders. Occurrence: Conditional |
| internationalOverride.returnMethod | ReturnMethodEnum | This field sets/indicates if the seller offers replacement items to the buyer in the case of an international return. The buyer must be willing to accept a replacement item; otherwise, the seller will need to issue a refund for a return. Occurrence: Conditional |
| internationalOverride.returnPeriod | TimeDuration | This container indicates the number of calendar days that 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: Conditional |
| internationalOverride.returnPeriod.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| internationalOverride.returnPeriod.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| internationalOverride.returnsAccepted | boolean | If set to Occurrence: Conditional |
| internationalOverride.returnShippingCostPayer | ReturnShippingCostPayerEnum | This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either Occurrence: Conditional |
| marketplaceId | MarketplaceIdEnum | The ID of the eBay marketplace to which this return business policy applies. Occurrence: Always |
| name | string | A seller-defined name for this return business policy. Names must be unique for policies assigned to the same marketplace. Occurrence: Always |
| refundMethod | RefundMethodEnum | If a seller indicates that they will accept buyer returns, this value will be Occurrence: Conditional |
| restockingFeePercentage | string | Important! This field is deprecated, since eBay no longer allows sellers to charge a restocking fee for buyer remorse returns. Occurrence: Conditional |
| returnInstructions | string | This text-based field provides more details on seller-specified return instructions. Important! This field is no longer supported on many eBay marketplaces. To see if a marketplace and eBay category does support this field, call getReturnPolicies method of the Metadata API. Then you will look for the policyDescriptionEnabled field with a value of Max length: 5000 (8000 for DE) Occurrence: Conditional |
| returnMethod | ReturnMethodEnum | This field will be returned if the seller is willing and able to offer a replacement item as an alternative to 'Money Back'. Occurrence: Conditional |
| returnPeriod | TimeDuration | This container specifies the amount of days that the buyer has to return the item after receiving it. The return period begins when the item is marked "delivered" at the buyer's specified ship-to location. This container will be returned unless the business policy states that the seller does not accept returns. Occurrence: Conditional |
| returnPeriod.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as Occurrence: Conditional |
| returnPeriod.value | integer | An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field. Occurrence: Conditional |
| returnPolicyId | string | A unique eBay-assigned ID for a return business policy. This ID is generated when the policy is created. Occurrence: Always |
| returnsAccepted | boolean | If set to 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 Occurrence: Always |
| warnings | array of ErrorDetailV3 | An array of one or more errors or warnings that were generated during the processing of the request. If there were no issues with the request, this array will return empty. Occurrence: Always |
| warnings.category | string | The category type for this error or warning. It is a string that can have one of three values:
Occurrence: Conditional |
| warnings.domain | string | Name of the domain ,or primary system, of the service or application where the error occurred. 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 | A more detailed explanation of the error than given in the Occurrence: Conditional |
| warnings.message | string | Information 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.outputRefIds | array of string | Identifies specific response elements associated with the error, if any. Path format is the same as Occurrence: Conditional |
| warnings.parameters | array of ErrorParameterV3 | This optional list of name/value pairs that contain context-specific Occurrence: Conditional |
| warnings.parameters.name | string | Name of the parameter that caused the error. Occurrence: Conditional |
| warnings.parameters.value | string | The value of the parameter that caused the error. Occurrence: Conditional |
| warnings.subdomain | string | If 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.
| 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. |
Warnings
For more on warnings, plus the codes of other common warnings, see Handling errors.
| Code | Domain | Category | Meaning |
|---|---|---|---|
| 20200 | API_ACCOUNT | BUSINESS | Warning. {additionalInfo} |
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
Sellers can create one or more return policies for one or more marketplaces as they need.
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
Provide, at a minimum, all required fields of the return policy object in the request payload.
POSThttps://api.ebay.com/sell/account/v1/return_policy
Output
If the call is successful, eBay returns an HTTP status code of 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
This call creates the absolute minimal return policy for when a seller does not accept returns. This sample is for demonstration purposes only; it is highly recommended that as an eBay seller, you always accept returns.
Input
This call truly contains the minimal set of fields needed to create a return policy.
POSThttps://api.ebay.com/sell/account/v1/return_policy
Output
If the call is successful, eBay returns an HTTP status code of 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
This sample creates a common 30-day return policy for both domestic and international returns. Here, the international policy differs from the domestic one in that the buyer, and not the seller, is responsible for the shipping costs on any international returns.
Input
In addition to the required input fields, this sample adds user-defined name and description fields for internal identification and sorting.
POSThttps://api.ebay.com/sell/account/v1/return_policy
Output
If the call is successful, eBay returns an HTTP status code of 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.