Buy with Prime | Developer Documentation
Documentation

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.

Sign Up

You use the Buy with Prime Catalog interface to create and update products. The following examples show you how to upload a catalog.

Perform these operations in the following order:

  1. Create a catalog feed file.
  2. Create an upload link.
  3. Upload a catalog feed file.
  4. 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 Catalog Interface. 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",
    offerPrime: true,
    sku: "12345",
    amazonSku: "12345",
    imageUrl: "https://example.com/image-12345.jpg",
    detailPageUrl: "https://www.amazon.com/dp/12345"
};

let prideAndPrejudice = {
    title: "Pride and Prejudice",
    isbn: "678910",
    offerPrime: true,
    sku: "678910",
    amazonSku: "678910",
    imageUrl: "https://example.com/image-678910.jpg",
    detailPageUrl: "https://www.amazon.com/dp/678910"
};

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 information about 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 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"

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) {
      payload {
        uploadUrl
        fileId
      }
    }
  }

// Mutation variables  
{
  input: {
    fileType: "CSV",
    size: feedFileSizeBytes
  }
}
Response 
{
  data: {
    payload {
      uploadUrl: "http://example.com/example-upload-url",
      fileId: "example-file-id"
    }
  }
}

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.payload.uploadUrl;

// Using the upload link, upload the catalog feed File
const uploadResponse =
  await fetch(uploadUrl, {
    method: 'PUT',
    body: feedFile
  });

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.payload.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"
    }
  }
}

Related topics

Updated 23 days ago