Upload a Catalog
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.
The following examples show you how to upload a catalog.
Perform these operations in the following order:
- Create a catalog feed file.
- Create an upload link.
- Upload a catalog feed file.
- Start feed processing.
After you start feed processing, you can get the result of the catalog upload and query the catalog.
For an overview of catalog terminology, see Create and Manage Catalogs. To learn how to call the Buy with Prime API, see Call the Buy with Prime API.
Sample data
The examples in this topic use the following sample data.
Sample catalog data
let inSearchOfLostTime = {
title: "In Search of Lost Time",
isbn: "12345",
isPrimeIntended: true,
sku: "12345",
mSku: "12345",
imageUrl: "https://example.com/image-12345.jpg",
detailPageUrl: "https://www.amazon.com/dp/12345"
};
let inSearchOfLostTime = {
title: "Pride and Prejudice",
isbn: "678910",
isPrimeIntended: true,
sku: "678910",
mSku: "678910",
imageUrl: "https://example.com/image-678910.jpg",
detailPageUrl: "https://www.amazon.com/dp/678910"
};
Step 1: Create a catalog feed file
Before you can upload your catalog, you must put your product details in a CSV catalog feed file. For the required format of the catalog feed file, download the template. For details on the fields, see Catalog feed file.
You can create the catalog feed file in different ways: by hand, by exporting from an existing catalog system, or by using a program.
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. | String | Yes but leave it empty | No |
SKU | Stock keeping unit. | String | Yes | No |
Amazon SKU | Amazon SKU on Amazon Seller Central or 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 image 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 |
The following example shows a feed file for the sample data shown previously.
Feed file
"External ID","Updated External ID","SKU","Amazon SKU","Offer Prime","Image URL","Product Detail Page URL"
"12345","","12345","12345",true,"https://example.com/image-12345.jpg","https://www.amazon.com/dp/1234567"
"678910","","678910","678910",true,"https://example.com/image-678910.jpg","https://www.amazon.com/dp/678910"
Step 2: Create an upload link
Before you upload a catalog feed file, you must create an upload link by calling the createUploadLink
mutation. The returned upload link is a single-use privileged URL that expires in two minutes.
The response includes an uploadUrl
and a fileId
. Save both of these values. You use the URL when you upload the catalog feed file. Later, when you start feed processing, you need the fileId
.
The following example shows how to create an upload link.
Request
// GraphQL mutation
mutation CreateUploadLink($input: UploadLinkInput!) {
createUploadLink(input: $input) {
uploadUrl
fileId
}
}
// Mutation variables
{
input: {
fileExtension: "CSV",
size: feedFileSizeBytes
}
}
Response
{
data: {
uploadUrl: "http://example.com.example-upload-url",
fileId: "example-file-id"
}
}
Step 3: Upload a catalog feed file
After you create an upload link, you can upload your catalog feed file by using a standard interface in your chosen programming language. The uploaded file is deleted after 30 days.
The following example shows how to upload a feed file by using JavaScript.
Request
// Extract the upload link from the mutation result.
let uploadUrl = createUploadLinkResponseJson.data.uploadUrl;
// Using the upload link, upload the catalog feed File
const uploadResponse =
await fetch(uploadUrl, {
method: 'PUT',
body: feedFile
});
Step 4: Start feed processing
After you upload the catalog feed file, you can start feed processing by calling the createCatalogFeed
mutation. As an input parameter, you supply the fileId
from the response you received when you created the upload link. Feed processing takes an average of one minute per 100 items.
Save the id
from the response so that you can query the result of the upload.
The following example shows how to start feed processing.
Request
// GraphQL query
mutation CreateCatalogFeed($input: CreateCatalogFeedInput) {
createCatalogFeed(input: $input) {
id
}
}
// Mutation variables
{
input: {
dataProvider: {
uploadedFile: {
fileId: createUploadLinkResponseJson.data.fileId
}
},
configuration: {
// Setting overwriteExistingProducts to false as we're only uploading a file with
// new products or failed products from previous upload attempts.
overwriteExistingProducts: false
}
}
}
Response
{
data: {
createCatalogFeed: {
id: "example-catalog-field-id"
}
}
}
Step 5: Get the result of the upload
To retrieve the results, see Get the Result of a Catalog Upload.
Related topics
Updated 6 days ago