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

Get a Return Policy by Name

GET /return_policy/get_by_policy_name

This call retrieves the complete details of a single return policy. Supply both the policy name and its associated marketplace_id in the call's query parameters.

Input

See also Samples.

Resource URI (production)

GET https://api.ebay.com/sell/account/v1/return_policy/get_by_policy_name?
  marketplace_id=MarketplaceIdEnum&
  name=string

URI parameters

Parameter Type Required? Meaning
marketplace_id string Required A unique identifier for an eBay marketplace.

Applicable values are from MarketplaceIdEnum.
name string Required User-defined return policy name.


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

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

See Getting Access Tokens for more information.



Payload model

This call has no request payload.


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 Success
400 Bad Request
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.

{ /* ReturnPolicy */
"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
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
categoryTypes array of CategoryType Conditionally 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 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
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. 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 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.

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.

Code so that your app gracefully handles any future changes to this list.
restockingFeePercentage string Conditionally 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 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. 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 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 this value is set to true, it indicates 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 Always 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.

Code so that your app gracefully handles any future changes to this list.



Error Codes

Code Domain Category Nature Meaning
20401 API_ACCOUNT REQUEST ERROR Missing field {fieldName}. {additionalInfo}
20403 API_ACCOUNT REQUEST ERROR Invalid {fieldName}. {additionalInfo}
20404 API_ACCOUNT REQUEST ERROR {fieldName} not found.
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: Get Return Policy by Name

Description

This call retrieves the return policy that matches the name you specify in the request.

Input

This call uses two query parameters to identify the policy you want to retrieve. Specify the name of the policy you want to retrieve using the name query parameter and supply the marketplace for the policy using the marketplace_id parameter. This call does not use a request body.

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

GET https://api.sandbox.ebay.com/sell/account/v1/return_policy/get_by_policy_name?
   name=minimal return policy, US marketplace&
   marketplace_id=EBAY_US

Output

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

JSON format.
{
  "name": "minimal return policy, US marketplace",
  "marketplaceId": "EBAY_US",
  "categoryTypes": [
    {
      "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
      "default": false
    }
  ],
  "returnsAccepted": true,
  "returnPeriod": {
    "value": 30,
    "unit": "DAY"
  },
  "extendedHolidayReturnsOffered": false,
  "restockingFeePercentage": "0.0",
  "refundMethod": "MONEY_BACK",
  "returnShippingCostPayer": "SELLER",
  "returnPolicyId": "5487680000"
}



Change History

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