GET/return_policy
This method retrieves all the return policies configured for the marketplace you specify using the marketplace_id query parameter.
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
| Parameter | Type | Description |
|---|---|---|
| marketplace_id | MarketplaceIdEnum | This query parameter specifies the ID of the eBay marketplace of the policies 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.
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-Language | string | 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. Occurrence: Conditional |
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
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. Occurrence: Always |
| returnPolicies.categoryTypes.default | boolean | Note: This field has been deprecated and is no longer used. Occurrence: Conditional |
| returnPolicies.categoryTypes.name | CategoryTypeEnum | The category type to which the policy applies (motor vehicles or non-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. 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 policy. 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. Occurrence: Conditional |
| returnPolicies.internationalOverride.returnPeriod.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as 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 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 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 return business policy. Names must be unique for policies assigned to the same marketplace. Occurrence: Always |
| returnPolicies.refundMethod | RefundMethodEnum | This field indicates the refund method offered by the seller. Its value will be 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 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. Occurrence: Conditional |
| returnPolicies.returnPeriod.unit | TimeDurationUnitEnum | These enum values represent the time measurement unit, such as 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 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 Occurrence: Conditional |
| total | integer | The total number of return business policies retrieved in the result set. 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.