Skip to main content

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

POST https://api.ebay.com/sell/account/v1/return_policy

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.

HeaderTypeDescription
Content-TypestringThis 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 clipboard

Request fields

Input container/fieldTypeDescription
categoryTypesarray 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 must be set to ALL_EXCLUDING_MOTORS_VEHICLES for return business policies.

Occurrence: Required

categoryTypes.defaultboolean

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: Optional

categoryTypes.nameCategoryTypeEnum

The category type to which the policy applies (motor vehicles or non-motor vehicles).

The MOTORS_VEHICLES category type is not valid for return policies. eBay flows do not support the return of motor vehicles.

Occurrence: Required

descriptionstring

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: Optional

extendedHolidayReturnsOfferedboolean

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

internationalOverrideInternationalReturnOverrideType

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.returnMethodReturnMethodEnum

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.returnPeriodTimeDuration

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

internationalOverride.returnPeriod.unitTimeDurationUnitEnum

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

internationalOverride.returnPeriod.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

internationalOverride.returnsAcceptedboolean

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

internationalOverride.returnShippingCostPayerReturnShippingCostPayerEnum

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

marketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace to which this return business policy applies.

Occurrence: Required

namestring

A seller-defined name for this return business policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Required

refundMethodRefundMethodEnum

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

restockingFeePercentagestring

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

returnInstructionsstring

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 true for the eBay category.


Max length: 5000 (8000 for DE)

Occurrence: Optional

returnMethodReturnMethodEnum

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

returnPeriodTimeDuration

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.

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 return period is set using the TimeDuration type, where you set unit to DAY and value 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.

Required if returnsAccepted is set to true.

Occurrence: Conditional

returnPeriod.unitTimeDurationUnitEnum

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

returnPeriod.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

returnsAcceptedboolean

If set to 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: Required

returnShippingCostPayerReturnShippingCostPayerEnum

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.

This field is conditionally required if returnsAccepted is set to true.

Occurrence: Conditional

Output

HTTP response headers

See HTTP response headers for details.

HeaderMeaning
LocationThe 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/fieldTypeDescription
categoryTypesarray of CategoryType

This field always returns ALL_EXCLUDING_MOTORS_VEHICLES for return business policies, since return business policies are not applicable to motor vehicle listings.

Occurrence: Always

categoryTypes.defaultboolean

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

categoryTypes.nameCategoryTypeEnum

The category type to which the policy applies (motor vehicles or non-motor vehicles).

The MOTORS_VEHICLES category type is not valid for return policies. eBay flows do not support the return of motor vehicles.

Occurrence: Always

descriptionstring

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.

Max length: 250

Occurrence: Conditional

extendedHolidayReturnsOfferedboolean

Important! This field is deprecated, since eBay no longer supports extended holiday returns. This field should no longer be returned.

Occurrence: Conditional

internationalOverrideInternationalReturnOverrideType

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.returnMethodReturnMethodEnum

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.returnPeriodTimeDuration

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

internationalOverride.returnPeriod.unitTimeDurationUnitEnum

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

internationalOverride.returnPeriod.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

internationalOverride.returnsAcceptedboolean

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

internationalOverride.returnShippingCostPayerReturnShippingCostPayerEnum

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

marketplaceIdMarketplaceIdEnum

The ID of the eBay marketplace to which this return business policy applies.

Occurrence: Always

namestring

A seller-defined name for this return business policy. Names must be unique for policies assigned to the same marketplace.

Max length: 64

Occurrence: Always

refundMethodRefundMethodEnum

If a seller indicates that they will accept buyer returns, this value will be MONEY_BACK.

Occurrence: Conditional

restockingFeePercentagestring

Important! This field is deprecated, since eBay no longer allows sellers to charge a restocking fee for buyer remorse returns.

Occurrence: Conditional

returnInstructionsstring

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 true for the eBay category.


Max length: 5000 (8000 for DE)

Occurrence: Conditional

returnMethodReturnMethodEnum

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

returnPeriodTimeDuration

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.unitTimeDurationUnitEnum

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

returnPeriod.valueinteger

An integer that represents an amount of time, as measured by the time-measurement unit specified in the unit field.

Occurrence: Conditional

returnPolicyIdstring

A unique eBay-assigned ID for a return business policy. This ID is generated when the policy is created.

Occurrence: Always

returnsAcceptedboolean

If set to true, the seller accepts returns. If set to false, this field indicates that the seller does not accept returns.

Occurrence: Always

returnShippingCostPayerReturnShippingCostPayerEnum

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.

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

This container will be returned unless the business policy states that the seller does not accept returns.

Occurrence: Always

warningsarray 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.categorystring

The category type for this error or warning. It is a string that 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.

Occurrence: Conditional

warnings.domainstring

Name of the domain ,or primary system, of the service or application where the error occurred.

Occurrence: Conditional

warnings.errorIdinteger

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.inputRefIdsarray 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.longMessagestring

A more detailed explanation of the error than given in the message error field.

Occurrence: Conditional

warnings.messagestring

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.outputRefIdsarray of string

Identifies specific response elements associated with the error, if any. Path format is the same as inputRefId.

Occurrence: Conditional

warnings.parametersarray of ErrorParameterV3

This optional list of name/value pairs that contain context-specific ErrorParameter objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each ErrorParameter object consists of two fields, a name and a value.

Occurrence: Conditional

warnings.parameters.namestring

Name of the parameter that caused the error.

Occurrence: Conditional

warnings.parameters.valuestring

The value of the parameter that caused the error.

Occurrence: Conditional

warnings.subdomainstring

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.

StatusMeaning
201Created
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
20400API_ACCOUNTREQUESTInvalid request. {additionalInfo}
20401API_ACCOUNTREQUESTMissing field .
20406API_ACCOUNTREQUESTInvalid return option
20500API_ACCOUNTAPPLICATIONSystem error.
20501API_ACCOUNTAPPLICATIONService unavailable. Please try again in next 24 hours.

Warnings

For more on warnings, plus the codes of other common warnings, see Handling errors.

CodeDomainCategoryMeaning
20200API_ACCOUNTBUSINESSWarning. {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.sandbox.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.sandbox.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.sandbox.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.

Got thoughts? Click the feedback button – your insights help us improve!