catalog APIv1_beta.3.0

getChangeRequests

GET
/change_request
Use this call to search for and retrieve one or more catalog change requests that were submitted by the authenticated user based on their creation date, processing status, reference type or reference ID.

Input

Resource URI (production)

GET https://api.ebay.com/commerce/catalog/v1_beta/change_request?

URI parameters

ParameterTypeDescription
offsetstringThe first change request to return based on its position in the returned collection of change requests. Use this parameter in conjunction with the limit parameter to control the pagination of the output.

For example, if offset is set to 10 and limit is set to 10, the call retrieves change requests 11 thru 20 from the resulting collection of change requests.

Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.

Default: 0 (zero)

Occurrence: Optional

limitstringThe number of change requests to return. This is the result set, a subset of the full collection of change requests that match the filter criteria of this call.

Maximum: 200
Default: 50

Occurrence: Optional

filterarray of FilterFieldOne or more comma-separated criteria for narrowing down the collection of change requests returned by this call. These criteria correspond to specific fields in the response payload. Multiple filter criteria combine to further restrict the results.

The available criteria are as follows:
creationDate
The time period during which qualifying change requests were created (the changeRequests.creationDate field). In the URI, this is expressed as a starting timestamp, with or without an ending timestamp (in brackets). The timestamps are in ISO 8601 format, which uses the 24-hour Universal Coordinated Time (UTC) clock. For example:
  • creationDate:[2016-02-21T08:25:43.511Z..] identifies orders created on or after the given timestamp.
  • creationDate:[2016-02-21T08:25:43.511Z..2016-04-21T08:25:43.511Z] identifies orders created between the given timestamps, inclusive.
changeRequestStatuses
The degree to which qualifying change requests have been resolved (the changeRequests.changeRequestStatus field). For example:
  • changeRequestStatuses:{SUBMITTED} specifies change requests that have been submitted and are being processed.
  • changeRequestStatuses:{UNDER_REVIEW|APPROVED_WITH_MODIFICATIONS} specifies change requests that are being reviewed by eBay, and change requests that have been approved, but eBay has made some modifications such as correcting typographic errors.
  • changeRequestStatuses:{REJECTED} specifies change requests that have been rejected by eBay because of a violation.
referenceId
The identifier of an object of the type specified by the value of the referenceType parameter. For example, if the value of referenceType is INVENTORY_ITEM, this field should contain the seller's SKU for an inventory item. If you include this without the referenceType parameter, the filter will apply to objects of any reference type with this reference ID, if specified in the change request. This parameter can take multiple values.

For example:

referenceId:{234242|675756}

referenceType
The type of object that a requested catalog change is intended to support, if specified in the change request (the changeRequests.referenceType field). For example:
  • referenceType:{INVENTORY_ITEM} indicates that the requested change will support the completion of an inventory item, which you can then use to create an offer.
  • referenceType:{LISTING} indicates that the requested change will support the modification of an active product listing.
  • referenceType:{LISTING_DRAFT} indicates that the requested change will support the completion of an offer, which you can then publish as a product listing.

Occurrence: Optional

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

{ /* GetChangeRequestsResponse */
"changeRequests" : [
{ /* ChangeRequest */ }
],
"href" : "string",
"limit" : "integer",
"next" : "string",
"prev" : "string",
}
Output container/fieldTypeDescription
changeRequestsarray of ChangeRequestContains the full details of one or more catalog change requests, including the original payload of the createChangeRequest call, processing status and key dates, and resolution details.

Occurrence: Conditional

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

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

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

changeRequests.creationDatestringThe creation date of this change request.

Occurrence: Always

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

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

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

Occurrence: Conditional

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

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

Occurrence: Conditional

changeRequests.processResolution.conflictingProducts.reasonstringThe reason for this conflict.

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Conditional

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

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

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

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

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

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

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

Occurrence: Conditional

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

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

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

Occurrence: Always

changeRequests.reasonForChangeRequeststringA text description of why this change request was submitted.

Occurrence: Always

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

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

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

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

Occurrence: Always

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

changeRequests.suggestedProduct.brandstringThe manufacturer's brand name for the suggested product.

Occurrence: Conditional

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

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

Occurrence: Conditional

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

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

changeRequests.suggestedProduct.isbnarray of stringA list of all International Standard Book Numbers (ISBNs) that identify the suggested product.

Occurrence: Conditional

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

Occurrence: Conditional

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

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

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

Occurrence: Conditional

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

Occurrence: Conditional

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

hrefstringThe URI of the getChangeRequests call request that produced this page of results.

Occurrence: Conditional

limitintegerThe maximum number of change requests in this page, a subset of the full collection of change requests that match the filter criteria of this call. This field combines with the offset field to identify the change requests being returned.

Occurrence: Conditional

nextstringThe getChangeRequests call URI for the next page. For example, the following URI returns records 41 thru 50 from the collection of change requests:

path/change_request?limit=10&offset=40

Note: This feature employs a zero-based list, where the first order in the list has an offset of 0.

Occurrence: Conditional

offsetintegerThe first change request in this page based on its position in the returned collection of change requests.

For example, if offset is set to 10 and limit is set to 10, this page includes change requests 11 thru 20 from the resulting collection of change requests.

Note: This feature employs a zero-based list, where the first item in the list has an offset of 0.

Occurrence: Conditional

prevstringThe getChangeRequests call URI for the previous page. For example, the following URI returns orders 21 thru 30 from the collection of orders:

path/change_request?limit=10&offset=20

Note: This feature employs a zero-based list, where the first order in the list has an offset of 0.

Occurrence: Conditional

totalintegerThe total number of change requests in the collection.

Note: If no change requests are found, this field is returned with a value of 0.

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
204No Content
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.
75002API_CATALOGREQUESTThe 'offset' value cannot be negative.
75004API_CATALOGREQUESTThe 'limit' value should be between 1 and 200 (inclusive).
75007API_CATALOGREQUESTCurrently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} .
75015API_CATALOGREQUESTInsufficient permissions to fulfill the request.
75151API_CATALOGREQUESTThe filter {filterName} is invalid. For more information, see the API call reference documentation.

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 Details of All Change Requests for a User

This sample searches for and retrieves all the catalog change requests that were submitted by the authenticated user.

Input

There are no URI parameters or payload with this sample.
GET
https://api.ebay.com/commerce/catalog/v1_beta/change_request?

Output

If the call is successful, all the catalog change requests that were submitted by the authenticated user are returned. Note: This call is supported only in the eBay SandBox environment (https://api.sandbox.ebay.com) and the response below is mock data.