This doc page has moved! You should be automatically redirected to the resources page for the eBay Account API. If you are not redirected automatically, follow this link to the Account API.

eBay Account APIVersion 1.2.0

Update a Return Policy

PUT /return_policy/{return_policy_id}

Use this call to update an existing return policy. Specify the policy you want to update using the return_policy_id 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.

Input

See also Samples.

Resource URI (production)

PUT https://api.ebay.com/sell/account/v1/return_policy/{return_policy_id}

URI parameters

Parameter Type Required? Meaning
return_policy_id string Required A unique eBay-assigned ID for a return policy.


HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication.
See HTTP request headers for details.



OAuth request scope

This request requires a user access token with the following scope:

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

See Getting Access Tokens for more information.



Payload model

The following lists all fields that could be included in the request.

{ /* ReturnPolicyRequest */
"categoryTypes": [
    { /* CategoryType */
    "default": boolean,
    "name": string
    }
    /* More CategoryType nodes here */
  ],
"description": string,
"extendedHolidayReturnsOffered": boolean,
"marketplaceId": string,
"name": string,
"refundMethod": string,
"restockingFeePercentage": string,
"returnInstructions": string,
"returnMethod": string,
"returnPeriod":
    { /* TimeDuration */
    "unit": string,
    "value": integer
    },
"returnsAccepted": boolean,
"returnShippingCostPayer": string
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
categoryTypes array of CategoryType Optional 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)
categoryTypes.default boolean Optional Sellers can create multiple policies for any categoryTypes.name and marketplaceId combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type; however, only one can be default at a time.

If this value is set to true, it indicates that 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.
categoryTypes.name string Required The category type to which the policy applies (motor vehicles or non-motor vehicles).
Note: The 'MOTORS_VEHICLES' category type is not valid for return policies because motor vehicle listings are non-returnable via eBay processes.

Applicable values are from CategoryTypeEnum:

ALL_EXCLUDING_MOTORS_VEHICLES
Category type name for all non-motor vehicle listings.
MOTORS_VEHICLES
Category type name for motor vehicle listings.
description string Optional An optional seller-defined description of the return policy.

Max length: 250
Max: 250.
extendedHolidayReturnsOffered boolean Optional If this value is set to true, it indicates the seller offers an Extended Holiday Returns policy for their listings.

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. If the feature is not enabled for the season, this field is ignored.The extended holiday returns period is defined by three dates:
  • The start date - start of November.
  • The purchase cutoff date - end of the year.
  • The end date - end of January.
Note: These dates may vary by a few days each year. Sellers will be 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 the listings until the current year's holiday returns period start date, at which point it overrides the non-holiday returns policy. Buyers will see and be subject to the Extended Holiday Returns offer in listings purchased through the purchase cutoff date, and will be able to return those purchases through the end date.

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 date to be returned.

If the value of holidayReturns is false for an item, the returns period specified by the returnsWithinOption field applies, regardless of the purchase date. If the item is listed with a policy of no returns, holidayReturns is automatically reset to false.

For the AddItem family of calls, the value of holidayReturns is false by default.

For the ReviseItem family of calls, you can omit holidayReturns from the input if its value does not need to change. If the listing being revised has bids or orders, you can add the extended holiday returns option to the listing, but you can't remove it. If the listing does not have bids or orders, you can add or remove the extended holiday returns option; however, this is a significant revision, triggering a version change in the listing.

For the RelistItem family of calls, you can omit holidayReturns from the input if its value does not need to change.
marketplaceId string Required 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.

Applicable values are from MarketplaceIdEnum:See marketplaceId.
name string Required A user-defined name for this return policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64
Max: 64.
refundMethod string Required Indicates the method the seller uses to compensate the buyer for returned items. The return method specified applies only to remorse returns.

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. Use the Trading API GeteBayDetails call to see what values your site(s) 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.

Applicable values are from RefundMethodEnum:

MERCHANDISE_CREDIT
A MERCHANDISE_CREDIT policy indicates the seller offers a credit for items returned for remorse reasons. Use returnMethod to indicate that you also accept requests for exchange or replacement. See GeteBayDetails to see the return types supported by your marketplace.
MONEY_BACK
A MONEY_BACK policy indicates the seller offers a full refund on items returned for remorse reasons.

In the US, you must use MONEY_BACK if you accept returns, but you can also use returnMethod to indicate that you also accept requests for exchange or replacement. See GeteBayDetails to see the return types supported by your marketplace.
restockingFeePercentage string Optional 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. The total amount returned to the buyer is reduced by the cost of the item multiplied by the percentage indicated by this field.

Allowable values are:
  • 0.0: No restocking fee is charged to the buyer
  • 10.0: 10 percent of the item price is charged to the buyer as a restocking fee
  • 15.0: 15 percent of the item price is charged to the buyer as a restocking fee
  • 20.0: 20 percent of the item price is charged to the buyer as a restocking fee
returnInstructions string Optional This optional free-form string field lets the seller provide a detailed explanation of the return policy.

Max length: 5000 characters
Max: 5000.
returnMethod string Required This field indicates the method in which the seller handles non-money back return requests for remorse returns. Sellers can specify they either exchange or replace items.

Applicable values are from ReturnMethodEnum:

EXCHANGE
The return method for remorse returns is an item exchange. Depending on the return policies and specifics, either the seller or the buyer can be responsible for the return shipping.
REPLACEMENT
The return method for remorse returns is an item replacement. Depending on the return policies and specifics, either the seller or the buyer can be responsible for the return shipping.
returnPeriod TimeDuration Required This value indicates the length of time the seller accepts returns, the duration of which starts when the buyer receives the item. If the return policy specifies that the seller accepts returns (ReturnsAccepted=true), then you must set a value for returnPeriod. It's good practice to call out the value you set here in the description field of the policy.

The US marketplace accepts three values for this field (note that TimeDuration is a complex type):
  • 14 Days
  • 30 Days
  • 60 Days
Different marketplaces may support different allowable time periods, and some eBay marketplaces may set a default value for this period (such as '14 Days') if the seller accepts returns but omits this returnPeriod value.

Call GeteBayDetails in the Trading API with DetailName set to ReturnPolicyDetails. In the response review the ReturnPolicyDetails.ReturnsWithin field to see the values supported on the marketplace targeted by the return policy.

Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours.
returnPeriod.unit string Conditional Required if a time duration is required by the call.

Specifies a period of time as a unit that is used to define a duration.

Time-measurement units can be years, months, days, hours, and minutes (see TimeDurationUnitEnum for a complete list of units). The unit is applied to the number in the value field to define a span of time.

Note that 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 your are using.

Applicable values are from TimeDurationUnitEnum:See unit.
returnPeriod.value integer Conditional Required if a time duration is required by the call.

An amount of time, as measured by the units specified in the unit field.

Note that 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 your are instantiating.
returnsAccepted boolean Required Set this value to true to indicate the seller accepts returns.

All marketplaces allow the seller to choose between accepting or not accepting returns. However, on some European eBay marketplaces (e.g., UK IE, and DE), sellers are required to accept returns for fixed-price items and auctions listed with Buy It Now.

See Returns and the Law (UK).

Note that Top-Rated sellers must accept item returns for a listing in order for that listing to receive a Top-Rated Plus badge on the View Item or search result pages.
returnShippingCostPayer string Required The seller uses this value to specify whether the buyer or the seller is responsible for paying return shipping charges.

Note that the seller is always responsible for return shipping costs for SNAD-related issues.

Applicable values are from ReturnShippingCostPayerEnum:

BUYER
Return shipping cost paid by BUYER.
SELLER
Return shipping cost paid by SELLER.

Output

See also Samples.

HTTP status codes

This call can return one of the following HTTP status codes. See the HTTP Status Code Registry for a complete overview of HTTP status codes.

Status Meaning
200 OK
400 Bad Request
404 Not Found
500 Internal Server Error

Payload model

Note: For information about the error fields and how to work with them, see Error Handling.

The following lists all fields that could be included in the response.

{ /* SetReturnPolicyResponse */
"categoryTypes": [
    { /* CategoryType */
    "default": boolean,
    "name": string
    }
    /* More CategoryType nodes here */
  ],
"description": string,
"extendedHolidayReturnsOffered": boolean,
"marketplaceId": string,
"name": string,
"refundMethod": string,
"restockingFeePercentage": string,
"returnInstructions": string,
"returnMethod": string,
"returnPeriod":
    { /* TimeDuration */
    "unit": string,
    "value": integer
    },
"returnPolicyId": string,
"returnsAccepted": boolean,
"returnShippingCostPayer": string,
"warnings": [
    { /* ErrorDetailV3 */
    "category": string,
    "domain": string,
    "errorId": integer,
    "inputRefIds": [
        string
        /* More string nodes here */
      ],
    "longMessage": string,
    "message": string,
    "outputRefIds": [
        string
        /* More string nodes here */
      ],
    "parameters": [
        { /* ErrorParameterV3 */
        "name": string,
        "value": string
        }
        /* More ErrorParameterV3 nodes here */
      ],
    "subdomain": string
    }
    /* More ErrorDetailV3 nodes here */
  ]
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
categoryTypes array of CategoryType Always 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)
categoryTypes.default boolean Always Sellers can create multiple policies for any categoryTypes.name and marketplaceId combination. For example, you can create multiple fulfillment policies for one marketplace, where they all target the same category type; however, only one can be default at a time.

If this value is set to true, it indicates that 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.
categoryTypes.name string Always The category type to which the policy applies (motor vehicles or non-motor vehicles).
Note: The 'MOTORS_VEHICLES' category type is not valid for return policies because motor vehicle listings are non-returnable via eBay processes.

Applicable values are from CategoryTypeEnum:

ALL_EXCLUDING_MOTORS_VEHICLES
Category type name for all non-motor vehicle listings.
MOTORS_VEHICLES
Category type name for motor vehicle listings.

Code so that your app gracefully handles any future changes to this list.
description string Conditionally An optional seller-defined description of the return policy.

Max length: 250
Max: 250.
extendedHolidayReturnsOffered boolean Always If this value is set to true, it indicates the seller offers an Extended Holiday Returns policy for their listings.

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.
marketplaceId string Always 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.

Applicable values are from MarketplaceIdEnum:See marketplaceId.
Code so that your app gracefully handles any future changes to this list.
name string Always A user-defined name for this return policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64
Max: 64.
refundMethod string Always Indicates the method the seller uses to compensate the buyer for returned items. The return method specified applies only to remorse returns.

Applicable values are from RefundMethodEnum:

MERCHANDISE_CREDIT
A MERCHANDISE_CREDIT policy indicates the seller offers a credit for items returned for remorse reasons. Use returnMethod to indicate that you also accept requests for exchange or replacement. See GeteBayDetails to see the return types supported by your marketplace.
MONEY_BACK
A MONEY_BACK policy indicates the seller offers a full refund on items returned for remorse reasons.

In the US, you must use MONEY_BACK if you accept returns, but you can also use returnMethod to indicate that you also accept requests for exchange or replacement. See GeteBayDetails to see the return types supported by your marketplace.

Code so that your app gracefully handles any future changes to this list.
restockingFeePercentage string Conditionally Optionally set by the seller, the percentage charged if the seller charges buyers a a restocking fee when items are returned. The total amount charged to the buyer is the cost of the item multiplied by the percentage indicated in this field.
returnInstructions string Conditionally This optional free-form string field lets the seller provide a detailed explanation of the return policy.

Max length: 5000 characters
Max: 5000.
returnMethod string Always This field indicates the method in which the seller handles non-money back return requests for remorse returns. Sellers can specify they either exchange or replace items.

Applicable values are from ReturnMethodEnum:

EXCHANGE
The return method for remorse returns is an item exchange. Depending on the return policies and specifics, either the seller or the buyer can be responsible for the return shipping.
REPLACEMENT
The return method for remorse returns is an item replacement. Depending on the return policies and specifics, either the seller or the buyer can be responsible for the return shipping.

Code so that your app gracefully handles any future changes to this list.
returnPeriod TimeDuration Always This value indicates the length of time the seller accepts returns, the duration of which starts when the buyer receives the item.
returnPeriod.unit string Conditionally Required if a time duration is required by the call.

Specifies a period of time as a unit that is used to define a duration.

Time-measurement units can be years, months, days, hours, and minutes (see TimeDurationUnitEnum for a complete list of units). The unit is applied to the number in the value field to define a span of time.

Note that 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 your are using.

Applicable values are from TimeDurationUnitEnum:See unit.
Code so that your app gracefully handles any future changes to this list.
returnPeriod.value integer Conditionally Required if a time duration is required by the call.

An amount of time, as measured by the units specified in the unit field.

Note that 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 your are instantiating.
returnPolicyId string Always A unique eBay-assigned ID for this policy.
returnsAccepted boolean Always If set to true, it indicates the seller accepts returns.
returnShippingCostPayer string Always The seller uses this value to specify who is responsible for paying the return shipping charges, either the buyer or the seller.

Note that the seller is always responsible for return shipping costs for SNAD-related issues.

Applicable values are from ReturnShippingCostPayerEnum:

BUYER
Return shipping cost paid by BUYER.
SELLER
Return shipping cost paid by SELLER.

Code so that your app gracefully handles any future changes to this list.
warnings array of ErrorDetailV3 Always A list of warnings related to request. This field normally returns empty, which indicates the request did not generate any warnings.
warnings.category string Conditionally The category type for this error or warning. It takes an ErrorCategory object which 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.
warnings.domain string Conditionally Name of the domain containing the service or application.
warnings.errorId integer Conditionally 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.
warnings.inputRefIds array of string Conditionally Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use JSONPath notation.
warnings.longMessage string Conditionally An expanded version of message that should be around 100-200 characters long, but is not required to be such.
warnings.message string Conditionally 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.
warnings.outputRefIds array of string Conditionally Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.
warnings.parameters array of ErrorParameterV3 Conditionally 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.
warnings.parameters.name string Conditionally Name of the entity that threw the error.
warnings.parameters.value string Conditionally A description of the error.
warnings.subdomain string Conditionally Name of the domain's subsystem or subdivision. For example, checkout is a subdomain in the buying domain.



Error Codes

Code Domain Category Nature Meaning
20200 API_ACCOUNT BUSINESS WARNING Warning. {additionalInfo}
20400 API_ACCOUNT REQUEST ERROR Invalid request. {additionalInfo}
20401 API_ACCOUNT REQUEST ERROR Missing field {fieldName}. {additionalInfo}
20402 API_ACCOUNT REQUEST ERROR Invalid input. {additionalInfo}
20403 API_ACCOUNT REQUEST ERROR Invalid {fieldName}. {additionalInfo}
20404 API_ACCOUNT REQUEST ERROR {fieldName} not found.
20406 API_ACCOUNT REQUEST ERROR Invalid return option. {fieldName}
20500 API_ACCOUNT APPLICATION ERROR System error.
20501 API_ACCOUNT APPLICATION ERROR Service unavailable. Please try again in next 24 hours.



Samples

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Sample: Update a Return Policy

Description

This example updates default return policy.

Input

This example specifies a new default return return policy. Note that this is the only use case where you need to include the categoryTypes field in a return policy. To specify a new default policy for a specific marketplace, you only need to indicate which policy is the new default for the marketplace and categoryTypes.name combination, eBay sets the default field for the old default policy to false.

When updating an existing policy, be sure to provide the entire policy object and in your request payload, with the changes made to the fields that you want to update. To obtain the existing policy object, perform a GET operation using ID of the policy you want to update. Us this same policy ID value in the retrunPolicyId path parameter.

Note that you cannot update all the fields in the policy object. For example, you cannot update the policy ID value.

URL format. See also the non-wrapped version of this URL.

PUT https://api.sandbox.ebay.com/sell/account/v1/return_policy/5487698000

{
  "name": "detailed return policy",
  "description": "Policy specifies restocking fee and handling for remorse return items.",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
      "default": "true"
    }
  ],
  "returnsAccepted": true,
  "returnPeriod": {
    "value": 60,
    "unit": "DAY"
  },
  "restockingFeePercentage": "10.0",
  "refundMethod": "MONEY_BACK",
  "returnMethod": "EXCHANGE",
  "returnShippingCostPayer": "BUYER",
  "returnInstructions": "Buyer pays for return shipping. Store credit for remorse returns."
}

Output

A successful call returns an HTTP status code of 200 OK and a response body containing the updated return policy.

JSON format.
{
  "name": "detailed return policy",
  "description": "Policy specifies restocking fee and handling for remorse return items.",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
      "default": true
    }
  ],
  "returnsAccepted": true,
  "returnPeriod": {
    "value": 60,
    "unit": "DAY"
  },
  "extendedHolidayReturnsOffered": false,
  "restockingFeePercentage": "10.0",
  "refundMethod": "MONEY_BACK",
  "returnMethod": "EXCHANGE",
  "returnShippingCostPayer": "BUYER",
  "returnInstructions": "Buyer pays for return shipping. Store credit for remorse returns.",
  "returnPolicyId": "5487698000",
  "warnings": []
}



Change History

Change Date Description
1.0.0
2016-10-19
  • Call (added): New call.