Inventory Mapping API (GraphQL)
Inventory Mapping API (GraphQL)
カテゴリ: sell
用途: 出品管理 (Listing Management)
タイプ: GraphQL
元リンク： Inventory Mapping API
Inventory Mapping APIは、既存の製品データから生成されたAIによる推奨事項を使用して、セラーが高品質な出品を作成するのを支援します。
クエリ (Queries)
listingPreviewsCreationTaskById
listingPreviewsCreationTaskById クエリは、IDによって ListingPreviewsCreationTask を取得します。返されるデータには、作成された出品プレビュー、および処理されなかった、マッピングされなかった、または無効な製品を含むタスクのステータスと結果が含まれます。このクエリを使用して、タスクのステータスを確認したり、セラーの外部製品をeBay出品プレビューに変換した結果を取得したりします。
startListingPreviewsCreation ミューテーションを送信した直後にこのクエリを呼び出して、タスクのステータスを確認できます。
ミューテーション (Mutations)
startListingPreviewsCreation
startListingPreviewsCreation ミューテーションは、セラーが提供した外部製品データ（最大10製品）を活用し、このデータを使用して提供された各製品のeBay出品プレビューを作成するプロセスを開始します。この非同期プロセスは完了までに時間がかかる場合があり、その時間は処理される外部製品の数に部分的に依存します。startListingPreviewsCreation ミューテーションには、外部製品の詳細が含まれます。ミューテーションの出力には、ステータスとタスクIDが含まれます。
型 (Types)
Category
この型は、外部製品に対して推奨されるeBayリーフカテゴリのIDを示します。null値は、データが利用できないか未定義であることを意味します。
| フィールド | 型 | 説明 |
|---|---|---|
| id | ID! | eBayリーフカテゴリの識別子。@deprecated(reason: "Use 'categoryId' field instead") |
| ancestors | [Category!]! | カテゴリエイリアス。リストの最初の要素は直近の祖先です。リストの最後の要素はルートカテゴリです。このカテゴリがルートの場合、リストは空になります。 |
| categoryId | ID! | カテゴリID。 |
| children | [Category!]! | カテゴリの子要素。リスト要素の順序は保証されません。 |
| leafCategory | Boolean! | カテゴリがリーフカテゴリであるか、さらに子を持つかを示します。 |
| level | Int! | カテゴリの階層/家系図におけるカテゴリの位置を示します。 |
| name | String! | カテゴリ名。名前はローカライズされていません。 |
| parent | Category | 親カテゴリ。nullの場合、このカテゴリには親がないことを意味します。 |
ExternalProductDetails
この型は、単一の外部製品の詳細を表します。これらの詳細は、eBay出品プレビューの作成に使用されます。
| フィールド | 型 | 説明 |
|---|---|---|
| aspects | [ExternalProductDetailsAspect!] | 外部製品の製品アスペクト名と値のペアの配列。 |
| category | String |
外部製品の出品カテゴリへのフルパス（例：/Electronics/Cell Phones & Accessories/Smart Watches）。外部製品に対して提供されなかった場合、このフィールドはnullとして返されます。
|
| externalProductIdentifier | ExternalProductIdentifier | このコンテナは、外部製品のGlobal Trade Identifier Number (GTIN) を示します。外部製品に対して提供されなかった場合、このコンテナはnullとして返されます。 |
| images | [HttpOrHttpsUrl!] | 製品の画像を指すURLの配列。 |
| sku | String | 外部製品のセラー定義の在庫管理単位（SKU）を表します。外部製品に対してSKUが提供されなかった場合、このフィールドはnullを返します。 |
| title | String | 外部製品のタイトル。外部製品に対して提供されなかった場合、このフィールドはnullとして返されます。 |
ExternalProductDetailsAspect
この型は、外部製品の特定の機能またはアスペクトを表すために使用されます。各アスペクトは、名前と1つ以上の値のリストによって定義されます。
| フィールド | 型 | 説明 |
|---|---|---|
| name | String! | 外部製品のアスペクトの名前。 |
| values | [String!]! | アスペクトに対応する1つ以上の値のリスト。 |
ExternalProductIdentifier
この型は、外部製品のGlobal Trade Identifier Number (GTIN) を表示するために使用されます。
| フィールド | 型 | 説明 |
|---|---|---|
| productId | String! | productType フィールドで指定されたGTINタイプに対応する、外部製品のGTIN値。外部製品に対してGTINが提供されなかった場合、このフィールドはnullとして返されます。 |
| productType | ExternalProductIdentifierEnum! |
外部製品のGTINタイプ。UPC、ISBN、および EAN がサポートされている値です。外部製品に対してGTINが提供されなかった場合、このフィールドはnullとして返されます。
|
InvalidExternalProductDetails
この型は、eBay出品プレビューの作成に使用できなかった外部製品の詳細を提供します。各無効な製品には、外部製品の詳細が出品プレビューの作成に適さなかった理由を説明する description フィールドが含まれます。説明はローカライズされておらず、時間の経過とともに変更される可能性があります。このフィールドは人間向けのデバッグ支援を目的としており、クライアント側の処理ロジックに description を使用しないでください。
| フィールド | 型 | 説明 |
|---|---|---|
| clientProvidedProductDetails | ExternalProductDetails! | ミューテーションリクエストを通じて最初に提供された外部製品の詳細。 |
| description | String! | 外部製品の詳細を使用してeBay出品プレビューを作成できなかった理由についての人間が読める説明。このフィールドは人間向けのデバッグ支援を目的としています。クライアント側の処理ロジックに説明を使用しないでください。 |
ListingPreview
この型は、出品プレビューと、各出品プレビューの生成に使用された外部製品の詳細を表示します。出品プレビューは、eBay製品ID（見つかった場合）、タイトル、商品説明、eBayカテゴリID、1つ以上のeBay Picture Service (ePS) 画像URL、製品アスペクト名と値のペア、SKU（提供された場合）など、eBay出品で使用される主要なフィールドの推奨詳細を提供します。
出品プレビューは下書きでもライブ出品でもなく、セラーがeBay出品APIを使用して次のステップで出品を作成する際に活用できる、外部製品の詳細から生成された情報です。
| フィールド | 型 | 説明 |
|---|---|---|
| aspects | [ListingPreviewProductAspect!] | 製品に対するeBayの推奨製品アスペクト名と値のペア、またはeBayカタログ製品が見つかった場合は、カタログ製品に関連付けられた製品アスペクト名と値のペア。 |
| category | Category | 製品を出品するためのeBayの推奨eBayリーフカテゴリ、またはeBayカタログ製品が見つかった場合は、カタログ製品に関連付けられたeBayリーフカテゴリ。特定の例外的な状況下でデータが利用できないか未定義である場合、null値を意味します。 |
| clientProvidedProductDetails | ExternalProductDetails! | このコンテナは、eBay出品プレビューにマッピングされた外部製品の提供された詳細を表示します。 |
| description | String | 製品の説明に対するeBayの推奨事項、またはeBayカタログ製品が見つかった場合は、カタログ製品に使用されている説明。特定の例外的な状況下でデータが利用できないか未定義である場合、null値を意味します。 |
| images | [HttpOrHttpsUrl!] | 出品で使用できる1つ以上のEPS画像URLの配列。ミューテーションリクエストの images 配列を通じて画像が提供された場合、eBayは対応するEPS画像URLを返します。さらに、外部製品に対してeBayカタログ製品が一致した場合、フィールドにはカタログ製品のストックフォトURLも含まれる場合があります。画像が利用できない場合、配列はnullになります。 |
| mappingReferenceId | String! |
この出品プレビューの一意の識別子。関連するAPIを介して出品プレビューに基づいて出品を作成または修正する際に、この25文字のIDを使用します。 最大長: 25文字 |
| product | Product | このコンテナの下にあるeBay製品ID (ePID) フィールドは、外部製品が一致したeBayカタログ製品を示します。ePID値は、eBay出品APIで製品タイトル、商品説明、製品アスペクト、ストックフォト、eBayカテゴリを出品に自動入力（プリフィル）するために使用できます。外部製品をePIDにマッピングできなかった場合、このフィールドはnullになります。 |
| sku | String | 外部製品のセラー定義SKU。外部製品に対してSKUが提供されなかった場合、このフィールドはnullを返します。 |
| title | String | 製品のタイトルに対するeBayの推奨事項、またはeBayカタログ製品が見つかった場合は、カタログ製品に使用されているタイトル。eBay出品では出品タイトルに80文字しか許可されていないため、この推奨タイトルは外部製品に提供されたタイトルよりも短い場合があります。特定の例外的な状況下でデータが利用できないか未定義である場合、null値を意味します。 |
ListingPreviewProductAspect
この型は、製品に対するeBayの推奨製品アスペクト名と値のペアを表示します。各アスペクトは、名前と1つ以上の値のリストによって定義されます。values.confidence フィールドの値は、その値が対応するアスペクトに対して正しい値であるというeBayの確信度を示します。
考慮すべきエッジケース
ほとんどのアスペクトには単一の値が関連付けられることが予想されますが、一部のアスペクトは複数の値を受け入れる場合があります。
Taxonomy APIs を通じて、任意のカテゴリのアスペクトプロパティを相互参照してください。
そのようなアスペクトの場合、利用可能な場合、複数の PREFILL 値が返されることがあります。
たとえば、アスペクトが Color で、値が Red、Blue、Green であり、信頼レベルが PREFILL または HINT である場合があります。
| フィールド | 型 | 説明 |
|---|---|---|
| aspectValues | [String!]! | アスペクトの1つ以上の値の配列。@deprecated(reason: "This field is deprecated and has been superseded by the **values** array.") |
| name | String! | アスペクトの名前。 |
| values | [ListingPreviewProductAspectValue!]! | 対応するアスペクトの1つ以上の値を持つ配列と、その値が対応するアスペクトに対して正しい値であるというeBayの確信度を示す confidence フィールド。 |
ListingPreviewProductAspectValue
この型は、アスペクトの対応する値と、その値がそのアスペクトに対して正しい値であるというeBayの確信度レベルを表示します。
| フィールド | 型 | 説明 |
|---|---|---|
| confidence | ListingPreviewProductAspectValueConfidenceEnum | アスペクト値の信頼レベル。サポートされている各値の説明については、ListingPreviewProductAspectValueConfidenceEnum 型を参照してください。このフィールドは例外的な状況下でのみnullになります。 |
| value | String | アスペクトの値。このフィールドは例外的な状況下でのみnullになります。 |
ListingPreviewsCreationTask
この型は、ミューテーションリクエストで生成された出品プレビュータスクのIDと結果を表示します。この非同期タスクは完了までに時間がかかる場合があります。タスクが完了するまで、出品プレビューの結果は返されません。
| フィールド | 型 | 説明 |
|---|---|---|
| id | ID! |
タスクの一意の識別子。成功した StartListingPreviewsCreation ミューテーションの後に返されます。 最大長: 25 |
| result | ListingPreviewsCreationTaskResult | このコンテナは、出品プレビュー作成タスクのステータスと結果を提供します。タスクの実行が完了するまでnullのままです。 |
ListingPreviewsCreationTaskByIdOutput
listingPreviewsCreationTaskById クエリ応答の基本型。成功したクエリはタスクの id 値を返しますが、出品プレビューの結果はタスクが完了するまで返されません。
| フィールド | 型 | 説明 |
|---|---|---|
| listingPreviewsCreationTask | ListingPreviewsCreationTask | requestId 値に対応する ListingPreviewsCreationTask が存在する場合、ここに返されます。requestId を持つタスクが存在しない場合、このフィールドはnullになります。 |
| requestedId | ID! |
クエリリクエストに渡された出品プレビュータスクの一意の識別子。 最大長: 25文字 |
ListingPreviewsCreationTaskResult
この型は、出品プレビュー作成タスクの最終的な結果を表示するために使用され、完了ステータスと実際のeBay出品プレビューが含まれます。該当する場合、未処理の外部製品、マッピングされていない外部製品、および無効な外部製品は別々の配列に表示されます。
| フィールド | 型 | 説明 |
|---|---|---|
| completionStatus | ListingPreviewsCreationTaskCompletionStatus! |
この列挙値は、StartListingPreviewsCreation ミューテーションの成功または失敗を示します。適用可能な値は COMPLETED、COMPLETED_WITH_ERROR、または FAILED です。
|
| invalidProducts | [InvalidExternalProductDetails!]! | 処理できなかった無効な外部製品の配列。各無効な製品には、外部製品の詳細を使用して出品プレビューを作成できなかった理由を示す description フィールドが含まれます。このフィールドは人間向けのデバッグ支援を目的としています。説明はローカライズされておらず、変更される可能性があります。クライアント側の処理ロジックにこの説明フィールドを使用しないでください。無効な製品がない場合、この配列は空になります。 |
| listingPreviews | [ListingPreview!]! | この配列には、セラーが提供した外部製品に基づいて正常に作成されたeBay出品プレビューが表示されます。各出品プレビューには、eBay製品ID（見つかった場合）、タイトル、商品説明、eBayカテゴリID、1つ以上のeBay Picture Service (ePS) 画像URL、製品アスペクト名と値のペア、およびSKU（提供された場合）が含まれます。さらに、このコンテナには、外部製品のクライアント提供詳細を表示する clientProvidedProductDetails コンテナも含まれます。 |
| unmappedProducts | [ExternalProductDetails!]! | eBayによって出品プレビューに正常にマッピングされなかった有効な外部製品の配列。これらの製品はクライアントによって再試行されるべきではありません。マッピングされていない製品がない場合、この配列は空になります。 |
| unprocessedProducts | [ExternalProductDetails!]! | 予期せぬ状況により処理されなかった外部製品の配列。各外部製品のミューテーションリクエストで提供されたすべての詳細は、この配列の下に返されます。未処理の外部製品は、後続のミューテーションリクエストに含めることができます。未処理の製品がない場合、この配列は返されないか、nullになります。 |
Product
この型は、外部製品に一致したeBayカタログ製品のeBay製品識別子 (ePID) を示します。
| フィールド | 型 | 説明 |
|---|---|---|
| epid | Epid | eBayカタログ製品の一意の識別子。An ePID value can be used in eBay listing APIs to prefill a listing with product title, product description, product aspects, stock photo(s), and eBay category. @deprecated(reason: "This field is deprecated and has been superseded by the **id** field.") |
| id | ID! | eBayカタログ製品の一意の識別子。ePID値は、eBay出品APIで製品タイトル、商品説明、製品アスペクト、ストックフォト、eBayカテゴリを出品に自動入力（プリフィル）するために使用できます。@deprecated(reason: "Use 'productId' field instead") |
| aspects | [ProductAspect!]! | 製品アスペクト。 |
| category | Category! | eBayサイトカテゴリメタデータ。 |
| imageUrls | [String!] | 製品画像URL。 |
| productId | ID! | 製品ePID (eBay Product ID)。 |
| title | String! | 製品タイトル。 |
ProductAspect
製品アスペクト
| フィールド | 型 | 説明 |
|---|---|---|
| aspectValues | [String!]! | このアスペクトに対する有効な値のリスト（例：Red、Green、Blue）。 |
| displayName | String! | このアスペクトのローカライズされた名前。この名前は常に指定されたマーケットプレイス向けにローカライズされます。 |
StartListingPreviewsCreationError
この型は、ミューテーションまたはクエリの実行中に発生したエラーを表示するために使用されます。
| フィールド | 型 | 説明 |
|---|---|---|
| errorDescription | String! | ミューテーションまたはクエリの実行中に発生したエラーの説明。このフィールドは人間向けのデバッグ支援を目的としています。説明はローカライズされておらず、変更される可能性があります。クライアント側のエラー処理ロジックにこれらのエラー説明を使用しないでください。 |
StartListingPreviewsCreationOutput
startListingPreviewsCreation ミューテーション応答の基本型。成功したミューテーションはタスクの id 値を返しますが、出品プレビューの結果はタスクが完了するまで返されません。
| フィールド | 型 | 説明 |
|---|---|---|
| errors | [StartListingPreviewsCreationError!] | ミューテーションリクエストでトリガーされた可能性のある1つ以上のエラーの配列。エラーがない場合、このフィールドはnullとして返されます。 |
| listingPreviewsCreationTask | ListingPreviewsCreationTask | この基本応答コンテナは、ミューテーションが成功した場合に返されるべきですが、出品プレビューの結果はタスクが完了するまで返されません。 |
完全なスキーマ (Full Schema)
directive @authorize(scopes: [String!]!) on OBJECT | FIELD_DEFINITION
"""
This type shows the ID of the eBay leaf category that is recommended for the external product. A null value signifies that the data is unavailable or undefined.
"""
type Category {
"""The identifier of the eBay leaf category. """
id: ID! @deprecated(reason: "Use 'categoryId' field instead")
"""
Category ancestors. First element in list is the immediate ancestor. Last element in list is the root
category. If this Category is the root, the list will be empty.
"""
ancestors: [Category!]!
"""Category Id"""
categoryId: ID!
"""Category children. List elements are in no guaranteed order."""
children: [Category!]!
"""
Whether or not the category is a LEAF category or it further have children
"""
leafCategory: Boolean!
"""
Level indicate the place of the category in the hierarchy/family tree of the category
"""
level: Int!
"""Category name. The name is NOT localized."""
name: String!
"""
Parent category. If null, it means there is no parent for this Category.
"""
parent: Category
}
"""A slightly refined version of RFC-3339 compliant DateTime Scalar"""
scalar DateTime
""" This type represents the eBay Product ID (e.g. ePID), which is the unique identifier of an eBay catalog product.
"""
scalar Epid
"""
This type represents the specifics of a single external product. These details are used to create eBay Listing Previews.
"""
type ExternalProductDetails {
"""An array of product aspect name-value pairs for an external product."""
aspects: [ExternalProductDetailsAspect!]
"""
The full path to the listing category of the external product, such as `/Electronics/Cell Phones & Accessories/Smart Watches` This field will be returned as null if not provided for an external product.
"""
category: String
"""
This container shows the Global Trade Identifier Number (GTIN) for an external product. This container will be returned as null if not provided for an external product.
"""
externalProductIdentifier: ExternalProductIdentifier
"""An array of URLs pointing to images of the product."""
images: [HttpOrHttpsUrl!]
"""
Represents the seller-defined Stock Keeping Unit (SKU) of the external product. If the SKU was not provided for an external product, this field returns null.
"""
sku: String
"""
The title of the external product. This field will be returned as null if not provided for an external product.
"""
title: String
}
"""
This type is used to represent a specific feature or aspect of an external product. Each aspect is defined by a name and a list of one or more values.
"""
type ExternalProductDetailsAspect {
"""The name of the aspect for the external product. """
name: String!
"""A list of one or more corresponding values for the aspect. """
values: [String!]!
}
"""
This type is used to specify product aspect name-value pairs of an external product. Each aspect is defined by a name and a list of one or more values. The maximum number of aspects allowed is 50.
"""
input ExternalProductDetailsAspectInput {
"""
The name of the aspect for the external product.
**Max length**: 100 characters
"""
name: String!
"""
An array of one or more corresponding values for the aspect.
**Max length**: 100 characters
"""
values: [String!]!
}
"""
This type is used to provide details of external products. Product details include title, images, product identifiers, product aspects, category name, and SKU value.
If product aspects are provided, a category name must also be provided or a listing preview cannot be generated for that external product. A SKU is optional, but it is highly recommended as it acts as a key to track/identify different external products. Include as many fields as possible to increase chances of creating higher-quality eBay listing previews.
"""
input ExternalProductDetailsInput {
"""
An array of product aspect name-value pairs for the external product. If the array is included, it is required that it contain no null entries. Some aspects will only have one value and other aspects will have multiple values. **Example** `[{"name":"Color","values":["Black","Red"]},{"name":"Storage Capacity","values":["64GB"]}]`
"""
aspects: [ExternalProductDetailsAspectInput!]
"""
The listing category of the external product. A simple category name can be supplied here such as "Smart Watches", or you can provide the path to the category, such as /Electronics/Cell Phones & Accessories/Smart Watches.`
"""
categoryName: String
"""
This container is used to provide a Global Trade Identifier Number (GTIN) for an external product. If a GTIN value is provided for an external product, no other data under **externalProductDetails** shall be provided.
"""
externalProductIdentifierInput: ExternalProductIdentifierInput
"""
An array of image URLs provided for the external product. Each provided image must be a valid URL that uses 'https'. If the array is included, it is required that it contain no null entries.
**Max images**: 24
"""
images: [HttpOrHttpsUrl!]
"""
The SKU (Stock Keeping Unit) of the external product. This value is a seller-defined identifier for the product. This is an optional field, but it is highly recommended as it acts as a key to track/identify different external products.
"""
sku: String
"""
The title of the external product. The title field should not contain HTML or JavaScript code. Any HTML characters will be treated as plain text. The title should be a string of characters, with support for all characters in the Unicode character set. An example of a title is **`Apple iPhone 11 Pro Max`**.
**Max length:** 250 characters
"""
title: String
}
"""
This type is used to show the Global Trade Identifier Number (GTIN) for an external product.
"""
type ExternalProductIdentifier {
"""
The GTIN value of the external product, corresponding to the GTIN type specified in the **productType** field. This field will be returned as null if a GTIN was not provided for the external product.
"""
productId: String!
""" The GTIN type of the external product. `UPC`, `ISBN`, and `EAN` are the supported values. This field will be returned as null if a GTIN was not provided for the external product.
"""
productType: ExternalProductIdentifierEnum!
}
""" An enumerated type defining values for different external product types.
"""
enum ExternalProductIdentifierEnum {
"""
A European Article Number (EAN) is a unique 8 or 13-digit identifier code that identifies products worldwide.
The EAN values are typically used across Europe.
"""
EAN
"""
An International Standard Book Number (ISBN) is a unique numeric commercial book identifier.
Both 10 and 13-character ISBNs are supported.
"""
ISBN
"""
Manufacturer Part Number (MPN) values are currently not supported, so please don't specify this value in the **productType** field.
"""
MPN
"""
A Universal Product Code (UPC) is a unique numerical identifier for commercial products.
UPC values are typically used in the US and Canada.
"""
UPC
}
""" This type is used to provide a Global Trade Identifier Number (GTIN) for an external product.
"""
input ExternalProductIdentifierInput {
"""
The GTIN value of the external product, corresponding to the GTIN type specified in the **productType** field. The pattern of characters in this field should match the **productId** type.
"""
productId: String!
"""
The GTIN type of the external product. `UPC`, `ISBN`, and `EAN` are the supported values and one of these should be specified in this field.
"""
productType: ExternalProductIdentifierEnum!
}
""" A scalar representing a valid HTTP or HTTPS URL string value. """
scalar HttpOrHttpsUrl
"""
This type provides details of an external product that could not be used to create an eBay listing preview. Each invalid product includes a **description** field that explains why the external product details were unsuitable for creating a listing preview. The description is not localized and may change over time. This field is intended as a debugging aid for humans—-do not use **description** for client-side handling logic.
"""
type InvalidExternalProductDetails {
"""
The external product details originally provided through the mutation request.
"""
clientProvidedProductDetails: ExternalProductDetails!
"""
A human-readable description of why the external product details could not be used to create an eBay listing preview. This field is intended as a debugging aid for humans--do not use description for client-side handling logic.
"""
description: String!
}
scalar join__FieldSet
enum join__Graph {
AUCTIONBACKEND
BINSVC
BPVPSVC
BUYERMANAGEMENTSVC
CANCELSVC
CATSVC
COMMITMENTGRAPHSVC
E4CCHARITYUSER
E4CSEARCHEXPERIENCE
ECHOGQL
FGQLDOCS
FOLLOW
INVMAPPINGEXTSVC
ITEMCONDITIONPROXY
KETUPA
LASERVICE
LISTAPI
LISTINGAPIDEMO
LSAS
M2MCHATENTITYSVC
MEMBERSVC
OFFERBACKEND
ORDERPUBLICGRAPHSVC
PRODUCTSERVICE2
QUOTEGRAPHSVC
RETURNSVC
RMMSVC
STOREEDITENTITYSVC
SUBBENEFITSSVC
SVLS
UNILISTINGSVC
USERFEDGRAPH
USERNOTESVC
USERSSHOPPINGLIST
VIDEOSERVICES
}
scalar link__Import
enum link__Purpose {
"""
`SECURITY` features provide metadata necessary to securely resolve fields.
"""
SECURITY
"""
`EXECUTION` features provide metadata necessary for operation execution.
"""
EXECUTION
}
"""
This type shows the listing previews, and the external product details used to generate each of the listing previews. A listing preview provides recommended details for key fields to be used in an eBay listing, such as eBay product ID (if found), the title, the product description, the eBay category ID, one or more eBay Picture Service (ePS) image URLs, product aspect name-value pairs, and SKU (if provided).
A listing preview is neither a draft nor a live listing, but rather information generated from external product details that sellers can leverage when creating a listing in a subsequent step using eBay listing APIs.
"""
type ListingPreview {
"""
eBay's recommended product aspect name-value pairs for the product, or if an eBay catalog product was found, the product aspect name-value pairs associated with the catalog product.
"""
aspects: [ListingPreviewProductAspect!]
"""
eBay's recommended eBay leaf category in which to list the product, or if an eBay catalog product was found, the eBay leaf category associated with the catalog product. A null value signifies that the data is unavailable or undefined under certain exceptional conditions.
"""
category: Category
"""
This container shows the provided details of the external product that was mapped to an eBay listing preview.
"""
clientProvidedProductDetails: ExternalProductDetails!
"""
eBay's recommendation for the description of the product, or if an eBay catalog product was found, the description used for the catalog product. A null value signifies that the data is unavailable or undefined under certain exceptional conditions.
"""
description: String
"""
An array of one or more EPS image URLs that can be used with the listing. If images were provided through the **images** array in the mutation request, eBay returns the corresponding EPS image URLs. Additionally, if an eBay catalog product was matched for the external product, the field may also include the catalog product's stock photo URL(s). If no images are available, the array will be null.
"""
images: [HttpOrHttpsUrl!]
"""
The unique identifier of this listing preview. Use this 25-character ID when creating or revising a listing based on the listing preview via related APIs.
**Maximum length:** 25 characters
"""
mappingReferenceId: String!
"""
The eBay product ID (ePID) field under this container shows the eBay catalog product that the external product was matched to. An ePID value can be used in eBay listing APIs to prefill a listing with product title, product description, product aspects, stock photo(s), and eBay category. If the external product could not be mapped to an ePID, this field will be null.
"""
product: Product
"""
The seller-defined SKU of the external product. If the SKU was not provided for an external product, this field returns null.
"""
sku: String
"""
eBay's recommendation for the title of the product, or if an eBay catalog product was found, the title used for the catalog product. eBay listings only allow 80 characters for a listing title, so this recommended title may be shorter than the title provided for the external product. A null value signifies that the data is unavailable or undefined under certain exceptional conditions.
"""
title: String
}
"""
This type shows eBay's recommended product aspect name-value pairs for the product. Each aspect is defined by a name and a list of one or more values. The value in the **values.confidence** field will indicate how confident eBay is about that value being the right value for that corresponding aspect.
**Edge cases to consider**
While most aspects are expected to have a single value associated with it, some aspects may accept multiple values.
Please cross-reference aspect properties for any given category through the **Taxonomy APIs**.
For such aspects, multiple `PREFILL` values may be returned when available.
For example, an aspect could be `Color` with values like `Red`, `Blue`, and `Green` and confidence levels `PREFILL` or `HINT`.
"""
type ListingPreviewProductAspect {
"""An array of one or more values for the aspect."""
aspectValues: [String!]! @deprecated(reason: "This field is deprecated and has been superseded by the **values** array.")
"""The name of the aspect."""
name: String!
"""
An array that has one or more values for the corresponding aspect, and a **confidence** field that indicate how confident eBay is about indicate how confident eBay is about that value being the right value for that corresponding aspect
"""
values: [ListingPreviewProductAspectValue!]!
}
"""
This type shows the corresponding value(s) for an aspect and the confidence level that eBay has that a value is the right value for that aspect.
"""
type ListingPreviewProductAspectValue {
"""
The confidence level of the aspect value. See the **ListingPreviewProductAspectValueConfidenceEnum** type for descriptions of each supported value. This field will only be null under exceptional circumstances.
"""
confidence: ListingPreviewProductAspectValueConfidenceEnum
"""
The value of the aspect. This field will only be null under exceptional circumstances.
"""
value: String
}
"""
An enumerated type that represents the confidence level that eBay has that a recommended product aspect value is the correct one.
"""
enum ListingPreviewProductAspectValueConfidenceEnum {
"""
This value indicates a medium to high confidence threshold for the suggested aspect value, making sellers more likely to select one of the recommended or hinted values from a set.
"""
HINT
"""
This value indicates a high confidence threshold for the suggested aspect value, meaning sellers are more likely to select this prefilled value over other options, when this aspect value is prefilled.
"""
PREFILL
}
"""
This type shows the ID and the results of a listing previews task that was generated with the mutation request. This asynchronous task can take some time to complete. The listing preview results cannot be returned until the task is complete.
"""
type ListingPreviewsCreationTask {
"""
The unique identifier of the task. It is returned after a successful **StartListingPreviewsCreation** mutation.
**Max length**: 25
"""
id: ID!
"""
This container provides the status and results of the listing previews creation Task. It remains null until the task has completed execution.
"""
result: ListingPreviewsCreationTaskResult
}
"""
The base type of the **listingPreviewsCreationTaskById** query request, where the **id** value for a listing preview task is passed in.
"""
input ListingPreviewsCreationTaskByIdInput {
"""
The unique identifier of the listing preview task to retrieve. This **id** value is returned in the **StartListingPreviewsCreation** mutation response.
**Max length**: 25 characters
"""
id: ID!
}
"""
The base type of the **listingPreviewsCreationTaskById** query response. A successful query will return the **id** value for the task, and the listing preview results cannot be returned until the task is complete.
"""
type ListingPreviewsCreationTaskByIdOutput {
"""
If a **ListingPreviewsCreationTask** corresponding to the **requestId** value exists, it will be returned here.
If no task with the **requestId** exists, this field will be null.
"""
listingPreviewsCreationTask: ListingPreviewsCreationTask
"""
The unique identifier of the listing preview task that was passed into the query request.
**Max length** 25 characters
"""
requestedId: ID!
}
"""
This type is used to describe the outcome of a listing preview creation task.
"""
enum ListingPreviewsCreationTaskCompletionStatus {
"""
This enumeration value indicates that the task has completed successfully with no errors.
"""
COMPLETED
"""
This enumeration value indicates that the task has completed successfully, but with one or more errors. Issues that would lead to this status include one or more products being invalid and/or unmapped. The task may have still completed successfully for other products.
"""
COMPLETED_WITH_ERROR
"""
This enumeration value indicates that the task was not completed successfully, and no listing previews were generated for any of the external products.
"""
FAILED
}
"""
This type is used to show the final outcome of a listing previews creation task, and includes the completion status and the actual eBay listing previews. If applicable, unprocessed external products, unmapped external products, and invalid external products are displayed in separate arrays.
"""
type ListingPreviewsCreationTaskResult {
""" This enumeration value indicates the success or failure of the **StartListingPreviewsCreation** mutation. Applicable values are `COMPLETED`, `COMPLETED_WITH_ERROR`, or `FAILED`
"""
completionStatus: ListingPreviewsCreationTaskCompletionStatus!
""" An array of invalid external products that could not be processed. Each invalid product will include a **description** field that indicates why the external product details could not be used to create a listing preview. This field is intended to be a debugging aid for humans. The description is not localized and is subject to change. Do not use this description field for client-side handling logic. This array will be empty if there are no invalid products.
"""
invalidProducts: [InvalidExternalProductDetails!]!
""" This array will show the eBay listing previews that were successfully created based on the seller's provided external products. Each listing preview will contain the eBay product ID (if found), the title, the product description, the eBay category ID, one or more eBay Picture Service (ePS) image URLs, product aspect name-value pairs, and SKU (if provided). Additionally, this container will also have the **clientProvidedProductDetails** container that shows the client-provided details for the external products.
"""
listingPreviews: [ListingPreview!]!
""" An array of valid external products that were not successfully mapped by eBay into listing previews. These products should not be retried by the client. This array will be empty if there are no unmapped products.
"""
unmappedProducts: [ExternalProductDetails!]!
""" An array of external products that were not processed due to unforeseen circumstances. All of the details provided for each external product in the mutation request are returned under this array. Unprocessed external products can be included in a subsequent mutation request. This array will not be returned or will be null if there are no unprocessed products.
"""
unprocessedProducts: [ExternalProductDetails!]!
}
"""Mutation root"""
type Mutation {
"""
The **startListingPreviewsCreation** mutation initiates a process that leverages a seller’s provided external product data (maximum 10 products) and uses this data to create an eBay listing preview for each provided product. This asynchronous process can take some time to complete, which is partially dependent on the number of external products being processed. The **startListingPreviewsCreation** mutation includes details of the external products. The output of the mutation will include the status and ID of the task, and may include errors if there are any issues. Once the listing previews task is complete, the mutation response will also include the results of the listing preview.
The startListingPreviewsCreation mutation initiates a process that creates eBay Listing Previews from a seller's external products. This process is asynchronous and can take some time to complete. The mutation takes an input that includes details of the external products. The output of the mutation includes the details of the listing previews creation task and any errors that occurred during the process. This mutation is useful for sellers who want to convert their external products into eBay Listing Previews. The field will only be null when there is a server error prior to starting the preview creation process.
@authorize(scopes:[https://api.ebay.com/oauth/api_scope/sell.inventory.mapping&eBayUser])
Possible Errors:
| Code | Domain | Category | Parameters | Message |
|--------|-----------------------|-------------|------------------------|-----------------------------------------------------------------------------------------------------------|
| 500000 | API_INVENTORY_MAPPING | REQUEST | | Marketplace not supported. See documentation for supported marketplaces. |
| 500001 | API_INVENTORY_MAPPING | REQUEST | | Request cannot be empty. Please provide valid input. |
| 500002 | API_INVENTORY_MAPPING | APPLICATION | | Internal system error. Please try again later. |
| 500004 | API_INVENTORY_MAPPING | REQUEST | images | Invalid image URL. The URL must start with "https". |
| 500006 | API_INVENTORY_MAPPING | REQUEST | images | The provided URL is invalid or could not be resolved. Please check and provide a valid URL. |
| 500007 | API_INVENTORY_MAPPING | REQUEST | title | Title exceeds maximum allowed length: 250. |
| 500008 | API_INVENTORY_MAPPING | REQUEST | productId | Product ID is missing or has an invalid value. Check value and see documentation as necessary. |
| 500009 | API_INVENTORY_MAPPING | REQUEST | productType | Product type is missing or has an invalid value. See documentation for the supported GTIN types. |
| 500010 | API_INVENTORY_MAPPING | REQUEST | images | Duplicate image URLs were found under the images array. Please remove duplicates. |
| 500011 | API_INVENTORY_MAPPING | REQUEST | | You must provide a title or at least one image URL under the images array. |
| 500014 | API_INVENTORY_MAPPING | REQUEST | | You have exceeded the maximum number of products allowed: 10. |
| 500015 | API_INVENTORY_MAPPING | REQUEST | | All aspects.name fields must have corresponding values. |
| 500016 | API_INVENTORY_MAPPING | REQUEST | | All aspectValues arrays must have one or more corresponding values. |
| 500017 | API_INVENTORY_MAPPING | REQUEST | aspects.name | One or more duplicate aspect names were provided for the product. Please remove duplicates. |
| 500018 | API_INVENTORY_MAPPING | REQUEST | images | One or more image URLs exceed the maximum length allowed: 250. |
| 500019 | API_INVENTORY_MAPPING | REQUEST | aspects | You have exceeded the maximum number of aspects allowed: 50. |
| 500020 | API_INVENTORY_MAPPING | REQUEST | aspects.name | One or more image aspect names exceed the maximum length allowed: 100. |
| 500021 | API_INVENTORY_MAPPING | REQUEST | aspects.value | One or more image aspect values exceed the maximum length allowed: 100. |
| 500022 | API_INVENTORY_MAPPING | REQUEST | images | You have exceeded the maximum number of images allowed: 24. |
| 500023 | API_INVENTORY_MAPPING | REQUEST | externalProductDetails | One or more identical products found. Please check and revise or remove duplicates and try again. |
"""
startListingPreviewsCreation(input: StartListingPreviewsCreationInput!): StartListingPreviewsCreationOutput
}
"""
This type shows the eBay product identifier (ePID) of an eBay catalog product that was matched for the external product.
"""
type Product {
"""
The unique identifier of an eBay catalog product. An ePID value can be used in eBay listing APIs to prefill a listing with product title, product description, product aspects, stock photo(s), and eBay category.
"""
epid: Epid @deprecated(reason: "This field is deprecated and has been superseded by the **id** field.")
"""
The unique identifier of an eBay catalog product. An ePID value can be used in eBay listing APIs to prefill a listing with product title, product description, product aspects, stock photo(s), and eBay category.
"""
id: ID! @deprecated(reason: "Use 'productId' field instead")
"""Product aspects"""
aspects: [ProductAspect!]!
"""eBay site category metadata"""
category: Category!
"""Product image URLs"""
imageUrls: [String!]
"""Product ePID (eBay Product ID)"""
productId: ID!
"""Product title"""
title: String!
}
"""Product aspect"""
type ProductAspect {
""" A list of valid values for this aspect (for example: Red, Green, and Blue)
"""
aspectValues: [String!]!
""" The localized name of this aspect, this name is always localized for the specified marketplace
"""
displayName: String!
}
"""Query root"""
type Query {
"""
The listingPreviewsCreationTaskById query retrieves a ListingPreviewsCreationTask by ID. The data returned includes the task's status and results, including the listing previews created and any products not processed, unmapped, or invalid. Use this query to check task status or obtain the results of converting a seller's external products into eBay listing previews.
You can call this query immediately after submitting the startListingPreviewsCreation mutation to check the task's status. However, if that mutation has not completed, the query may return a null or an incomplete result.
@authorize(scopes:[https://api.ebay.com/oauth/api_scope/sell.inventory.mapping&eBayUser])
Possible Errors:
| Code | Domain | Category | Parameters | Message |
|--------|-----------------------|-------------|------------|-----------------------------------------------------------------------------|
| 500000 | API_INVENTORY_MAPPING | REQUEST | | Marketplace not supported. See documentation for supported marketplaces. |
| 500001 | API_INVENTORY_MAPPING | REQUEST | | Request cannot be empty. Please provide valid input. |
| 500002 | API_INVENTORY_MAPPING | APPLICATION | | Internal system error. Please try again later. |
| 500003 | API_INVENTORY_MAPPING | REQUEST | id | Invalid Task ID. Please provide a valid ID. |
"""
listingPreviewsCreationTaskById(input: ListingPreviewsCreationTaskByIdInput!): ListingPreviewsCreationTaskByIdOutput
}
"""
This type is used to show any errors that occurred during the execution of a mutation or query.
"""
type StartListingPreviewsCreationError {
"""
A description of an error that occurred while executing a mutation or query. This field is intended to be a debugging aid for humans. The description is not localized and is subject to change. Do not use these error descriptions for client-side error handling logic.
"""
errorDescription: String!
}
"""
This is the base type for the **startListingPreviewsCreation** mutation. It contains an array of **externalProducts** that need to be converted into eBay listing previews.
"""
input StartListingPreviewsCreationInput {
"""
This array is used to provide details of external products. Product details include title, images, product identifiers, product aspects, category name, and SKU value. In order to successfully identify an external product, at least one of the following three fields must be used:
* title
* image
* product id only (UPC, ISBN, or EAN)
Include as many fields as possible to increase chances of creating higher-quality eBay listing previews. For example, including title, images, category name, and aspects is better than just including title and images. A SKU is optional, but it is highly recommended as it acts as a key to track/identify different external products.
"""
externalProducts: [ExternalProductDetailsInput!]
}
"""
The base type of the **startListingPreviewsCreation** mutation response. A successful mutation will return the **id** value for the task, and the listing preview results cannot be returned until the task is complete.
"""
type StartListingPreviewsCreationOutput {
"""
An array of one or more errors that may have been triggered with the mutation request. This field will be returned as null if there are no errors.
"""
errors: [StartListingPreviewsCreationError!]
"""
This base response container should be returned with a successful mutation, but the listing preview results cannot be returned until the task is complete.
"""
listingPreviewsCreationTask: ListingPreviewsCreationTask
}