createReturnPolicy

v1.0.0

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 .

Input

{
  "type": "object",
  "description": "Return policy request",
  "properties": {
    "categoryTypes": {
      "type": "array",
      "description": "This container indicates which category group that the return policy applies to.<br/><br/><span class=\"tablenote\"><b>Note</b>: Return business policies are not applicable to motor vehicle listings, so the <b>categoryTypes.name</b> value must be set to <code>ALL_EXCLUDING_MOTORS_VEHICLES</code> for return business policies.</span>",
      "items": {
        "type": "object",
        "description": "The category type discerns whether the policy applies to motor vehicle listings, or to any other items except motor vehicle listings. <br/><br/>Each business policy can be associated with either or both categories ('MOTORS_VEHICLES' and 'ALL_EXCLUDING_MOTORS_VEHICLES'); however, return business policies are not applicable for motor vehicle listings.",
        "properties": {
          "default": {
            "type": "boolean",
            "description": "<span class=\"tablenote\"><strong>Note:</strong> This field has been deprecated and is no longer used.<ul><li>Do not include this field in any <b>create</b> or <b>update</b> method.</li><li>This field may be returned within the payload of a <b>get</b> method, but it can be ignored.</li></ul></span>"
          },
          "name": {
            "type": "string",
            "description": "The category type to which the policy applies (motor vehicles or non-motor vehicles). <br /><br />The <code>MOTORS_VEHICLES</code> category type is not valid for return policies. eBay flows do not support the return of motor vehicles. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:CategoryTypeEnum'>eBay API documentation</a>"
          }
        }
      }
    },
    "description": {
      "type": "string",
      "description": "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.  <br/><br/><b>Max length</b>: 250"
    },
    "extendedHolidayReturnsOffered": {
      "type": "boolean",
      "description": "<p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> This field is deprecated, since eBay no longer supports extended holiday returns. Any value supplied in this field is neither read nor returned.</p> "
    },
    "internationalOverride": {
      "type": "object",
      "description": "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.",
      "properties": {
        "returnMethod": {
          "type": "string",
          "description": "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. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnMethodEnum'>eBay API documentation</a>"
        },
        "returnPeriod": {
          "type": "object",
          "description": "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.  <br/><br/>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 <a href=\"/api-docs/sell/metadata/resources/marketplace/methods/getReturnPolicies\">getReturnPolicies</a> method of the <b>Metadata API</b>. <br/><br/>The <b>TimeDuration</b> type is used to set/indicate the return period, and you set the <b>unit</b> value to <code>DAY</code> and the <b>value</b> field to either <code>30</code> or <code>60</code> (or other value, as appropriate).  <br/><br/>Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours.  <br/><br/>This field is conditionally required if the <b>internationalOverride.returnsAccepted</b> field is set to <code>true</code>.",
          "properties": {
            "unit": {
              "type": "string",
              "description": "These enum values represent the time measurement unit, such as <code>DAY</code>. A span of time is defined when you apply the value specified in the <b>value</b> field to the value specified for <b>unit</b>. <br/><br/>See <b>TimeDurationUnitEnum</b> for a complete list of possible time-measurement units. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:TimeDurationUnitEnum'>eBay API documentation</a>"
            },
            "value": {
              "type": "integer",
              "format": "int32",
              "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the <b>unit</b> field."
            }
          }
        },
        "returnShippingCostPayer": {
          "type": "string",
          "description": "This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either <code>BUYER</code> or <code>SELLER</code>.  <br/><br/>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.  <br/><br/>This field is conditionally required if the <b>internationalOverride.returnsAccepted</b> field is set to <code>true</code>. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnShippingCostPayerEnum'>eBay API documentation</a>"
        },
        "returnsAccepted": {
          "type": "boolean",
          "description": "If set to <code>true</code>, the seller accepts international returns. If set to <code>false</code>, the seller does not accept international returns.  <br/><br/>This field is conditionally required if the seller chooses to have a separate international return policy."
        }
      }
    },
    "marketplaceId": {
      "type": "string",
      "description": "The ID of the eBay marketplace to which this return business policy applies.  For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:MarketplaceIdEnum'>eBay API documentation</a>"
    },
    "name": {
      "type": "string",
      "description": "A seller-defined name for this return business policy. Names must be unique for policies assigned to the same marketplace. <br/><br/><b>Max length</b>: 64"
    },
    "refundMethod": {
      "type": "string",
      "description": "This value indicates the refund method that will be used by the seller for buyer returns.<p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> If this field is not included in a return business policy, it will default to MONEY_BACK.</p> For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:RefundMethodEnum'>eBay API documentation</a>"
    },
    "restockingFeePercentage": {
      "type": "string",
      "description": "<p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> 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.</p>"
    },
    "returnInstructions": {
      "type": "string",
      "description": "This text-based field provides more details on seller-specified return instructions. <p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> This field is no longer supported on many eBay marketplaces. To see if a marketplace and eBay category does support this field, call <a href=\"/api-docs/sell/metadata/resources/marketplace/methods/getReturnPolicies\">getReturnPolicies</a> method of the <b>Metadata API</b>. Then you will look for the <b>policyDescriptionEnabled</b> field with a value of <code>true</code> for the eBay category.</span></p><br/><b>Max length</b>: 5000 (8000 for DE)"
    },
    "returnMethod": {
      "type": "string",
      "description": "This field can be used if the seller is willing and able to offer a replacement item as an alternative to 'Money Back'. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnMethodEnum'>eBay API documentation</a>"
    },
    "returnPeriod": {
      "type": "object",
      "description": "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.  <br/><br/>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.  <br/><br/>For a definitive list of return periods for one or more categories, call <a href=\"/api-docs/sell/metadata/resources/marketplace/methods/getReturnPolicies\">getReturnPolicies</a> method of the <b>Metadata API</b>.<br/><br/>The return period is set using the <b>TimeDuration</b> type, where you set <b>unit</b> to <code>DAY</code> and <b>value</b> to either <code>30</code> or <code>60</code> (or other value, as appropriate).  <br/><br/>Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours.  <br/><br/><i>Required if </i> <b>returnsAccepted</b> is set to <code>true</code>.",
      "properties": {
        "unit": {
          "type": "string",
          "description": "These enum values represent the time measurement unit, such as <code>DAY</code>. A span of time is defined when you apply the value specified in the <b>value</b> field to the value specified for <b>unit</b>. <br/><br/>See <b>TimeDurationUnitEnum</b> for a complete list of possible time-measurement units. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:TimeDurationUnitEnum'>eBay API documentation</a>"
        },
        "value": {
          "type": "integer",
          "format": "int32",
          "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the <b>unit</b> field."
        }
      }
    },
    "returnShippingCostPayer": {
      "type": "string",
      "description": "This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either <code>BUYER</code> or <code>SELLER</code>.  <br/><br/>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.  <br/><br/>This field is conditionally required if <b>returnsAccepted</b> is set to <code>true</code>. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnShippingCostPayerEnum'>eBay API documentation</a>"
    },
    "returnsAccepted": {
      "type": "boolean",
      "description": "If set to <code>true</code>, the seller accepts returns. <p><span class=\"tablenote\"><strong>Note:</strong>Top-Rated sellers must accept item returns and the <b>handlingTime</b> 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 <a href=\"http://pages.ebay.com/help/sell/top-rated.html \">Becoming a Top Rated Seller and qualifying for Top Rated Plus benefits</a>.</span></p>"
    }
  }
}

Output

{
  "type": "object",
  "description": "A complex type that is populated with a response containing a return policies.",
  "properties": {
    "categoryTypes": {
      "type": "array",
      "description": "This field always returns <code>ALL_EXCLUDING_MOTORS_VEHICLES</code> for return business policies, since return business policies are not applicable to motor vehicle listings.",
      "items": {
        "type": "object",
        "description": "The category type discerns whether the policy applies to motor vehicle listings, or to any other items except motor vehicle listings. <br/><br/>Each business policy can be associated with either or both categories ('MOTORS_VEHICLES' and 'ALL_EXCLUDING_MOTORS_VEHICLES'); however, return business policies are not applicable for motor vehicle listings.",
        "properties": {
          "default": {
            "type": "boolean",
            "description": "<span class=\"tablenote\"><strong>Note:</strong> This field has been deprecated and is no longer used.<ul><li>Do not include this field in any <b>create</b> or <b>update</b> method.</li><li>This field may be returned within the payload of a <b>get</b> method, but it can be ignored.</li></ul></span>"
          },
          "name": {
            "type": "string",
            "description": "The category type to which the policy applies (motor vehicles or non-motor vehicles). <br /><br />The <code>MOTORS_VEHICLES</code> category type is not valid for return policies. eBay flows do not support the return of motor vehicles. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:CategoryTypeEnum'>eBay API documentation</a>"
          }
        }
      }
    },
    "description": {
      "type": "string",
      "description": "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. <br/><br/><b>Max length</b>: 250"
    },
    "extendedHolidayReturnsOffered": {
      "type": "boolean",
      "description": "<p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> This field is deprecated, since eBay no longer supports extended holiday returns. This field should no longer be returned.</p> "
    },
    "internationalOverride": {
      "type": "object",
      "description": "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.",
      "properties": {
        "returnMethod": {
          "type": "string",
          "description": "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. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnMethodEnum'>eBay API documentation</a>"
        },
        "returnPeriod": {
          "type": "object",
          "description": "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.  <br/><br/>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 <a href=\"/api-docs/sell/metadata/resources/marketplace/methods/getReturnPolicies\">getReturnPolicies</a> method of the <b>Metadata API</b>. <br/><br/>The <b>TimeDuration</b> type is used to set/indicate the return period, and you set the <b>unit</b> value to <code>DAY</code> and the <b>value</b> field to either <code>30</code> or <code>60</code> (or other value, as appropriate).  <br/><br/>Note that this value cannot be modified if the listing has bids or sales, or if the listing ends within 12 hours.  <br/><br/>This field is conditionally required if the <b>internationalOverride.returnsAccepted</b> field is set to <code>true</code>.",
          "properties": {
            "unit": {
              "type": "string",
              "description": "These enum values represent the time measurement unit, such as <code>DAY</code>. A span of time is defined when you apply the value specified in the <b>value</b> field to the value specified for <b>unit</b>. <br/><br/>See <b>TimeDurationUnitEnum</b> for a complete list of possible time-measurement units. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:TimeDurationUnitEnum'>eBay API documentation</a>"
            },
            "value": {
              "type": "integer",
              "format": "int32",
              "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the <b>unit</b> field."
            }
          }
        },
        "returnShippingCostPayer": {
          "type": "string",
          "description": "This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either <code>BUYER</code> or <code>SELLER</code>.  <br/><br/>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.  <br/><br/>This field is conditionally required if the <b>internationalOverride.returnsAccepted</b> field is set to <code>true</code>. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnShippingCostPayerEnum'>eBay API documentation</a>"
        },
        "returnsAccepted": {
          "type": "boolean",
          "description": "If set to <code>true</code>, the seller accepts international returns. If set to <code>false</code>, the seller does not accept international returns.  <br/><br/>This field is conditionally required if the seller chooses to have a separate international return policy."
        }
      }
    },
    "marketplaceId": {
      "type": "string",
      "description": "The ID of the eBay marketplace to which this return business policy applies. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:MarketplaceIdEnum'>eBay API documentation</a>"
    },
    "name": {
      "type": "string",
      "description": "A seller-defined name for this return business policy. Names must be unique for policies assigned to the same marketplace.<br /><br /><b>Max length:</b> 64"
    },
    "refundMethod": {
      "type": "string",
      "description": "If a seller indicates that they will accept buyer returns, this value will be <code>MONEY_BACK</code>. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:RefundMethodEnum'>eBay API documentation</a>"
    },
    "restockingFeePercentage": {
      "type": "string",
      "description": "<p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> This field is deprecated, since eBay no longer allows sellers to charge a restocking fee for buyer remorse returns.</p>"
    },
    "returnInstructions": {
      "type": "string",
      "description": "This text-based field provides more details on seller-specified return instructions. <p class=\"tablenote\"><span  style=\"color: #dd1e31;\"><b>Important!</b></span> This field is no longer supported on many eBay marketplaces. To see if a marketplace and eBay category does support this field, call <a href=\"/api-docs/sell/metadata/resources/marketplace/methods/getReturnPolicies\">getReturnPolicies</a> method of the <b>Metadata API</b>. Then you will look for the <b>policyDescriptionEnabled</b> field with a value of <code>true</code> for the eBay category.</span></p><br/><b>Max length</b>: 5000 (8000 for DE)"
    },
    "returnMethod": {
      "type": "string",
      "description": "This field will be returned if the seller is willing and able to offer a replacement item as an alternative to 'Money Back'. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnMethodEnum'>eBay API documentation</a>"
    },
    "returnPeriod": {
      "type": "object",
      "description": "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.",
      "properties": {
        "unit": {
          "type": "string",
          "description": "These enum values represent the time measurement unit, such as <code>DAY</code>. A span of time is defined when you apply the value specified in the <b>value</b> field to the value specified for <b>unit</b>. <br/><br/>See <b>TimeDurationUnitEnum</b> for a complete list of possible time-measurement units. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/ba:TimeDurationUnitEnum'>eBay API documentation</a>"
        },
        "value": {
          "type": "integer",
          "format": "int32",
          "description": "An integer that represents an amount of time, as measured by the time-measurement unit specified in the <b>unit</b> field."
        }
      }
    },
    "returnPolicyId": {
      "type": "string",
      "description": "A unique eBay-assigned ID for a return business policy. This ID is generated when the policy is created."
    },
    "returnShippingCostPayer": {
      "type": "string",
      "description": "This field indicates who is responsible for paying for the shipping charges for returned items. The field can be set to either <code>BUYER</code> or <code>SELLER</code>.  <br/><br/>Note that the seller is always responsible for return shipping costs for SNAD-related issues.  <br/><br/>This container will be returned unless the business policy states that the seller does not accept returns. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/account/types/api:ReturnShippingCostPayerEnum'>eBay API documentation</a>"
    },
    "returnsAccepted": {
      "type": "boolean",
      "description": "If set to <code>true</code>, the seller accepts returns. If set to <code>false</code>, this field indicates that the seller does not accept returns."
    },
    "warnings": {
      "type": "array",
      "description": "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.",
      "items": {
        "type": "object",
        "description": "A container that defines the elements of error and warning messages.",
        "properties": {
          "category": {
            "type": "string",
            "description": "The category type for this error or warning. It is a string that can have one of three values:<ul><li><code>Application</code>: 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.</li><li><code>Business</code>: 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.</li><li><code>Request</code>: 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.</li></ul>"
          },
          "domain": {
            "type": "string",
            "description": "Name of the domain ,or primary system, of the service or application where the error occurred."
          },
          "errorId": {
            "type": "integer",
            "format": "int32",
            "description": "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."
          },
          "inputRefIds": {
            "type": "array",
            "description": "Identifies specific request elements associated with the error, if any. inputRefId's response is format specific. For JSON, use <i>JSONPath</i> notation.",
            "items": {
              "type": "string"
            }
          },
          "longMessage": {
            "type": "string",
            "description": "A more detailed explanation of the error than given in the <code>message</code> error field."
          },
          "message": {
            "type": "string",
            "description": "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."
          },
          "outputRefIds": {
            "type": "array",
            "description": "Identifies specific response elements associated with the error, if any. Path format is the same as <code>inputRefId</code>.",
            "items": {
              "type": "string"
            }
          },
          "parameters": {
            "type": "array",
            "description": "This optional list of name/value pairs that contain context-specific <code>ErrorParameter</code> objects, with each item in the list being a parameter (or input field name) that caused an error condition. Each <code>ErrorParameter</code> object consists of two fields, a <code>name</code> and a <code>value</code>.",
            "items": {
              "type": "object",
              "description": "A complex type that indicates a parameter that caused an error and the value of the parameter which caused the error.",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Name of the parameter that caused the error."
                },
                "value": {
                  "type": "string",
                  "description": "The value of the parameter that caused the error."
                }
              }
            }
          },
          "subdomain": {
            "type": "string",
            "description": "If present, indicates the subsystem in which the error occurred."
          }
        }
      }
    }
  }
}