Create and Manage Catalogs
Buy with Prime API is now available for early access
Sign up for early access to the Buy with Prime API using the 'Sign Up' button below. The API may change as Amazon receives feedback and iterates on it.
Before you can offer Buy with Prime, you must populate the Buy with Prime catalog with products. You can add products to your Buy with Prime catalog in two ways:
- You can upload a CSV file that contains your product information, which supports up to 15,000 products per upload. For examples, see Upload a Catalog.
- You can upload products one by one. For examples, see Create and Manage Products in a Catalog.
You can also create new products, update existing products, or delete products from the catalog. After you create products, you can query and retrieve information associated with those products.
For example requests and responses, see:
- Create and Manage Products in a Catalog
- Upload a Catalog
- Get the Result of a Catalog Upload
- Query a Catalog
Terminology
The following sections describe catalog terminology and match each term to its programming construct.
Product
| Description | An item that shoppers can purchase. Each product in the Buy with Prime catalog is associated with attributes (such as a link to the product detail page, the quantity of the item in inventory, and so on) and one or more product identifiers that uniquely identify the product within a specific context. When you interact with the Buy with Prime API, each product is represented by a |
| Associated programming construct | A Product ties together the different attributes and product identifiers assigned to a product. |
| Notes | To upload products to the Buy with Prime catalog, you first put your product details in a CSV file and then upload it. For details, see Upload a catalog. You can also upload products individually. For details, see Create and Manage Products in a Catalog. |
Product attribute
| Description | A piece of information associated with a product. Products have the following attributes:
|
| Associated programming construct | A Product ties together the different attributes and product identifiers assigned to a product. |
| Notes | N/A |
Product identifier
| Description | A unique identifier that identifies the product within a specific context. You can use any of the product identifiers when interacting with the API. Buy with Prime business processes also use identifiers, for example, when an order is fulfilled. There are four types of product identifiers, described later in this topic: |
| Associated programming construct | A Product ties together the different product identifiers assigned to a product. |
| Notes | Each Buy with Prime item can have more than one product identifier. For example, in addition to the id that Buy with Prime assigns the item, you might specify an external ID that corresponds to a listing ID on your end. |
Buy with Prime product ID
| Definition | The unique identifier for a product in the Buy with Prime catalog. Buy with Prime assigns this ID when you upload a product. |
| Associated programming construct | id field, of type ID, within a Product. |
| Notes | You don't need to rely on this identifier or store it in your system. Rely on your own identifiers (such as external product ID) instead. |
External product ID
| Definition | A unique, user-provided product ID that uniquely identifies a product in the Buy with Prime catalog. You provide this ID when you upload a product. |
| Associated programming construct | externalId field, of type ExternalProductIdentifier, within a Product. |
| Notes | You can use this ID to store any of your own identifiers, such as a listing ID. We recommend that you use this identifier when you interact with the Buy with Prime API so that you don't need to store any Buy with Prime product identifiers. |
SKU assigned by your service
| Definition | A unique, user-provided stock keeping unit (SKU) ID that uniquely identifies a physical item in your system. You provide this ID when you upload a product. |
| Associated programming construct | productSku field, of type SkuProductIdentifier, within a Product. |
| Notes | SKUs are usually human-readable, which can be useful to quickly identify your product in a report. You can choose to interact with the API using the product's SKU instead of the product's external ID. |
Amazon SKU
| Definition | The unique Amazon SKU, specified in Seller Central or Supply Chain Portal, that identifies a product in Amazon’s fulfillment systems. This SKU is often called mSKU. |
| Associated programming construct | amazonSku field, of type AmazonSkuProductIdentifier, within a Product. |
| Notes | This identifier is used during delivery preview generation and fulfillment. |
Catalog feed
| Definition | A bulk data import operation of Buy with Prime products. |
| Associated programming construct | CatalogFeed |
| Notes | To create a catalog feed, you first put your product details in a CSV file, and then upload the file. For details, see Upload a Catalog. |
Catalog feed file
A CSV file of products that you upload to the Buy with Prime catalog. The uploaded CSV file is deleted after 30 days. For the required format of the feed file, download the template.
The following table shows the fields that the CSV file must contain. Note that the field requirements differ depending on whether this upload is the first listing for a product or you are re-uploading information for an existing listing.
You must put the headers (field names) as the first row of the CSV file, or the upload will fail.
| Field | Description | Type | Required? | Required for Re-listing? |
|---|---|---|---|---|
| External ID | A unique external product identifier that you provide. This identifier can be the same as the SKU. | String | Yes | Yes |
| Updated External ID | Only used for re-listing, so leave this empty initially. When re-listing, specify the Updated External ID if you want to change the current External ID. | String | No | No |
| SKU | Stock keeping unit. | String | Yes | No |
| Amazon SKU | Amazon SKU on seller central/supply chain portal. | String | Yes | No |
| Offer Prime | Whether to offer Prime for this product. Allowed values: true or false. Default value: false. | Boolean | No | No |
| Image URL | Link to product image. Buy with Prime uses the product image for the post-order user experience. | String | Yes | No |
| Product Detail Page URL | Link to product detail page. Buy with Prime links to the product in the post-order user experience. | String | No, but you must have this URL to enable Prime | No, but you must have this URL to enable Prime |
Catalog feed signal
| Definition | A signal that something has occurred that you must fix. |
| Associated programming construct | Signal |
| Notes | The catalogFeed query returns a Signal when an error prevents the processing of the catalog feed file. |
Catalog feed processing result file
The result of a feed upload in CSV format. When a catalog feed file finishes processing, the result report indicates the success or failure of applying the update from each row of the input catalog feed file. For instructions on how to download the report, see Get the Result of a Catalog Upload.
The report has the following fields.
| Field | Description |
|---|---|
| Import Result | The result of the upload. |
| Error Type | The type of error that occurred. |
| Error Code(s) | The code of the error that occurred. |
| Error Detail(s) | Details about the error. |
| External ID | A unique external product identifier. This identifier can be the same as the SKU. |
| Updated External ID | Only used for re-listing, so leave this empty initially. When re-listing, specify the Updated External ID if you want to change the current External ID. |
| SKU | Stock keeping unit. |
| Amazon SKU | Amazon SKU on seller central/supply chain portal. |
| Offer Prime | Whether to offer Prime for this product. |
| Image URL | Link to product image. |
| Product Detail Page URL | Link to product detail page. |
API operations
You use the following mutations, queries, and events to create and manage catalogs.
Mutations
| Name | Description |
|---|---|
createCatalogFeed | Creates a catalog feed, which represents a bulk data import operation of Buy with Prime products. |
createUploadLink | Gets a temporary upload URL for uploading a catalog feed file. After the file is uploaded, you can pass the returned fileId to other Buy with Prime API operations to further process the uploaded file. |
createProduct | Create a new product within your Buy With Prime catalog. |
updateProduct | Update an existing product in your Buy With Prime catalog. |
deleteProduct | Delete an existing product from your Buy With Prime catalog. |
Queries
| Name | Description |
|---|---|
catalogFeed | Gets a catalog feed, which represents a bulk data import operation of Buy with Prime products. |
downloadLink | Gets a temporary URL that you use to download files using file IDs returned by Buy with Prime operations such as the catalogFeed query. |
inventoryItem | Gets an inventory item by using a Buy With Prime inventory identifier. |
product | Returns a product, which holds the product identifier mapping between an e-commerce platform and Amazon's fulfillment systems. |
products | Returns a ProductConnection, which holds a list of edges that contain a product. For details about edges, see Pagination in the GraphQL documentation. |
Events
| Event | When Event is Published |
|---|---|
BUYABILITY_CHANGED | An item that was previously eligible for Buy with Prime is no longer eligible for Buy with Prime, or vice versa. |
INVENTORY_CHANGED | An item's inventory level changes or an item has an error that requires merchant action. |
Related topics
Updated 4 days ago