catalog APIv1_beta.3.0

getChangeRequest

GET
/change_request/{change_request_id}
Use this call to retrieve the contents of a catalog change request based on its unique identifier, change_request_id. The change_request_id value was originally generated by the createChangeRequest call, and is returned by the getChangeRequests call in the changeRequests.changeRequestId field.

Input

Resource URI (production)

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request/{change_request_id}

URI parameters

ParameterTypeDescription
change_request_idstringThe unique identifier of the change request being requested. This value was originally generated by the createChangeRequest call, and is returned by the getChangeRequests call in the changeRequests.changeRequestId field.

Occurrence: Required

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.

Output

HTTP response headers

{ /* ChangeRequest */ }
Output container/fieldTypeDescription
changeRequestIdstringThe unique identifier of this change request. This value was originally generated by the createChangeRequest call and returned in the location code of that call's HTTP response header.

Occurrence: Always

changeRequestStatusChangeRequestStatusThe current processing status of this change request. If the value of this field is APPROVED_WITH_MODIFICATIONS, the change request has been approved with one or more modifications applied by eBay. Check the processResolution.corrections response object for details about the modifications. If the value of this field is REJECTED, the change request has been rejected for violating eBay standards or for conflicting with an existing product record. Check the processResolution.violations response object for details about the rejection.

Available values:
  • APPROVED — Upon review, the change request has been approved as submitted.
  • APPROVED_WITH_MODIFICATIONS — Upon review, the change request has been approved with one or more corrections applied by eBay. Check the processResolution.corrections response object for details about the modifications.
  • REJECTED — Upon review, the change request has been rejected for a conflict with an existing catalog product, or for violating eBay standards. Check the processResolution.violations response object for details about the rejection.
  • SUBMITTED — The change request has been submitted and is being processed.
  • UNDER_EXTENDED_REVIEW — After one hour of review, the change request is under extended review by eBay.
  • UNDER_REVIEW — Upon submission/processing, the change request is under review by eBay. This typically takes up to one hour.

Occurrence: Always

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

creationDatestringThe creation date of this change request.

Occurrence: Always

expectedCompletionDatestringeBay's estimate of the completion date of this change request.

Occurrence: Conditional

processResolutionProcessResolutionReturned if the value of changeRequestStatus is one of the following:
  • APPROVED
  • APPROVED_WITH_MODIFICATIONS — Indicates that the product was created or updated by eBay with certain corrections applied to its attributes or aspects.
  • REJECTED — Indicates that the suggested product either conflicts with existing products or violates eBay standards.
This container provides details of conflicting products, corrections required, or violations that were discovered in this change request

Occurrence: Conditional

processResolution.conflictingProductsarray of ConflictingProductContains information about one or more existing products with identifying information that matches or instersects with the suggested product. For each conflicting product, the difference is in the presence or value of one or more product aspects. If the seller accepts the aspects and their values of the conflicting product (such as a color value of scarlet instead of crimson), that product can be adopted by the seller instead of the suggested product.

If the seller does not accept any of the conflicting products as is, you can submit a change request to update one of them, or to create a new product for which identifying information doesn't overlap with an existing product enough to produce a conflict.

Occurrence: Conditional

processResolution.conflictingProducts.conflictCodestringThe eBay assigned identifier of this conflict.

Occurrence: Conditional

processResolution.conflictingProducts.differentiatingAspectsarray of ProductAspectContains information about one or more aspects of the conflicting product, which the seller's change request either duplicates or provides similar values. The seller should either accept the conflicting product's aspects and values and adopt the product as is, or submit a change request to create or update a product that doesn't conflict with an existing product record.

Occurrence: Conditional

processResolution.conflictingProducts.differentiatingAspects.namestringThe name of the product aspect, such as Model Number, Size, or Color.

Occurrence: Conditional

processResolution.conflictingProducts.differentiatingAspects.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

processResolution.conflictingProducts.epidstringThe eBay product ID of the conflicting catalog product.

Occurrence: Conditional

processResolution.conflictingProducts.reasonstringThe reason for this conflict.

Occurrence: Conditional

processResolution.correctionsarray of CorrectionContains information about one or more corrections to this change request that eBay has applied to the new or updated product. Sellers can accept these corrections by adopting the product, which is identified by the epid field.

Occurrence: Conditional

processResolution.corrections.aspectValuesCorrectionAspectValuesReturned only if the value of corrections.productAttribute.attributeName is ASPECT_NAME. Contains the name and values of a product aspect that has been corrected by eBay in this change request.

Occurrence: Conditional

processResolution.corrections.aspectValues.aspectNamestringThe localized name of this product aspect that requires correction, such as Model Number, Size, or Color.

Occurrence: Conditional

processResolution.corrections.aspectValues.valuesarray of CorrectionAspectValueA list of one or more values of this product aspect that must be corrected.

Occurrence: Conditional

processResolution.corrections.aspectValues.values.newValuestringThe aspect's correct value

Occurrence: Conditional

processResolution.corrections.aspectValues.values.valuestringThe aspect's current incorrect value.

Occurrence: Conditional

processResolution.corrections.correctionCodestringThe eBay-assigned identifier of the correction type for this correction.

Occurrence: Conditional

processResolution.corrections.productAttributeCorrectionProductAttributeContains the name of a particular product attribute with an incorrect value, and if the name is not ASPECT_NAME (a product aspect), the incorrect and correct values of the attribute.

For correction information about a product aspect, see the corrections.aspectValues container.

Occurrence: Conditional

processResolution.corrections.productAttribute.attributeNameProductAttributeNameThe name of the product attribute type in the change request which requires correction, such as BRAND, CATEGORY, or TITLE. See the ProductAttributeName type for available values.

Note: If the value of this field is ASPECT_NAME, see corrections.aspectValues for correction information.

Occurrence: Conditional

processResolution.corrections.productAttribute.newValuestringNot returned if the value of attributeName is ASPECT_NAME (see instead corrections.aspectValues). This is the named attribute's correct value.

Occurrence: Conditional

processResolution.corrections.productAttribute.valuestringNot returned if the value of attributeName is ASPECT_NAME (see instead corrections.aspectValues). This is the named attribute's current incorrect value.

Occurrence: Conditional

processResolution.corrections.reasonstringThe reason why this correction is required.

Occurrence: Conditional

processResolution.epidstringReturned only if the value of changeRequestStatus is APPROVED or APPROVED_WITH_MODIFICATIONS; this is the eBay identifier of the resulting product.

Occurrence: Conditional

processResolution.productHrefstringThe URI of the getProduct call request that retrieves this product's details.

This field is returned under one of the following conditions:
  • The value of changeRequestType is PRODUCT_UPDATE.
  • The value of changeRequestType is PRODUCT_CREATION, and the value of changeRequestStatus is APPROVED or APPROVED_WITH_MODIFICATIONS.

Occurrence: Conditional

processResolution.violationsarray of ViolationContains information about one or more violations in the values of the suggested product's aspects or fixed attributes.

Occurrence: Conditional

processResolution.violations.aspectsValuesViolationAspectValuesReturned only if the value of productAttribute.name is ASPECT_NAME. Contains the name of a product aspect that is in violation of eBay standards in this change request, along with its values that produced the violation.

Occurrence: Conditional

processResolution.violations.aspectsValues.aspectNamestringThe localized name of this product aspect that's in violation, such as Model Number, Size, or Color.

Occurrence: Conditional

processResolution.violations.aspectsValues.valuesarray of stringA list of one or more values of this product aspect that are in violation of eBay standards.

Occurrence: Conditional

processResolution.violations.productAttributeViolationProductAttributeContains the name of a particular product attribute with a value in violation of eBay standards, and if the name is not ASPECT_NAME (a product aspect), the value of the attribute that's in violation of eBay standards.

Occurrence: Conditional

processResolution.violations.productAttribute.nameProductAttributeNameThe name of the product attribute type in the change request which is in violation, such as BRAND, CATEGORY, or TITLE. See the ProductAttributeName type for available values.

Note: If the value of this field is ASPECT_NAME, see violations.aspectsValues for violation information.

Occurrence: Conditional

processResolution.violations.productAttribute.valuesarray of stringNot returned if the value of name is ASPECT_NAME (see instead violations.aspectsValues). This is a list of the named attribute's values that are in violation.

Occurrence: Conditional

processResolution.violations.reasonstringAn explanation of the reason for this violation.

Occurrence: Conditional

processResolution.violations.violationCodestringThe eBay-assigned identifier of the violation type of this violation.

Occurrence: Conditional

processStatusMessagestringA text description and explanation of the status indicated by the changeRequestStatus field.

Occurrence: Always

reasonForChangeRequeststringA text description of why this change request was submitted.

Occurrence: Always

referenceIdstringReturned if the referenceType field is returned in the response. 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

referenceTypeReferenceTypeReturned if this field was included in the the createChangeRequest call. This specifies the type of eBay object that the seller wants to create or update using the requested change. It 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: Conditional

resolutionDatestringReturned if the value of changeRequestStatus is APPROVED, APPROVED_WITH_MODIFICATIONS, or REJECTED. This is the date that the change request was resolved.

Occurrence: Conditional

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

Occurrence: Always

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

suggestedProduct.aspectsarray of ProductAspectContains one or more category aspects and their values that are associated with the suggested product.

Occurrence: Conditional

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

Occurrence: Conditional

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

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

suggestedProduct.eanarray of stringA list of all European Article Numbers (EANs) that identify the suggested product.

Occurrence: Conditional

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

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

Occurrence: Conditional

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

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

suggestedProduct.titlestringThe catalog title that will be used as the listing title for all item listings based on the suggested product.

Occurrence: Conditional

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

Occurrence: Conditional

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: 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
200Success
403Forbidden
404Not Found
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} .
75015API_CATALOGREQUESTInsufficient permissions to fulfill the request.
75150API_CATALOGREQUESTThe specified change request ID was not found.

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 Change Request Details

This sample returns the details of the specified catalog change request by passing in the ID of the change request. This value was originally generated by the createChangeRequest call, and is returned by the getChangeRequests call in the changeRequests.changeRequestId field.

Input

The input is the change_request_id URI parameter, which specifies the ID of the change request. There is no payload with this request.
GET
https://api.ebay.com/commerce/catalog/v1_beta/change_request/5ac3cf22ca4c591b0c324749

Output

The details are returned for the change request with ID 5ac3cf22ca4c591b0c324749, which is a product update request that was just submitted.