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

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

HeaderTypeDescription
Accept-LanguagestringUse this header to specify the natural language in which the authenticated user desires the response.

Occurrence: Strongly Recommended

X-EBAY-C-MARKETPLACE-IDstringUse 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.

Input container/fieldTypeDescription
changeRequestTypeChangeRequestTypeThe 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

reasonForChangeRequeststringRequired 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

referenceIdstringRequired 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

referenceTypeReferenceTypeThe 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

suggestedProductSuggestedProductContains the full details of the suggested product, including information about the product's identifiers, description, product images, categories, and aspects.

Occurrence: Required

suggestedProduct.additionalImageUrlsarray of stringA 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.aspectsarray of ProductAspectContains one or more category aspects and their values that are associated with the suggested product.

Occurrence: Optional

suggestedProduct.aspects.namestringThe name of the product aspect, such as Model Number, Size, or Color.

Occurrence: Optional

suggestedProduct.aspects.valuesarray of stringRequired 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.brandstringThe manufacturer's brand name for the suggested product.

Occurrence: Optional

suggestedProduct.descriptionstringA 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.eanarray of stringA list of all European Article Numbers (EANs) that identify the suggested product.

Occurrence: Optional

suggestedProduct.epidstringRequired 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.imageUrlstringRequired 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.isbnarray of stringA list of all International Standard Book Numbers (ISBNs) that identify the suggested product.

Occurrence: Optional

suggestedProduct.mpnarray of stringA list of all Manufacturer Product Number (MPN) values that the manufacturer uses to identify the suggested product.

Occurrence: Optional

suggestedProduct.otherApplicableCategoryIdsarray of stringA 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.primaryCategoryIdstringThe 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.titlestringThe catalog title that will be used as the listing title for all item listings based on the suggested product.

Occurrence: Required

suggestedProduct.upcarray of stringA list of all Universal Product Codes (UPCs) that identify the suggested product.

Occurrence: Optional

suggestedProduct.versionstringRequired 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.

HeaderMeaning
LocationA 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.

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

Error codes

CodeDomainCategoryMeaning
75000API_CATALOGAPPLICATIONThere was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
75007API_CATALOGREQUESTCurrently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
75008API_CATALOGREQUESTPrimary Category Id {primaryCategoryId} should not be repeated in Other Applicable Category Ids. For more information, see the API call reference documentation.
75015API_CATALOGREQUESTInsufficient permissions to fulfill the request.
75152API_CATALOGREQUESTThe field {fieldName} is invalid. For more information, see the API call reference documentation.
75153API_CATALOGREQUESTThe field {fieldName} is missing. For more information, see the API call reference documentation.
75154API_CATALOGREQUESTThe field {fieldName} is not required for product creation. For more information, see the API call reference documentation.
75155API_CATALOGREQUESTAspect values are missing. For more information, see the API call reference documentation.
75156API_CATALOGREQUESTThe {fieldName} field exceeds limit of characters allowed ({characterLengthLimit}).
75157API_CATALOGREQUESTChange Request is not supported for the product at this moment.
75158API_CATALOGREQUESTThe {fieldName} has invalid image extension. Possible extensions: {possibleExtensions}
75159API_CATALOGREQUESTInvalid 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

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.