catalog APIv1_beta.3.0

createChangeRequest

POST

/change_request

When sellers are unable to identify an eBay catalog product on which to base their item listing, this call enables you to request that eBay update an existing product record or create a new product record that will successfully match the seller's inventory item.

Input

Resource URI (production)

POST https://api.ebay.com/commerce/catalog/v1_beta/change_request

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.

This call also uses the X-EBAY-C-MARKETPLACE-ID header to identify the user's business context. This header is currently limited to EBAY-US, EBAY-AU, EBAY-CA, and EBAY-GB values. If not included with your request, the marketplace value defaults to EBAY-US. Note that it does not indicate a language preference or end-user location.

Examples:
X-EBAY-C-MARKETPLACE-ID: EBAY-US
X-EBAY-C-MARKETPLACE-ID: EBAY-AU

This method has the additional request header requirements listed below. See HTTP request headers - opens rest request components page for details.

Header Type Description

Header	Type	Description
Accept-Language	string	Use this header to specify the natural language in which the authenticated user desires the response. Occurrence: Strongly Recommended
X-EBAY-C-MARKETPLACE-ID	string	Use this header to identify the authenticated user's business context. This header is currently limited to `EBAY_US`, `EBAY_AU`, `EBAY_CA`, and `EBAY_GB` values. If not included with your request, the marketplace value defaults to `EBAY_US`. Note that it does not indicate a language preference or end-user location. Occurrence: Required

Accept-Language

string

Use this header to specify the natural language in which the authenticated user desires the response.

Occurrence: Strongly Recommended

X-EBAY-C-MARKETPLACE-ID

string

Use this header to identify the authenticated user's business context. This header is currently limited to EBAY_US, EBAY_AU, EBAY_CA, and EBAY_GB values. If not included with your request, the marketplace value defaults to EBAY_US. Note that it does not indicate a language preference or end-user location.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one scope from the following list:

https://api.ebay.com/oauth/api_scope/sell.inventory

See OAuth access tokens for more information.

Note: Only the sell.inventory scope is required for selling applications, and only the commerce.catalog.readonly scope is required for buying applications.

Request payload

Copy complete valid JSON to Clipboard

{ /* CreateChangeRequestPayload */

"changeRequestType" : "ChangeRequestType : [PRODUCT_CREATION,PRODUCT_UPDATE]",

"reasonForChangeRequest" : "string",

"referenceId" : "string",

"referenceType" : "ReferenceType : [INVENTORY_ITEM,LISTING,LISTING_DRAFT]",

"suggestedProduct" :

{ /* SuggestedProduct */

"additionalImageUrls" : [

"string"

"aspects" : [

{ /* ProductAspect */

"name" : "string",

"values" : [

"string"

]

}

"brand" : "string",

"description" : "string",

"ean" : [

"string"

"epid" : "string",

"imageUrl" : "string",

"isbn" : [

"string"

"mpn" : [

"string"

"otherApplicableCategoryIds" : [

"string"

"primaryCategoryId" : "string",

"title" : "string",

"upc" : [

"string"

"version" : "string"

}

Request fields

Input container/field	Type	Description
changeRequestType	ChangeRequestType	The type of catalog modification being requested by this change request. Available values: `PRODUCT_CREATION` — Change request to create a new product `PRODUCT_UPDATE` — Change request to update an existing product Occurrence: Required
reasonForChangeRequest	string	Required if the value of changeRequestType is `PRODUCT_UPDATE`, and optional otherwise; this is a text description of why this change is being requested. Occurrence: Conditional
referenceId	string	Required if the referenceType field is included in the request. This is the identifier of an object of the type specified by the value of referenceType. For example, if the value of referenceType is `INVENTORY_ITEM`, this field should contain the seller's SKU for an inventory item. Occurrence: Conditional
referenceType	ReferenceType	The type of object that the requested change is intended to support. This applies to objects that are incomplete due to the need for a matching catalog product. Providing a referenceType and a referenceId in a catalog change request enables eBay to automatically apply the resulting new or updated product directly to the specified object without requiring additional action on your part. Available values: `INVENTORY_ITEM` — The requested change will support the completion of an inventory item, which you can then use to create an offer. `LISTING` — The requested change will support the modification of an active product listing. `LISTING_DRAFT` — The requested change will support the completion of an offer, which you can then publish as a product listing. Occurrence: Optional
suggestedProduct	SuggestedProduct	Contains the full details of the suggested product, including information about the product's identifiers, description, product images, categories, and aspects. Occurrence: Required
suggestedProduct.additionalImageUrls	array of string	A list of URLs for additional images associated with the suggested product. For the URL of the primary image, see the imageUrl field. Occurrence: Optional
suggestedProduct.aspects	array of ProductAspect	Contains one or more category aspects and their values that are associated with the suggested product. Occurrence: Optional
suggestedProduct.aspects.name	string	The name of the product aspect, such as `Model Number`, `Size`, or `Color`. Occurrence: Optional
suggestedProduct.aspects.values	array of string	Required or returned if a value is provided for the name field. This is a list of one or more localized values of this product aspect. Occurrence: Conditional
suggestedProduct.brand	string	The manufacturer's brand name for the suggested product. Occurrence: Optional
suggestedProduct.description	string	A rich description of the suggested product, which can contain HTML, including the following basic tags: Text formatting tags such as `<b>`, `<i>`, `<br>`, `<ol>`, `<ul>`, and `<li>` Table formatting tags such as `<table>`, `<tr>`, `<td>`, `<th>`, `<thead>`, `<tfoot>`, `<tbody>`, `<caption>`, `<col>`, and `<colgroup>` Note: Active content from sellers is prohibited on eBay, including animation or video via JavaScript, Flash, plug-ins, or form actions. Occurrence: Optional
suggestedProduct.ean	array of string	A list of all European Article Numbers (EANs) that identify the suggested product. Occurrence: Optional
suggestedProduct.epid	string	Required or returned only if the value of the changeRequestType field is `PRODUCT_UPDATE`. This is the eBay product ID of the product record for which an update is being suggested. Occurrence: Conditional
suggestedProduct.imageUrl	string	Required or returned if the value of the changeRequestType field is `PRODUCT_CREATION`. This is the URL of the primary image associated with the suggested product. Occurrence: Conditional
suggestedProduct.isbn	array of string	A list of all International Standard Book Numbers (ISBNs) that identify the suggested product. Occurrence: Optional
suggestedProduct.mpn	array of string	A list of all Manufacturer Product Number (MPN) values that the manufacturer uses to identify the suggested product. Occurrence: Optional
suggestedProduct.otherApplicableCategoryIds	array of string	A list of category IDs (other than the value of primaryCategoryId) for all the leaf categories to which the suggested product might belong. Occurrence: Optional
suggestedProduct.primaryCategoryId	string	The identifier of the category that eBay recommends using to list the suggested product, based on previous listings of similar products. Products in the eBay catalog are not automatically associated with any particular category, but using an inappropriate category can make it difficult for prospective buyers to find the product. For other possible categories that might be used, see otherApplicableCategoryIds. Occurrence: Required
suggestedProduct.title	string	The catalog title that will be used as the listing title for all item listings based on the suggested product. Occurrence: Required
suggestedProduct.upc	array of string	A list of all Universal Product Codes (UPCs) that identify the suggested product. Occurrence: Optional
suggestedProduct.version	string	Required or returned only if the value of changeRequestType is `PRODUCT_UPDATE`. This is the current version number in the catalog of the product record for which an update is being suggested. Occurrence: Optional

Output

HTTP response headers

See HTTP response headers for details.

Header	Meaning
Location	A successful call returns the following location code in the HTTP header: `{ENV}/commerce/catalog/v1_beta/change_request/{REQUESTID}` The ENV string is the HTTPS path to the same eBay supported environment in which this call was issued. The REQUESTID parameter identifies the newly created change request. Use this getChangeRequest URI to retrieve the contents of the new change request.

Response payload

This call has no payload.

Response fields

This call has no field definitions.

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
202	Accepted
400	Bad Request
403	Forbidden
500	Internal Server Error

Error codes

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

Code	Domain	Category	Meaning
75000	API_CATALOG	APPLICATION	There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
75007	API_CATALOG	REQUEST	Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
75008	API_CATALOG	REQUEST	Primary Category Id {primaryCategoryId} should not be repeated in Other Applicable Category Ids. For more information, see the API call reference documentation.
75015	API_CATALOG	REQUEST	Insufficient permissions to fulfill the request.
75152	API_CATALOG	REQUEST	The field {fieldName} is invalid. For more information, see the API call reference documentation.
75153	API_CATALOG	REQUEST	The field {fieldName} is missing. For more information, see the API call reference documentation.
75154	API_CATALOG	REQUEST	The field {fieldName} is not required for product creation. For more information, see the API call reference documentation.
75155	API_CATALOG	REQUEST	Aspect values are missing. For more information, see the API call reference documentation.
75156	API_CATALOG	REQUEST	The {fieldName} field exceeds limit of characters allowed ({characterLengthLimit}).
75157	API_CATALOG	REQUEST	Change Request is not supported for the product at this moment.
75158	API_CATALOG	REQUEST	The {fieldName} has invalid image extension. Possible extensions: {possibleExtensions}
75159	API_CATALOG	REQUEST	Invalid size of {fieldName} collection. Maximum allowed size is: {maxSize}

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: Create a Change Request

This sample creates a new change request to update the record of the catalog product with the ePID value 114795376.

Input

The update being suggested includes any field in the request payload with a value that differs from the current catalog record for the product.

POST

http://api.ebay.com/commerce/catalog/v1_beta/change_request

{
   "changeRequestType":"PRODUCT_UPDATE",
   "referenceId":"123",
   "suggestedProduct":{
      "epid":"114795376",
      "version": "1048481621",
      "title":"Apple iPhone 6 Plus - 128GB - Gold (Tbaytel) Smartphone",
      "description":"This Apple 6 Plus runs on iOS operating system and offers useful features",
      "primaryCategoryId":"9355",
      "aspects":[
         {
            "name":"Features",
            "values":[
               "3G Data Capable",
               "4G Data Capable"
            ]
         }
      ],
      "imageUrl":"https://i.ebayimg.com/00/s/NDczWDMyNQ==/z/-6IAAOSwY45UPAWE/$_6.JPG?set_id=89040003C1",
      "brand":"Apple",
      "upc":[
         "08859er09600199",
         "0745577656433"
      ],
      "ean":[
         "0885909420452",
         "0885909530199"
      ],
      "isbn":[
         "5909530199",
         "8888654321"
      ],
      "mpn":[
         "MD295LL/A",
         "MD295LL/B"
      ],
      "otherApplicableCategoryIds":[
         "93154",
         "22211"
      ],
      "additionalImageUrls":[
         "https://i.ebayimg.com/00/s/OTc0WDY1Nw==/z/yfEAAOSwEK9UKrlH/$_6.JPG?set_id=89040003C1",
         "https://i.ebayimg.com/00/s/MTAwMlg3MTA=/z/KRIAAOSwDk5UKrlJ/$_6.JPG?set_id=89040003C1"
      ]
   },
   "reasonForChangeRequest":"Reason to change the request"
}

Output

A successful call returns the following location code in the HTTP header:

http://api.ebay.com/commerce/catalog/v1_beta/change_request/5ac7a780ca4c591b0c3248fe

This location code is a getChangeRequest URI that retrieves the newly created change request. There is no payload with this response.