getReturnPolicies: eBay Account API | eBay Developers Program

GET/return_policy

This method retrieves all the return policies configured for the marketplace you specify using the marketplace_id query parameter.

Marketplaces and locales

Get the correct policies for a marketplace that supports multiple locales using the Content-Language request header. For example, get the policies for the French locale of the Canadian marketplace by specifying fr-CA for the Content-Language header. Likewise, target the Dutch locale of the Belgium marketplace by setting Content-Language: nl-BE. For details on header values, see HTTP request headers.

Input

Resource URI

GET https://api.ebay.com/sell/account/v1/return_policy?

marketplace_id=MarketplaceIdEnum

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

Parameter	Type	Description
marketplace_id	MarketplaceIdEnum	This query parameter specifies the ID of the eBay marketplace of the policy you want to retrieve. Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

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

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

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* ReturnPolicyResponse */

"href" : "string",

"limit" : "integer",

"next" : "string",

"offset" : "integer",

"prev" : "string",

"returnPolicies" : [

{ /* ReturnPolicy */

"categoryTypes" : [

{ /* CategoryType */

"default" : "boolean",

"name" : "CategoryTypeEnum : [MOTORS_VEHICLES,ALL_EXCLUDING_MOTORS_VEHICLES]"

}

"description" : "string",

"extendedHolidayReturnsOffered" : "boolean",

"internationalOverride" :

{ /* InternationalReturnOverrideType */

"returnMethod" : "ReturnMethodEnum : [EXCHANGE,REPLACEMENT]",

"returnPeriod" :

{ /* TimeDuration */

"unit" : "TimeDurationUnitEnum : [YEAR,MONTH,DAY...]",

"value" : "integer"

"returnsAccepted" : "boolean",

"returnShippingCostPayer" : "ReturnShippingCostPayerEnum : [BUYER,SELLER]"

"marketplaceId" : "MarketplaceIdEnum : [EBAY_AT,EBAY_AU,EBAY_BE...]",

"name" : "string",

"refundMethod" : "RefundMethodEnum : [MERCHANDISE_CREDIT,MONEY_BACK]",

"restockingFeePercentage" : "string",

"returnInstructions" : "string",

"returnMethod" : "ReturnMethodEnum : [EXCHANGE,REPLACEMENT]",

"returnPeriod" :

{ /* TimeDuration */

"unit" : "TimeDurationUnitEnum : [YEAR,MONTH,DAY...]",

"value" : "integer"

"returnPolicyId" : "string",

"returnsAccepted" : "boolean",

"returnShippingCostPayer" : "ReturnShippingCostPayerEnum : [BUYER,SELLER]"

}

"total" : "integer"

}

Response fields

Output container/field	Type	Description
href	string	This field is for future use. Occurrence: Conditional
limit	integer	This field is for future use. Occurrence: Conditional
next	string	This field is for future use. Occurrence: Conditional
offset	integer	This field is for future use. Occurrence: Conditional
prev	string	This field is for future use. Occurrence: Conditional
returnPolicies	array of ReturnPolicy	A list of all of the seller's return business policies defined for the specified marketplace. This array will be returned as empty if no return business policies are defined for the specified marketplace. Occurrence: Always
returnPolicies.categoryTypes	array of CategoryType	This container indicates which category group that the return policy applies to. Note: Return business policies are not applicable to motor vehicle listings, so the categoryTypes.name value will always be `ALL_EXCLUDING_MOTORS_VEHICLES` for return business policies. Occurrence: Always
returnPolicies.categoryTypes.default	boolean	Note: This field has been deprecated and is no longer used. Do not include this field in any create or update method. This field may be returned within the payload of a get method, but it can be ignored. Occurrence: Conditional
returnPolicies.categoryTypes.name	CategoryTypeEnum	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. eBay flows do not support the return of motor vehicles. Occurrence: Always
returnPolicies.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. Max length: 250 Occurrence: Conditional
returnPolicies.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: Conditional
returnPolicies.internationalOverride	InternationalReturnOverrideType	This container shows the seller's international return policy settings. This container is only returned if the seller has set a separate international return policy for the business policies. International return policies are optional, even if the seller ships to international locations. If a separate international return policy is not set, all of the domestic return policy settings also apply to international orders. Occurrence: Conditional
returnPolicies.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
returnPolicies.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. 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 return periods for one or more categories, call getReturnPolicies method of the Metadata API. The TimeDuration type is used to set/indicate the return period, and you set the unit value to `DAY` and the value field 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. This field is conditionally required if the internationalOverride.returnsAccepted field is set to `true`. Occurrence: Conditional
returnPolicies.internationalOverride.returnPeriod.unit	TimeDurationUnitEnum	These enum values represent the time measurement unit, such as `DAY`. A span of time is defined when you apply the value specified in the value field to the value specified for unit. See TimeDurationUnitEnum for a complete list of possible time-measurement units. Occurrence: Conditional
returnPolicies.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
returnPolicies.internationalOverride.returnsAccepted	boolean	If set to `true`, the seller accepts international returns. If set to `false`, the seller does not accept international returns. This field is conditionally required if the seller chooses to have a separate international return policy. Occurrence: Conditional
returnPolicies.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 `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 'significantly not as described' (SNAD) issues. This field is conditionally required if the internationalOverride.returnsAccepted field is set to `true`. Occurrence: Conditional
returnPolicies.marketplaceId	MarketplaceIdEnum	The ID of the eBay marketplace to which this return business policy applies. Occurrence: Always
returnPolicies.name	string	A seller-defined name for this payment business policy. Names must be unique for policies assigned to the same marketplace. Max length: 64 Occurrence: Always
returnPolicies.refundMethod	RefundMethodEnum	If a seller indicates that they will accept buyer returns, this value will be set to `MONEY_BACK`. Occurrence: Always
returnPolicies.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 and it is no longer returned. Occurrence: Conditional
returnPolicies.returnInstructions	string	This text-based field provides more details on seller-specified return instructions. This field is only returned if set for the return business policy. 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 `true` for the eBay category. Max length: 5000 (8000 for DE) Occurrence: Conditional
returnPolicies.returnMethod	ReturnMethodEnum	This field is only returned if the seller is willing to offer a replacement item as an alternative to 'Money Back'. Occurrence: Conditional
returnPolicies.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. Most categories support 30-day and 60-day return periods. Note: Unless the seller has set a separate international return policy through the internationalOverride container, this return period will be valid for domestic and international returns (if the seller ships internationally). Occurrence: Always
returnPolicies.returnPeriod.unit	TimeDurationUnitEnum	These enum values represent the time measurement unit, such as `DAY`. A span of time is defined when you apply the value specified in the value field to the value specified for unit. See TimeDurationUnitEnum for a complete list of possible time-measurement units. Occurrence: Conditional
returnPolicies.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
returnPolicies.returnPolicyId	string	A unique eBay-assigned ID for a return business policy. This ID is generated when the policy is created. Occurrence: Always
returnPolicies.returnsAccepted	boolean	If this field is returned as `true`, the seller accepts returns. 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: Always
returnPolicies.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
total	integer	The total number of return business policies retrieved in the result set. If no return business policies are defined for the specified marketplace, this field is returned with a value of `0`. Occurrence: Always

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
200	Success
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
20401	API_ACCOUNT	REQUEST	Missing field {fieldName}. {additionalInfo}
20403	API_ACCOUNT	REQUEST	Invalid {fieldName}. {additionalInfo}
20404	API_ACCOUNT	REQUEST	{fieldName} not found.
20500	API_ACCOUNT	APPLICATION	System error.
20501	API_ACCOUNT	APPLICATION	Service unavailable. Please try again in next 24 hours.

Warnings

This call has no warnings.

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: Get all Return Policies

Sellers can create one or more return policies for a particular marketplace. This call returns all the current policies for the specified marketplace.

Input

Specify the marketplace for the policies you want to retrieve using the marketplace_id query parameter.

GEThttps://api.ebay.com/sell/account/v1/return_policy?marketplace_id=EBAY_US

Output

If the call is successful, eBay returns an HTTP status code of 200 OK and a complete list of the return policies associated with the specified marketplace.

{
    "total": 3,
    "returnPolicies": [
        {
            "name": "3********y",
            "description": "Policy specifies an international return policy in addition to the domestic return policy.",
            "marketplaceId": "EBAY_US",
            "categoryTypes": [
                {
                    "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
                    "default": true
                }
            ],
            "returnsAccepted": true,
            "returnPeriod": {
                "value": 30,
                "unit": "DAY"
            },
            "refundMethod": "MONEY_BACK",
            "returnMethod": "REPLACEMENT",
            "returnShippingCostPayer": "SELLER",
            "internationalOverride": {
                "returnsAccepted": true,
                "returnPeriod": {
                    "value": 60,
                    "unit": "DAY"
                },
                "returnShippingCostPayer": "BUYER"
            },
            "returnPolicyId": "5********0"
        },
        {
            "name": "n********y",
            "marketplaceId": "EBAY_US",
            "categoryTypes": [
                {
                    "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
                    "default": false
                }
            ],
            "returnsAccepted": false,
            "returnPolicyId": "5********0"
        },
        {
            "name": "m********e",
            "marketplaceId": "EBAY_US",
            "categoryTypes": [
                {
                    "name": "ALL_EXCLUDING_MOTORS_VEHICLES",
                    "default": false
                }
            ],
            "returnsAccepted": true,
            "returnPeriod": {
                "value": 30,
                "unit": "DAY"
            },
            "refundMethod": "MONEY_BACK",
            "returnShippingCostPayer": "SELLER",
            "returnPolicyId": "5********0"
        }
    ]
}