{
"openapi": "3.0.0",
"info": {
"title": "Catalog API",
"description": "Use the Catalog API to search the eBay catalog for products on which to base a seller's item listing; to retrieve a product record by its eBay product identifier (ePID); to submit a catalog change request to modify an existing product or create a new product; and to manage catalog change requests.",
"contact": {
"name": "eBay Inc,"
},
"license": {
"name": "eBay API License Agreement",
"url": "https://go.developer.ebay.com/api-license-agreement"
},
"version": "v1_beta.3.1"
},
"servers": [
{
"url": "https://api.ebay.com{basePath}",
"description": "Production",
"variables": {
"basePath": {
"default": "/commerce/catalog/v1_beta"
}
}
}
],
"paths": {
"/change_request/{change_request_id}": {
"get": {
"tags": [
"change_request"
],
"description": "Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. Currently, this method may still return data for a valid change request ID, but the data will be static, the status will not change, and it will not be possible to make any changes to the change request. At any time, it is possible that all catalog change requests for a user will be removed, and then this method will just trigger this error: The specified change request ID was not found. (error code 75150). 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.",
"operationId": "getChangeRequest",
"deprecated": true,
"parameters": [
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "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.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Language",
"in": "header",
"description": "Use this header to specify the natural language in which the authenticated user desires the response.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "change_request_id",
"in": "path",
"description": "The 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.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChangeRequest"
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} ."
},
"75015": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Insufficient permissions to fulfill the request."
},
"75150": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified change request ID was not found."
}
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory"
]
}
]
}
},
"/change_request": {
"get": {
"tags": [
"change_request"
],
"description": "Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. Currently, this method may still return existing change requests for a user, but the data will be static, the statuses will not change, and it will not be possible to make any changes to any of the change requests. At any time, it is possible that all catalog change requests for a user will be removed, and then this method will just return an empty changeRequests array. 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.",
"operationId": "getChangeRequests",
"deprecated": true,
"parameters": [
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "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.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Language",
"in": "header",
"description": "Use this header to specify the natural language in which the authenticated user desires the response.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "filter",
"in": "query",
"description": "One 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. changeRequestStatus The degree to which qualifying change requests have been resolved (the changeRequests.changeRequestStatus field). For example: changeRequestStatus:{SUBMITTED} specifies change requests that have been submitted and are being processed. changeRequestStatus:{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. changeRequestStatus:{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. For implementation help, refer to eBay API documentation at https://developer.ebay.com/devzone/rest/api-ref/catalog/types/FilterField.html",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "The 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",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "The 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)",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GetChangeRequestsResponse"
}
}
}
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75002": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The 'offset' value cannot be negative."
},
"75004": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The 'limit' value should be between 1 and 200 (inclusive)."
},
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} ."
},
"75015": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Insufficient permissions to fulfill the request."
},
"75151": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The filter {filterName} is invalid. For more information, see the API call reference documentation."
}
}
}
},
"403": {
"description": "Forbidden"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory"
]
}
]
},
"post": {
"tags": [
"change_request"
],
"description": "Note: The three catalog change request methods in the Catalog API are deprecated, and are scheduled to be decommissioned in Q1 of 2020. This method is no longer supported for any eBay categories and will return this error if used: Change Request is not supported for this product at this moment. (error code 75157) 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.",
"operationId": "createChangeRequest",
"deprecated": true,
"parameters": [
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "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.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "Accept-Language",
"in": "header",
"description": "Use this header to specify the natural language in which the authenticated user desires the response.",
"required": false,
"schema": {
"type": "string"
}
}
],
"requestBody": {
"description": "Contains the full details of a specified catalog change request, including the type of request, the reason for a product update request, and the details of the new or updated product being suggested.",
"content": {
"application/json": {
"schema": {
"description": "Contains the full details of a specified catalog change request, including the type of request, the reason for a product update request, and the details of the new or updated product being suggested.",
"$ref": "#/components/schemas/CreateChangeRequestPayload"
}
}
},
"required": false
},
"responses": {
"202": {
"description": "Accepted"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} ."
},
"75008": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Primary Category Id {primaryCategoryId} should not be repeated in Other Applicable Category Ids. For more information, see the API call reference documentation."
},
"75015": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Insufficient permissions to fulfill the request."
},
"75152": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The field {fieldName} is invalid. For more information, see the API call reference documentation."
},
"75153": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The field {fieldName} is missing. For more information, see the API call reference documentation."
},
"75154": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The field {fieldName} is not required for product creation. For more information, see the API call reference documentation."
},
"75155": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Aspect values are missing. For more information, see the API call reference documentation."
},
"75156": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Length of 'reasonForChangeRequest' should not exceed 250 characters."
},
"75157": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Change Request is not supported for the product at this moment."
}
}
}
},
"403": {
"description": "Forbidden"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory"
]
}
]
}
},
"/product/{epid}": {
"get": {
"tags": [
"product"
],
"description": "This call retrieves details of the catalog product identified by the eBay product identifier (ePID) specified in the request. These details include the product's title and description, aspects and their values, associated images, applicable category IDs, and any recognized identifiers that apply to the product. For a new listing, you can use the search call to identify candidate products on which to base the listing, then use the getProduct call to present the full details of those candidate products to the seller to makea a final selection.",
"operationId": "getProduct",
"parameters": [
{
"name": "epid",
"in": "path",
"description": "The ePID of the product being requested. This value can be discovered by issuing the search call and examining the value of the productSummaries.epid field for the desired returned product summary.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Product"
}
}
}
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces}."
},
"75010": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified EPID value {epid} was not found."
},
"75011": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified EPID value {epid} no longer exists. Its new value is {newepid}."
},
"75015": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Insufficient permissions to fulfill the request."
},
"75016": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified EPID value {epid} is no longer available."
}
}
}
},
"403": {
"description": "Forbidden"
},
"404": {
"description": "Not Found"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory",
"https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly"
]
}
]
}
},
"/product_summary/search": {
"get": {
"tags": [
"product_summary"
],
"description": "This call searches for and retrieves summaries of one or more products in the eBay catalog that match the search criteria provided by a seller. The seller can use the summaries to select the product in the eBay catalog that corresponds to the item that the seller wants to offer for sale. When a corresponding product is found and adopted by the seller, eBay will use the product information to populate the item listing. The criteria supported by search include keywords, product categories, and category aspects. To see the full details of a selected product, use the getProduct call. In addition to product summaries, this call can also be used to identify refinements, which help you to better pinpoint the product you're looking for. A refinement consists of one or more aspect values and a count of the number of times that each value has been used in previous eBay listings. An aspect is a property (e.g. color or size) of an eBay category, used by sellers to provide details about the items they're listing. The refinement container is returned when you include the fieldGroups query parameter in the request with a value of ASPECT_REFINEMENTS or FULL. Example A seller wants to find a product that is "gray" in color, but doesn't know what term the manufacturer uses for that color. It might be Silver, Brushed Nickel, Pewter, or even Grey. The returned refinement container identifies all aspects that have been used in past listings for products that match your search criteria, along with all of the values those aspects have taken, and the number of times each value was used. You can use this data to present the seller with a histogram of the values of each aspect. The seller can see which color values have been used in the past, and how frequently they have been used, and selects the most likely value or values for their product. You issue the search call again with those values in the aspect_filter parameter to narrow down the collection of products returned by the call. Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. If you provide more than one of these parameters, they will be combined with a logical AND to further refine the returned collection of matching products. Note: This call requires that certain special characters in the query parameters be percent-encoded: (space) = %20 , = %2C : = %3A [ = %5B ] = %5D { = %7B | = %7C } = %7D This requirement applies to all query parameter values. However, for readability, call examples and samples in this documentation will not use the encoding. This call returns product summaries rather than the full details of the products. To retrieve the full details of a product, use the getProduct call with an ePID.",
"operationId": "search",
"parameters": [
{
"name": "aspect_filter",
"in": "query",
"description": "An eBay category and one or more aspects of that category, with the values that can be used to narrow down the collection of products returned by this call. Aspects are product attributes that can represent different types of information for different products. Every product has aspects, but different products have different sets of aspects. You can determine appropriate values for the aspects by first submitting this call without this parameter. It will return either the productSummaries.aspects container, the refinement.aspectDistributions container, or both, depending on the value of the fieldgroups parameter in the request. The productSummaries.aspects container provides the category aspects and their values that are associated with each returned product. The refinement.aspectDistributions container provides information about the distribution of values of the set of category aspects associated with the specified categories. In both cases sellers can select from among the returned aspects to use with this parameter. Note: You can also use the Taxonomy API's getItemAspectsForCategory call to retrieve detailed information about aspects and their values that are appropriate for your selected category. The syntax for the aspect_filter parameter is as follows (on several lines for readability; categoryId is required): aspect_filter=categoryId:category_id, aspect1:{valueA|valueB|...}, aspect2:{valueC|valueD|...},... A matching product must be within the specified category, and it must have least one of the values identified for every specified aspect. Note: Aspect names and values are case sensitive. Here is an example of an aspect_filter parameter in which 9355 is the category ID, Color is an aspect of that category, and Black and White are possible values of that aspect (on several lines for readability): GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? aspect_filter=categoryId:9355,Color:{White|Black} Here is the aspect_filter with required URL encoding and a second aspect (on several lines for readability): GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? aspect_filter=categoryId:9355,Color:%7BWhite%7CBlack%7D, Storage%20Capacity:%128GB%7C256GB%7D Note: You cannot use the aspect_filter parameter in the same call with either the gtin parameter or the mpn parameter. For implementation help, refer to eBay API documentation at https://developer.ebay.com/devzone/rest/api-ref/catalog/types/AspectFilter.html",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "category_ids",
"in": "query",
"description": "Important: Currently, only the first category_id value is accepted. One or more comma-separated category identifiers for narrowing down the collection of products returned by this call. Note: This parameter requires a valid category ID value. You can use the Taxonomy API's getCategorySuggestions call to retrieve appropriate category IDs for your product based on keywords. The syntax for this parameter is as follows: category_ids=category_id1,category_id2,... Here is an example of a call with the category_ids parameter: GET https://api.ebay.com/commerce/catalog/v1_beta/product_summary/search? category_ids=178893 Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. If you provide only the category_ids parameter, you cannot specify a top-level (L1) category.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "fieldgroups",
"in": "query",
"description": "The type of information to return in the response. Important: This parameter may not produce valid results if you also provide more than one value for the category_ids parameter. It is recommended that you avoid using this combination. Valid Values: ASPECT_REFINEMENTS — This returns the refinement container, which includes the category aspect and aspect value distributions that apply to the returned products. For example, if you searched for Ford Mustang, some of the category aspects might be Model Year, Exterior Color, Vehicle Mileage, and so on. Note: Aspects are category specific. FULL — This returns all the refinement containers and all the matching products. This value overrides the other values, which will be ignored. MATCHING_PRODUCTS — This returns summaries for all products that match the values you provide for the q and category_ids parameters. This does not affect your use of the ASPECT_REFINEMENTS value, which you can use in the same call. Code so that your app gracefully handles any future changes to this list. Default: MATCHING_PRODUCTS",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "gtin",
"in": "query",
"description": "A string consisting of one or more comma-separated Global Trade Item Numbers (GTINs) that identify products to search for. Currently the GTIN values can include EAN, ISBN, and UPC identifier types. Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. You cannot use the gtin parameter in the same call with either the q parameter or the aspect_filter parameter.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "The number of product summaries to return. This is the result set, a subset of the full collection of products that match the search or filter criteria of this call. Maximum: 200 Default: 50",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "mpn",
"in": "query",
"description": "A string consisting of one or more comma-separated Manufacturer Part Numbers (MPNs) that identify products to search for. This call will return all products that have one of the specified MPNs. MPNs are defined by manufacturers for their own products, and are therefore certain to be unique only within a given brand. However, many MPNs do turn out to be globally unique. Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. You cannot use the mpn parameter in the same call with either the q parameter or the aspect_filter parameter.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "offset",
"in": "query",
"description": "This parameter is reserved for internal or future use.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "q",
"in": "query",
"description": "A string consisting of one or more keywords to use to search for products in the eBay catalog. Note: This call searches the following product record fields: title, description, brand, and aspects.localizedName, which do not include product IDs. Wildcard characters (e.g. *) are not allowed. The keywords are handled as follows: If the keywords are separated by a comma (e.g. iPhone,256GB), the query returns products that have iPhone AND 256GB. If the keywords are separated by a space (e.g. "iPhone ipad" or "iPhone, ipad"), the query ignores any commas and returns products that have iPhone OR iPad. Note: Although all query parameters are optional, this call must include at least the q parameter, or the category_ids, gtin, or mpn parameter with a valid value. You cannot use the q parameter in the same call with either the gtin parameter or the mpn parameter.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductSearchResponse"
}
}
}
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75001": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The call must have a valid 'q', or 'category_ids' or 'gtin' or 'mpn' query parameter."
},
"75004": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The 'limit' value should be between 1 and 200 (inclusive)."
},
"75006": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Top level category browsing is not allowed. Please provide keywords or more filters for the applied top level category."
},
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces} ."
},
"75008": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The 'fieldgroups' value {fieldgroups} is invalid. The supported fieldgroups are: {supportedFieldgroups}"
},
"75012": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The aspect_filter format is invalid. For more information, see the API call reference documentation."
},
"75013": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The 'aspect_filter' query parameter must include a categoryId. For more information, see the API call reference documentation."
},
"75014": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The categoryId in 'aspect_filter' query parameter is invalid. For more information, see the API call reference documentation."
},
"75015": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Insufficient permissions to fulfill the request."
},
"75017": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified GTIN value is invalid."
},
"75018": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The call must be made with either 'q' or 'gtin/mpn'."
},
"75019": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The call with 'gtin/mpn' cannot be made with aspect_filter."
}
}
}
},
"403": {
"description": "Forbidden"
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory",
"https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly"
]
}
]
}
},
"/get_product_metadata": {
"get": {
"tags": [
"product_metadata"
],
"description": "This call retrieves an array of all supported aspects, aspect constraints, and aspect values for the specified catalog product and its associated or suggested categories, as well as the values currently associated with that product. The array is a union (with duplicates removed) of all returned aspects. After using the search and getProduct calls to find a catalog product that matches a seller's inventory item, you may discover a matching product, but determine that one or more product details are missing or inaccurate. You can propose updates to the product's aspects and aspect values for the catalog by taking the following steps: Use the Taxonomy API's category_tree calls to discover the appropriate category or categories for the seller's inventory item. See Finding categories for a listing or promotion. Use getProductMetadata to determine the aspects of your selected categories and the values of those aspects that should be added to the aspects and values already associated with your product. Use the createChangeRequest call to to submit a change request to update the product in the eBay catalog for your seller's marketplace. Note: The X-EBAY-C-MARKETPLACE-ID request header is required to identify the user's business context. The eBay Product Identifier (ePID) for a catalog product is also required and is specified through the epid query parameter.",
"operationId": "getProductMetadata",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "This request header sets the natural language that will be provided in the field values of the response payload. Supported values for this header can be found in the Marketplace ID and language header values table.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "epid",
"in": "query",
"description": "The unique eBay product identifier of the catalog product that you want to update. The supported and applied aspects, constraints, and values for this eBay catalog product are returned.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "other_applicable_category_ids",
"in": "query",
"description": "Use only if you are also including the primary_category_id parameter in the request. Provide one or more comma-separated category IDs in this parameter. Sellers can use other_applicable_category_ids to retrieve information about the specified categories' associated aspects, constraints, and values, along with the same information for the category specified in the primary_category_id parameter, for the seller to assess, select, and populate for submission with the createChangeRequest call. eBay category IDs are returned by the Taxonomy API's category_tree calls.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "primary_category_id",
"in": "query",
"description": "Use only if the seller believes this product is associated with the wrong primary category. Use this parameter to submit the unique identifier of the primary category that the seller wants to use instead. This call retrieves information about the specified category's associated aspects, constraints, and values for the seller to assess, select, and populate for submission with the Catalog API's createChangeRequest call. If you exclude this parameter from your request, this call retrieves information about the aspects, constraints, and values of the specified product's current primary category and other applicable categories. If you include this parameter in your request, this call does not return any information about the specified product's current primary or other applicable categories, but only about the specified category. To retrieve information about any other categories, you must specify them with the other_applicable_category_ids parameter. eBay category IDs are returned by the Taxonomy API's category_tree calls.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "Use this header to specify the eBay marketplace identifier. Supported values for this header can be found in the MarketplaceIdEnum type definition.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductMetadata"
}
}
}
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces}"
},
"75040": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified category ID is invalid."
},
"75042": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Missing query param ePID."
},
"75043": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified ePID is invalid."
},
"75044": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The field Primary category Id is required when Other Applicable Category Ids is present."
},
"75045": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The maximum number of Other Applicable Category Ids allowed is 4."
}
}
}
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
},
"/get_product_metadata_for_categories": {
"get": {
"tags": [
"product_metadata"
],
"description": "This call retrieves an array of all supported aspects, aspect constraints, and aspect values for the specified eBay categories. The array is a union (with duplicates removed) of all returned aspects. After using the search and getProduct calls to find a catalog product that matches a seller's inventory item, you may determine that a matching product does not exist in the eBay catalog. You can propose a new product for the catalog by taking the following steps: Use the Taxonomy API's category_tree calls to discover the appropriate category or categories for the seller's inventory item. See Finding categories for a listing or promotion. Use getProductMetadataForCategories to determine the aspects of your selected categories that should be associated with your new product. Use the createChangeRequest call to to submit a change request to add the new product to the eBay catalog for your seller's marketplace. Note: The X-EBAY-C-MARKETPLACE-ID request header is required to identify the user's business context. At least one eBay category ID is required and is specified through the primary_category_id query parameter.",
"operationId": "getProductMetadataForCategories",
"parameters": [
{
"name": "Accept-Language",
"in": "header",
"description": "This request header sets the natural language that will be provided in the field values of the response payload. Supported values for this header can be found in the Marketplace ID and language header values table.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "other_applicable_category_ids",
"in": "query",
"description": "A string of comma-separated category IDs. if sellers want to specify more than the primary category under which to offer a product, they can use this parameter to retrieve the aspects associated with all of the additional specified categories. eBay category IDs are returned by the Taxonomy API's category_tree calls.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "primary_category_id",
"in": "query",
"description": "The unique identifier of the primary eBay category for which you will retrieve product aspects. eBay category IDs are returned by the Taxonomy API's category_tree calls.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "X-EBAY-C-MARKETPLACE-ID",
"in": "header",
"description": "Use this header to specify the eBay marketplace identifier. Supported values for this header can be found under Supported marketplaces on the Catalog API Overview page.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductMetadataForCategories"
}
}
}
},
"204": {
"description": "No Content"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"75007": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Currently, the {marketplaceId} marketplace is not supported. The supported Marketplaces are: {allowedMarketplaces}"
},
"75040": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The specified category ID is invalid."
},
"75041": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "Missing query param primary category ID."
},
"75045": {
"domain": "API_CATALOG",
"category": "REQUEST",
"description": "The maximum number of Other Applicable Category Ids allowed is 4."
}
}
}
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"75000": {
"domain": "API_CATALOG",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope"
]
}
]
}
}
},
"components": {
"schemas": {
"Aspect": {
"type": "object",
"properties": {
"localizedName": {
"type": "string",
"description": "The localized name of this category aspect."
},
"localizedValues": {
"type": "array",
"description": "A list of the localized values of this category aspect.",
"items": {
"type": "string"
}
}
},
"description": "This type contains the name and values of a category aspect."
},
"AspectDistribution": {
"type": "object",
"properties": {
"aspectValueDistributions": {
"type": "array",
"description": "Contains information about one or more values of the category aspect identified by localizedAspectName.",
"items": {
"$ref": "#/components/schemas/AspectValueDistribution"
}
},
"localizedAspectName": {
"type": "string",
"description": "The localized name of an aspect that is associated with the category identified by dominantCategoryId."
}
},
"description": "This type contains information about one category aspect that is associated with a specified category."
},
"AspectValueDistribution": {
"type": "object",
"properties": {
"localizedAspectValue": {
"type": "string",
"description": "The localized value of the category aspect identified by refinement.aspectDistributions.localizedAspectName."
},
"matchCount": {
"type": "integer",
"description": "The number of times the value of localizedAspectValue has been used for eBay product listings. By comparing this quantity to the matchCount for other values of the same aspect, you can present a histogram of the values to sellers, who can use that information to select which aspect value is most appropriate for their product. You can then include the user-selected value in the the search call's aspect_filter parameter to refine your search.",
"format": "int32"
},
"refinementHref": {
"type": "string",
"description": "A HATEOAS reference that further refines the search with this particular localizedAspectValue."
}
},
"description": "This type contains information about one value of a specified aspect. This value serves as a product refinement."
},
"CategoryAspect": {
"type": "object",
"properties": {
"aspectHelpText": {
"type": "string",
"description": "Returned only if this field is populated. This provides information and context for the category aspect. The help text can be presented to the seller to clarify the intended purpose of this aspect, and recommendations for its use. For example, the help text for the Country/Region of Manufacture aspect is: Specifying the country/region of manufacture can help streamline customs clearance."
},
"constraint": {
"description": "Contains information about the input and formatting constraints of the category aspect, including the data type and format, input mode, occurrence, and cardinality.",
"$ref": "#/components/schemas/ProductAspectConstraint"
},
"name": {
"type": "string",
"description": "The name of the category aspect."
},
"values": {
"type": "array",
"description": "Not returned if the value of the constraint field is FREE_TEXT and there are no stored values for this aspect. Contains information about one or more supported values for the category identified by the name field), as well as constraint information for those values.",
"items": {
"$ref": "#/components/schemas/CategoryAspectValue"
}
}
},
"description": "This type contains detailed information about each required and recommended aspect associated with an eBay category. These details include the aspect name, supported/possible values, and constraint information."
},
"CategoryAspectValue": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "A supported value of the corresponding category aspect (shown in the aspects.name field). Every supported value for the category aspect is shown in the aspects.values container."
},
"valueConstraints": {
"type": "array",
"description": "Not returned if the value of the value field can always be selected for this aspect of the specified category (that is, when no constraints apply to using the value). Contains a list of the dependencies that identify when the value of the value field is available for the current aspect. Each dependency specifies the values of another aspect of the same category (a control aspect), for which the current value of the current aspect can also be selected by the seller. Example: A shirt is available in three sizes and three colors, but only the Small and Medium sizes come in Green. Thus for the Color aspect, the value Green is constrained by its dependency on Size (the control aspect). Only when the Size aspect value is Small or Medium, can the Color aspect value of Green be selected by the seller.",
"items": {
"$ref": "#/components/schemas/ValueConstraint"
}
}
},
"description": "This type contains the supported values for a given category aspect name, as well as constraint information for specified category aspect values for a product."
},
"ChangeRequest": {
"type": "object",
"properties": {
"changeRequestId": {
"type": "string",
"description": "The 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."
},
"changeRequestStatus": {
"type": "string",
"description": "The 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. For implementation help, refer to eBay API documentation"
},
"changeRequestType": {
"type": "string",
"description": "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 For implementation help, refer to eBay API documentation"
},
"creationDate": {
"type": "string",
"description": "The creation date of this change request."
},
"expectedCompletionDate": {
"type": "string",
"description": "eBay's estimate of the completion date of this change request."
},
"processResolution": {
"description": "Returned 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",
"$ref": "#/components/schemas/ProcessResolution"
},
"processStatusMessage": {
"type": "string",
"description": "A text description and explanation of the status indicated by the changeRequestStatus field."
},
"reasonForChangeRequest": {
"type": "string",
"description": "A text description of why this change request was submitted."
},
"referenceId": {
"type": "string",
"description": "Returned 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."
},
"referenceType": {
"type": "string",
"description": "Returned 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. For implementation help, refer to eBay API documentation"
},
"resolutionDate": {
"type": "string",
"description": "Returned if the value of changeRequestStatus is APPROVED, APPROVED_WITH_MODIFICATIONS, or REJECTED. This is the date that the change request was resolved."
},
"suggestedProduct": {
"description": "Contains the full details of the suggested product, including information about the product's identifiers, description, product images, categories, and aspects.",
"$ref": "#/components/schemas/SuggestedProduct"
}
},
"description": "This type contains the full details of a specified catalog change request, including the original payload of the createChangeRequest call, processing status and key dates, and resolution details."
},
"ConflictingProduct": {
"type": "object",
"properties": {
"conflictCode": {
"type": "string",
"description": "The eBay assigned identifier of this conflict."
},
"differentiatingAspects": {
"type": "array",
"description": "Contains 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.",
"items": {
"$ref": "#/components/schemas/ProductAspect"
}
},
"epid": {
"type": "string",
"description": "The eBay product ID of the conflicting catalog product."
},
"reason": {
"type": "string",
"description": "The reason for this conflict."
}
},
"description": "This type contains information about an existing catalog product that presents a conflict with a seller's suggested product."
},
"Correction": {
"type": "object",
"properties": {
"aspectValues": {
"description": "Returned 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.",
"$ref": "#/components/schemas/CorrectionAspectValues"
},
"correctionCode": {
"type": "string",
"description": "The eBay-assigned identifier of the correction type for this correction."
},
"productAttribute": {
"description": "Contains 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.",
"$ref": "#/components/schemas/CorrectionProductAttribute"
},
"reason": {
"type": "string",
"description": "The reason why this correction is required."
}
},
"description": "This type contains information about a correction that eBay has applied to the suggested product in a change request."
},
"CorrectionAspectValue": {
"type": "object",
"properties": {
"newValue": {
"type": "string",
"description": "The aspect's correct value"
},
"value": {
"type": "string",
"description": "The aspect's current incorrect value."
}
},
"description": "This type contains a value of a given eBay product aspect which must be corrected, along with the correct value."
},
"CorrectionAspectValues": {
"type": "object",
"properties": {
"aspectName": {
"type": "string",
"description": "The localized name of this product aspect that requires correction, such as Model Number, Size, or Color."
},
"values": {
"type": "array",
"description": "A list of one or more values of this product aspect that must be corrected.",
"items": {
"$ref": "#/components/schemas/CorrectionAspectValue"
}
}
},
"description": "This type identifies a product aspect that requires correction in a catalog change request, along with its aspect values that must be corrected."
},
"CorrectionProductAttribute": {
"type": "object",
"properties": {
"attributeName": {
"type": "string",
"description": "The 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. For implementation help, refer to eBay API documentation"
},
"newValue": {
"type": "string",
"description": "Not returned if the value of attributeName is ASPECT_NAME (see instead corrections.aspectValues). This is the named attribute's correct value."
},
"value": {
"type": "string",
"description": "Not returned if the value of attributeName is ASPECT_NAME (see instead corrections.aspectValues). This is the named attribute's current incorrect value."
}
},
"description": "Contains information about a particular product attribute with an incorrect value."
},
"CreateChangeRequestPayload": {
"type": "object",
"properties": {
"changeRequestType": {
"type": "string",
"description": "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 For implementation help, refer to eBay API documentation"
},
"reasonForChangeRequest": {
"type": "string",
"description": "Required if the value of changeRequestType is PRODUCT_UPDATE, and optional otherwise; this is a text description of why this change is being requested."
},
"referenceId": {
"type": "string",
"description": "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."
},
"referenceType": {
"type": "string",
"description": "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. For implementation help, refer to eBay API documentation"
},
"suggestedProduct": {
"description": "Contains the full details of the suggested product, including information about the product's identifiers, description, product images, categories, and aspects.",
"$ref": "#/components/schemas/SuggestedProduct"
}
},
"description": "This type contains the input payload of the createChangeRequest call, including the type of request, the reason for a product update request, and the details of the new or updated product being suggested."
},
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Identifies the type of erro."
},
"domain": {
"type": "string",
"description": "Name for the primary system where the error occurred. This is relevant for application errors."
},
"errorId": {
"type": "integer",
"description": "A unique number to identify the error.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error."
},
"message": {
"type": "string",
"description": "Information on how to correct the problem, in the end user's terms and language where applicable."
},
"outputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
}
},
"description": "This type defines the fields that can be returned in an error."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The object of the error."
},
"value": {
"type": "string",
"description": "The value of the object."
}
}
},
"GetChangeRequestsResponse": {
"type": "object",
"properties": {
"changeRequests": {
"type": "array",
"description": "Contains 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.",
"items": {
"$ref": "#/components/schemas/ChangeRequest"
}
},
"href": {
"type": "string",
"description": "The URI of the getChangeRequests call request that produced this page of results."
},
"limit": {
"type": "integer",
"description": "The 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.",
"format": "int32"
},
"next": {
"type": "string",
"description": "The 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."
},
"offset": {
"type": "integer",
"description": "The 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.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "The 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."
},
"total": {
"type": "integer",
"description": "The total number of change requests in the collection. Note: If no change requests are found, this field is returned with a value of 0.",
"format": "int32"
}
},
"description": "This type contains the output payload of the getChangeRequests call, which is a portion of the collection of change requests that match the search criteria. The returned set of change requests is a page, and the response includes information for navigating the output pages."
},
"Image": {
"type": "object",
"properties": {
"height": {
"type": "integer",
"description": "The height of the image in pixels.",
"format": "int32"
},
"imageUrl": {
"type": "string",
"description": "The eBay Picture Services (EPS) URL of the image."
},
"width": {
"type": "integer",
"description": "The width of the image in pixels.",
"format": "int32"
}
},
"description": "This type contains information about a product image stored in eBay Picture Services (EPS)."
},
"ProcessResolution": {
"type": "object",
"properties": {
"conflictingProducts": {
"type": "array",
"description": "Contains 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.",
"items": {
"$ref": "#/components/schemas/ConflictingProduct"
}
},
"corrections": {
"type": "array",
"description": "Contains 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.",
"items": {
"$ref": "#/components/schemas/Correction"
}
},
"epid": {
"type": "string",
"description": "Returned only if the value of changeRequestStatus is APPROVED or APPROVED_WITH_MODIFICATIONS; this is the eBay identifier of the resulting product."
},
"productHref": {
"type": "string",
"description": "The 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."
},
"violations": {
"type": "array",
"description": "Contains information about one or more violations in the values of the suggested product's aspects or fixed attributes.",
"items": {
"$ref": "#/components/schemas/Violation"
}
}
},
"description": "This type provides details of conflicting products, corrections required, or violations that were discovered in a change request."
},
"Product": {
"type": "object",
"properties": {
"additionalImages": {
"type": "array",
"description": "Contains information about additional images associated with this product. For the primary image, see the image container.",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"aspects": {
"type": "array",
"description": "Contains an array of the category aspects and their values that are associated with this product.",
"items": {
"$ref": "#/components/schemas/Aspect"
}
},
"brand": {
"type": "string",
"description": "The manufacturer's brand name for this product."
},
"description": {
"type": "string",
"description": "The rich description of this product, which might contain HTML."
},
"ean": {
"type": "array",
"description": "A list of all European Article Numbers (EANs) that identify this product.",
"items": {
"type": "string"
}
},
"epid": {
"type": "string",
"description": "The eBay product ID of this product."
},
"gtin": {
"type": "array",
"description": "A list of all GTINs that identify this product. Currently this can include EAN, ISBN, and UPC identifier types.",
"items": {
"type": "string"
}
},
"image": {
"description": "Contains information about the primary image of this product. For more images of this product, see the additionalImages container.",
"$ref": "#/components/schemas/Image"
},
"isbn": {
"type": "array",
"description": "A list of all International Standard Book Numbers (ISBNs) that identify this product.",
"items": {
"type": "string"
}
},
"mpn": {
"type": "array",
"description": "A list of all MPN values that the manufacturer uses to identify this product.",
"items": {
"type": "string"
}
},
"otherApplicableCategoryIds": {
"type": "array",
"description": "A list of category IDs (other than the value of primaryCategoryId) for all the leaf categories to which this product might belong.",
"items": {
"type": "string"
}
},
"primaryCategoryId": {
"type": "string",
"description": "The identifier of the leaf category that eBay recommends using to list this 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."
},
"productWebUrl": {
"type": "string",
"description": "The URL for this product's eBay product page."
},
"title": {
"type": "string",
"description": "The title of this product on eBay."
},
"upc": {
"type": "array",
"description": "A list of Universal Product Codes (UPCs) that identify this product.",
"items": {
"type": "string"
}
},
"version": {
"type": "string",
"description": "The current version number of this product record in the catalog."
}
},
"description": "This type contains the full details of a specified product, including information about the product's identifiers, product images, aspects, and categories."
},
"ProductAspect": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the product aspect, such as Model Number, Size, or Color."
},
"values": {
"type": "array",
"description": "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.",
"items": {
"type": "string"
}
}
},
"description": "This type contains the name and values of a category aspect that is associated with a particular product."
},
"ProductAspectConstraint": {
"type": "object",
"properties": {
"aspectDataType": {
"type": "string",
"description": "The data type used to represent the aspect. See the AspectDataTypeEnum type for more information about each data type. For implementation help, refer to eBay API documentation"
},
"aspectFormat": {
"type": "string",
"description": "Returned only if the value of aspectDataType is STRING or NUMBER. The required format for date or number values (e.g. a date value may be expressed as MMYYYY or MMYY)."
},
"aspectMode": {
"type": "string",
"description": "Indicates whether the seller must select from a closed list of aspect values, or can input the aspect value manually. For implementation help, refer to eBay API documentation"
},
"aspectRequired": {
"type": "boolean",
"description": "A value of true indicates that the aspect is mandatory for products listed in this category."
},
"importance": {
"type": "string",
"description": "This value indicates the level of importance of the product identifier appearing in the catalog product. For implementation help, refer to eBay API documentation"
},
"productToAspectCardinality": {
"type": "string",
"description": "Indicates whether the aspect requires only one value, or can accept multiple values when listing in this category. An example of a product aspect that will often have numerous values is Features. For implementation help, refer to eBay API documentation"
}
},
"description": "This type contains information about the constraints for an aspect that's associated with a specific eBay category or eBay Catalog product."
},
"ProductAspectValue": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "A supported value of the corresponding product aspect (shown in the aspects.name field). Every supported value for the product aspect is shown under the aspects.values container. Note that one of these values can possibly be used instead of the product aspect value(s) currently defined for the eBay Catalog product and specified in the aspects.valuesAssociatedWithProduct array."
},
"valueConstraints": {
"type": "array",
"description": "Not returned if the value of the value field can always be selected for this aspect of the specified category. Contains a list of the dependencies that identify when the value of the value field is available for the current aspect. Each dependency specifies the values of another aspect of the same category (a control aspect), for which the current value of the current aspect can also be selected by the seller. Example: A shirt is available in three sizes and three colors, but only the Small and Medium sizes come in Green. Thus for the Color aspect, the value Green is constrained by its dependency on Size (the control aspect). Only when the Size aspect value is Small or Medium, can the Color aspect value of Green be selected by the seller.",
"items": {
"$ref": "#/components/schemas/ValueConstraint"
}
}
},
"description": "This type contains information about a product aspect associated with a given catalog product."
},
"ProductIdentifier": {
"type": "object",
"properties": {
"constraint": {
"description": "Contains information about the input, formatting, and occurrence constraints of the product identifier.",
"$ref": "#/components/schemas/ProductIdentifierConstraint"
},
"values": {
"type": "array",
"description": "A list of one or more valid values for this product identifier.",
"items": {
"type": "string"
}
}
},
"description": "This type contains information about certain available product attributes, their input requirements, and their constraints for specified categories."
},
"ProductIdentifierConstraint": {
"type": "object",
"properties": {
"importance": {
"type": "string",
"description": "This value indicates the level of importance of the product identifier appearing in the catalog product. For implementation help, refer to eBay API documentation"
},
"mode": {
"type": "string",
"description": "Indicates whether the seller must select from a closed list of identifier values, or can input the identifier manually. For implementation help, refer to eBay API documentation"
},
"required": {
"type": "boolean",
"description": "A value of true indicates that the identifier is mandatory for the product or categories specified."
}
},
"description": "This type contains information about the input, formatting, and occurrence constraints of a product identifier."
},
"ProductIdentifierForProductMetadata": {
"type": "object",
"properties": {
"constraint": {
"description": "Contains information about the input, formatting, and occurrence constraints of the product identifier.",
"$ref": "#/components/schemas/ProductIdentifierConstraint"
},
"valueAssociatedWithProduct": {
"type": "string",
"description": "The identifier value currently associated with the product."
},
"values": {
"type": "array",
"description": "A list of one or more valid values for this product identifier.",
"items": {
"type": "string"
}
}
},
"description": "This type contains information about certain available product attributes, their input requirements, and their constraints for a specified product and any specified categories."
},
"ProductMetadata": {
"type": "object",
"properties": {
"aspects": {
"type": "array",
"description": "Contains information about one or more aspects that are supported for the specified catalog product, including those that are currently associated with the product. This is a union (with duplicates removed) of all aspects associated with the specified category or categories (if provided) and those associated with the product.",
"items": {
"$ref": "#/components/schemas/ProductMetadataAspect"
}
},
"brand": {
"description": "Contains information about available brand names, their input requirements, and their constraints for the specified product and categories.",
"$ref": "#/components/schemas/ProductIdentifierForProductMetadata"
},
"ean": {
"description": "The European Article Numbers (EANs) that identify this product.",
"$ref": "#/components/schemas/ProductIdentifierForProductMetadata"
},
"isbn": {
"description": "The International Standard Book Numbers (ISBNs) associated with the product.",
"$ref": "#/components/schemas/ProductIdentifierForProductMetadata"
},
"mpn": {
"description": "Contains information about available Manufacturer Product Numbers (MPNs), their input requirements, and their constraints for the specified product and categories.",
"$ref": "#/components/schemas/ProductIdentifierForProductMetadata"
},
"upc": {
"description": "The Universal Product Codes (UPCs) associated with the product.",
"$ref": "#/components/schemas/ProductIdentifierForProductMetadata"
}
},
"description": "This type is the container type for the response payload of the getProductMetadata call, which returns merged aspect metadata for a catalog product."
},
"ProductMetadataAspect": {
"type": "object",
"properties": {
"aspectHelpText": {
"type": "string",
"description": "Returned only if this field is populated. This provides information and context for the product aspect. The help text can be presented to the seller to clarify the intended purpose of the aspect, and recommendations for its use. For example, the help text for the Country/Region of Manufacture aspect is: Specifying the country/region of manufacture can help streamline customs clearance."
},
"constraint": {
"description": "Contains information about the constraints for this product aspect, including data type and format, input mode, and occurrence.",
"$ref": "#/components/schemas/ProductAspectConstraint"
},
"droppable": {
"type": "boolean",
"description": "A value of true indicates that this product aspect can be removed from the specified catalog product definition by omitting it from a product change request. A value of false indicates that this product aspect cannot be dropped (although it is possible that its value could be modified)."
},
"name": {
"type": "string",
"description": "The name of the product aspect, such as Model Number, Size, or Color."
},
"values": {
"type": "array",
"description": "Not returned if the value of the constraint field is FREE_TEXT and there are no stored values for this aspect. Contains information about the supported values for the product aspect identified by the name field, as well as constraint information for the product aspect values. These values can be used instead of the product aspect value(s) currently defined for the eBay Catalog product, and those specified in the valuesAssociatedWithProduct array.",
"items": {
"$ref": "#/components/schemas/ProductAspectValue"
}
},
"valuesAssociatedWithProduct": {
"type": "array",
"description": "The value(s) currently defined for the eBay Catalog product for the product aspect identified by the corresponding name field.",
"items": {
"type": "string"
}
}
},
"description": "This type contains detailed information about an aspect that's supported for a given eBay Catalog product. These details include the aspect name, current value(s), supported/possible values, and constraint information."
},
"ProductMetadataForCategories": {
"type": "object",
"properties": {
"aspects": {
"type": "array",
"description": "Contains information about one or more required and recommended product aspects associated with the specified eBay category or categories. This is a union (with duplicates removed) of all aspects associated with the specified categories.",
"items": {
"$ref": "#/components/schemas/CategoryAspect"
}
},
"brand": {
"description": "Contains information about available brand names, their input requirements, and their constraints for the specified categories.",
"$ref": "#/components/schemas/ProductIdentifier"
},
"ean": {
"description": "The European Article Numbers (EANs) that identify this product.",
"$ref": "#/components/schemas/ProductIdentifier"
},
"isbn": {
"description": "The International Standard Book Numbers (ISBNs) associated with the product.",
"$ref": "#/components/schemas/ProductIdentifier"
},
"mpn": {
"description": "Contains information about available Manufacturer Product Numbers (MPNs), their input requirements, and their constraints for the specified categories.",
"$ref": "#/components/schemas/ProductIdentifier"
},
"upc": {
"description": "The Universal Product Codes (UPCs) associated with the product.",
"$ref": "#/components/schemas/ProductIdentifier"
}
},
"description": "This type is the container type for the response payload of the getProductMetadataForCategories call, which returns required and recommended product aspects, brand names, and manufacturer part numbers for one or more eBay categories."
},
"ProductSearchResponse": {
"type": "object",
"properties": {
"href": {
"type": "string",
"description": "This field is reserved for internal or future use."
},
"limit": {
"type": "integer",
"description": "The number of product summaries returned in the response. This is the result set, a subset of the full collection of products that match the search or filter criteria of this call. If the limit query parameter was included in the request, this field will have the same value. Default: 50",
"format": "int32"
},
"next": {
"type": "string",
"description": "This field is reserved for internal or future use."
},
"offset": {
"type": "integer",
"description": "This field is reserved for internal or future use.",
"format": "int32"
},
"prev": {
"type": "string",
"description": "This field is reserved for internal or future use."
},
"productSummaries": {
"type": "array",
"description": "Returned if the fieldGroups query parameter was omitted from the request, or if it was included with a value of MATCHING_PRODUCTS or FULL. This container provides an array of product summaries in the current result set for products that match the combination of the q, category_ids, and aspect_filter parameters that were provided in the request. Each product summary includes information about the product's identifiers, product images, aspects, the product page URL, and the getProduct URL for retrieving the product details.",
"items": {
"$ref": "#/components/schemas/ProductSummary"
}
},
"refinement": {
"description": "Returned only if the fieldGroups query parameter was included in the request with a value of ASPECT_REFINEMENTS or FULL. An aspect is a property of a category, used by sellers to provide details about the items they're listing. For example, the Cell Phones & Smartphones category (#9355) includes a Storage Capacity aspect. This container provides information about the distribution of values of a set of category aspects. The category aspects are those associated with the category that eBay determines is most likely to cover the products that match the search criteria.",
"$ref": "#/components/schemas/Refinement"
},
"total": {
"type": "integer",
"description": "This field is reserved for internal or future use.",
"format": "int32"
}
},
"description": "This type contains the specifications for the collection of products that match the search or filter criteria of a search call. A maximum of 200 product summaries is returned (the result set), fewer if you include the limit query parameter in the request."
},
"ProductSummary": {
"type": "object",
"properties": {
"additionalImages": {
"type": "array",
"description": "Contains information about additional images associated with this product. For the primary image, see the image container.",
"items": {
"$ref": "#/components/schemas/Image"
}
},
"aspects": {
"type": "array",
"description": "Contains an array of the category aspects and their values that are associated with this product.",
"items": {
"$ref": "#/components/schemas/Aspect"
}
},
"brand": {
"type": "string",
"description": "The manufacturer's brand name for this product."
},
"ean": {
"type": "array",
"description": "A list of all European Article Numbers (EANs) that identify this product.",
"items": {
"type": "string"
}
},
"epid": {
"type": "string",
"description": "The eBay product ID of this product."
},
"gtin": {
"type": "array",
"description": "A list of all GTINs that identify this product. This includes all of the values returned in the ean, isbn, and upc fields.",
"items": {
"type": "string"
}
},
"image": {
"description": "Contains information about the primary image of this product. For more images of this product, see the additionalImages container.",
"$ref": "#/components/schemas/Image"
},
"isbn": {
"type": "array",
"description": "A list of all International Standard Book Numbers (ISBNs) that identify this product.",
"items": {
"type": "string"
}
},
"mpn": {
"type": "array",
"description": "A list of all Manufacturer Product Number (MPN) values that the manufacturer uses to identify this product.",
"items": {
"type": "string"
}
},
"productHref": {
"type": "string",
"description": "The URI of the getProduct call request that retrieves this product's details."
},
"productWebUrl": {
"type": "string",
"description": "The URL for this product's eBay product page."
},
"title": {
"type": "string",
"description": "The title of this product on eBay."
},
"upc": {
"type": "array",
"description": "A list of Universal Product Codes (UPCs) that identify this product.",
"items": {
"type": "string"
}
}
},
"description": "This type contains a summary of a specified product. The product summary includes information about the product's identifiers, product images, aspects, and the getProduct URL for retrieving the product details."
},
"Refinement": {
"type": "object",
"properties": {
"aspectDistributions": {
"type": "array",
"description": "Contains information about one or more aspects that are associated with the category identified by dominantCategoryId.",
"items": {
"$ref": "#/components/schemas/AspectDistribution"
}
},
"dominantCategoryId": {
"type": "string",
"description": "The ID of the category that eBay determines is most likely to cover the products matching the search criteria."
}
},
"description": "This type identifies a product category and the aspects associated with that category. Each aspect distribution container returns the distribution of values that have been used for the aspect."
},
"SuggestedProduct": {
"type": "object",
"properties": {
"additionalImageUrls": {
"type": "array",
"description": "A list of URLs for additional images associated with the suggested product. For the URL of the primary image, see the imageUrl field.",
"items": {
"type": "string"
}
},
"aspects": {
"type": "array",
"description": "Contains one or more category aspects and their values that are associated with the suggested product.",
"items": {
"$ref": "#/components/schemas/ProductAspect"
}
},
"brand": {
"type": "string",
"description": "The manufacturer's brand name for the suggested product."
},
"description": {
"type": "string",
"description": "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."
},
"ean": {
"type": "array",
"description": "A list of all European Article Numbers (EANs) that identify the suggested product.",
"items": {
"type": "string"
}
},
"epid": {
"type": "string",
"description": "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."
},
"imageUrl": {
"type": "string",
"description": "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."
},
"isbn": {
"type": "array",
"description": "A list of all International Standard Book Numbers (ISBNs) that identify the suggested product.",
"items": {
"type": "string"
}
},
"mpn": {
"type": "array",
"description": "A list of all Manufacturer Product Number (MPN) values that the manufacturer uses to identify the suggested product.",
"items": {
"type": "string"
}
},
"otherApplicableCategoryIds": {
"type": "array",
"description": "A list of category IDs (other than the value of primaryCategoryId) for all the leaf categories to which the suggested product might belong.",
"items": {
"type": "string"
}
},
"primaryCategoryId": {
"type": "string",
"description": "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."
},
"title": {
"type": "string",
"description": "The catalog title that will be used as the listing title for all item listings based on the suggested product."
},
"upc": {
"type": "array",
"description": "A list of all Universal Product Codes (UPCs) that identify the suggested product.",
"items": {
"type": "string"
}
},
"version": {
"type": "string",
"description": "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."
}
},
"description": "This type contains the full details of a suggested product, including information about the product's identifiers, description, product images, categories, and aspects."
},
"ValueConstraint": {
"type": "object",
"properties": {
"applicableForAspectName": {
"type": "string",
"description": "The name of the control aspect on which the current aspect value depends."
},
"applicableForAspectValues": {
"type": "array",
"description": "Contains a list of the values of the control aspect on which this aspect's value depends. When the control aspect has any of the specified values, the current value of the current aspect will also be available.",
"items": {
"type": "string"
}
}
},
"description": "This type contains a list of the dependencies that identify when a particular value is available for a given aspect of a given category. Each dependency specifies the values of another aspect of the same category (the control aspect), for which the given value of the given aspect can also be selected by the seller. This container consists of constraint information for the corresponding product aspect value."
},
"Violation": {
"type": "object",
"properties": {
"aspectsValues": {
"description": "Returned 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.",
"$ref": "#/components/schemas/ViolationAspectValues"
},
"productAttribute": {
"description": "Contains 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.",
"$ref": "#/components/schemas/ViolationProductAttribute"
},
"reason": {
"type": "string",
"description": "An explanation of the reason for this violation."
},
"violationCode": {
"type": "string",
"description": "The eBay-assigned identifier of the violation type of this violation."
}
},
"description": "This type contains information about a violation of eBay standards in a change request."
},
"ViolationAspectValues": {
"type": "object",
"properties": {
"aspectName": {
"type": "string",
"description": "The localized name of this product aspect that's in violation, such as Model Number, Size, or Color."
},
"values": {
"type": "array",
"description": "A list of one or more values of this product aspect that are in violation of eBay standards.",
"items": {
"type": "string"
}
}
},
"description": "Contains the name of a product aspect that is in violation of eBay standards in a particular catalog change request, along with its values that produced the violation."
},
"ViolationProductAttribute": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The 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. For implementation help, refer to eBay API documentation"
},
"values": {
"type": "array",
"description": "Not 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.",
"items": {
"type": "string"
}
}
},
"description": "This type contains 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 values of the attribute that are in violation."
}
},
"securitySchemes": {
"api_auth": {
"type": "oauth2",
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"flows": {
"clientCredentials": {
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope": "View public data from eBay"
}
},
"authorizationCode": {
"authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope/commerce.catalog.readonly": " This scope would allow signed in user to read catalog data.",
"https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers"
}
}
}
}
}
}
}