Buy with Prime | Developer Documentation
Documentation

Query 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

After you upload your catalog to Buy with Prime, you can query products in the catalog. The following examples show how to query products for different attributes. For details on querying variation group fields, see Create and Manage Product Variations. For details on querying product purchase group fields, see Create and Manage Purchase Groups.

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",
    offerPrime: true,
    sku: "12345",
    amazonSku: "12345",
    imageUrl: "https://example.com/image-12345.jpg",
    detailPageUrl: "https://www.amazon.com/dp/12345",
    description: {
      values: [
        {
          value: "This is the book In Search of Lost Time",
          locale: "en-US"
        },
        {
          value: "À la recherche du temps perdu",
          locale: "fr-FR"
        }
      ],
      defaultLocale: "en-US"
    }
};

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",
    description: {
      values: [
        {
          value: "<p>This is the book Pride and Prejudice</p>",
          locale: "en-US"
        }
      ],
      defaultLocale: "en-US"
    }
};

Get a product from the catalog

In the Buy with Prime catalog, each product is represented by a Product. The Product contains the product IDs and attributes that you specified for the product when you uploaded the catalog. The following example shows how to query a product in the catalog by using the product's SKU.

Request 
// GraphQL query
query product($identifier: ProductIdentifierInput) {
    product(identifier: $identifier) {
      externalId {
        value
      }
      sku {
        value
      }
      amazonSku {
        value
        marketplaceId
      }
      offerPrime
      productDetailPageUrl
      image {
        sourceUrl
      }
      description {
        values {
          value
          locale
        }
        defaultLocale
      }
    }
  }
}

// Query variables
{
  identifier: {
    sku: inSearchOfLostTime.sku
  }
}
Response 
{
  "data": {
    "product": {     
      "externalId": {
        "value": "12345"
      },
      "sku": {
        "value": "12345"
      },
      "amazonSku": {
        "value": "12345"
      },   
      "offerPrime": true,      
      "productDetailPageUrl": "https://www.amazon.com/dp/1234567",
      "image": {
        "sourceUrl": "https://example.com/image-12345.jpg"
      },
      "description": {
        "values": [
          {
            "value": "This is the book In Search of Lost Time",
            "locale": "en-US"
          },
          {
            "value": "À la recherche du temps perdu",
            "locale": "fr-FR"
          }
        ],
        "defaultLocale": "en-US"
      }
    }
  }
}

Get a list of products from the catalog

The following example shows how to query a list of products from the catalog.

Request 
//GraphQL query
query products(
    $first: Int
    $after: String
) {
    products(first: $first, after: $after) {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        edges {
            cursor
            node {
                id
                ... on Product {
                    id
                    externalId {
                        value
                    }
                    sku {
                        value
                    }
                    amazonSku {
                        marketplaceId
                        value
                    }
                    offerPrime
                    productDetailPageUrl
                    image {
                        displayReadyUrl
                        sourceUrl
                    }
                    description {
                      values {
                        value
                        locale
                      }
                      defaultLocale
                    }
                }
            }
        }
    }
Response 
{
  "data": {
    "products": {
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": true,
        "startCursor": "example-id-2",
        "endCursor": "example-id-3"
      },
      "edges": [
        {
          "cursor": "example-id-2",
          "node": {
            "id": "example-id-2",
            "externalId": {
              "value": "example-external-id-2"
            },
            "sku": {
              "value": "example-sku-2"
            },
            "amazonSku": {
              "marketplaceId": null,
              "value": "example-amazonSku-2"
            },
            "offerPrime": true,
            "productDetailPageUrl": "https://example.com/products/id2",
            "image": {
              "displayReadyUrl": "https://example.com/product-image-display.jpeg",
              "sourceUrl": "https://example.com/product-image.jpeg"
            },
            "description": {
              "values": [
                {
                  "value": "<p>This is the description for example-id-2</p>",
                  "locale": "en-US"
                }
              ],
              "defaultLocale": "en-US"
            }
          }
        },
        {
          "cursor": "example-id-3",
          "node": {
            "id": "example-id-3",
            "externalId": null,
            "sku": {
              "value": "example-sku-3"
            },
            "amazonSku": null,
            "offerPrime": false,
            "productDetailPageUrl": null,
            "image": null,
            "description": null
          }
        }
      ]
    }
  }
}

Get a list of products from a catalog using pagination

Use the first and after input fields to navigate pages of product results. The first input field dictates the number of items to return in a page, with a default of 20 if not specified. The after input field returns any products listed after the pageInfo.endCursor provided.

Enter a null value for the after field to view the first page of product results, or a pageInfo.endCursor from a prior page of products to see a subsequent page. Use cursor values immediately, as they are short-lived.

The following example queries the first two products after the query shown in Get a list of products from the catalog.

Request 
query products() {
    products(first: 2, after: "example-id-2") {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        edges {
            cursor
            node {
                id
                ... on Product {
                    id
                    externalId {
                        value
                    }
                    sku {
                        value
                    }
                    amazonSku {
                        marketplaceId
                        value
                    }
                    offerPrime
                    productDetailPageUrl
                    image {
                        displayReadyUrl
                        sourceUrl
                    }
                    description {
                      values {
                        value
                        locale
                      }
                      defaultLocale
                    }
                }
            }
        }
    }
Response 
{
  "data": {
    "products": {
      "pageInfo": {
        "hasNextPage": false,
        "hasPreviousPage": true, 
        "startCursor": "example-id-4",
        "endCursor": "example-id-5"
      },
      "edges": [
        {
          "cursor": "example-id-4",
          "node": {
            "id": "example-id-21",
            "externalId": {
              "value": "example-external-id-21"
            },
            "sku": {
              "value": "example-sku-21"
            },
            "amazonSku": {
              "marketplaceId": null,
              "value": "example-amazonSku-21"
            },
            "offerPrime": true,
            "productDetailPageUrl": "https://example.com/products/id21",
            "image": {
              "displayReadyUrl": "https://example.com/product-image-display.jpeg",
              "sourceUrl": "https://example.com/product-image.jpeg"
            },
            "description": {
              "values": [
                {
                  "value": "This is the description for example-id-21",
                  "locale": "en-US"
                }
              ],
              "defaultLocale": "en-US"
            }
          }
        },
        {
          "cursor": "example-id-5",
          "node": {
            "id": "example-id-22",
            "externalId": null,
            "sku": {
              "value": "example-sku-22"
            },
            "amazonSku": null,
            "offerPrime": false,
            "productDetailPageUrl": null,
            "image": null,
            "description": null
          }
        }
      ]
    }
  }
}

Get a filtered list of products from a catalog

Filters allow you to reduce the number of products returned when you query a catalog by targeting specific categories of products. If you use a filter, the query returns a maximum of 15,000 products. If you do not use a filter, the query returns all products in the catalog. For details on filtering options, see Filter options.

The following example returns only products that are eligible for Buy with Prime.

Request 
query products(
    $first: Int
    $after: String
) {
    products(
      first: $first,
      after: $after,
      filter: { offerPrime: { eq: true } }
    ) {
        pageInfo {
            hasNextPage
            hasPreviousPage
            startCursor
            endCursor
        }
        edges {
            cursor
            node {
                id
                ... on Product {
                    id
                    externalId {
                        value
                    }
                    sku {
                        value
                    }
                    amazonSku {
                        marketplaceId
                        value
                    }
                    offerPrime
                    productDetailPageUrl
                    image {
                        displayReadyUrl
                        sourceUrl
                    }
                    description {
                      values {
                        value
                        locale
                      }
                      defaultLocale
                    }
                }
            }
        }
    }
Response 
{
  "data": {
    "products": {
      "pageInfo": {
        "hasNextPage": true,
        "hasPreviousPage": false,
        "startCursor": "catalogid#example-id-1",
        "endCursor": "catalogid#example-id-2"
      },
      "edges": [
        {
          "cursor": "catalogid#example-id-1",
          "node": {
            "id": "example-id-1",
            "externalId": {
              "value": "example-external-id-1"
            },
            "sku": {
              "value": "example-sku-1"
            },
            "amazonSku": {
              "marketplaceId": null,
              "value": "example-amazonSku-1"
            },
            "offerPrime": "true",
            "productDetailPageUrl": "https://example.com/products/id1",
            "image": {
              "displayReadyUrl": "https://example.com/product-image-display.jpeg",
              "sourceUrl": "https://example.com/product-image.jpeg"
            },
            "description": {
              "values": [
                {
                  "value": "This is the description for example-id-1",
                  "locale": "en-US"
                }
              ],
              "defaultLocale": "en-US"
            }
          }
        }
      ]
    }
  }
}

Query filters support both AND and OR logic. A query containing multiple filter fields defaults to searching for products that satisfy both filters, except for fields that you include within an OR filter.

The following example shows an AND filter query.

filter: {
    hasImage: { isNull: true }
    amazonSku: { eq: "example-amazonSku-1" }
}

The following example shows an OR filter query.

filter: {
    OR:[
        {
            hasImage: { eq: true } 
        },
        {
            offerPrime: { eq: false }
        }
    ]
}

The following example shows a combination of AND and OR filter queries.

filter: {
    hasProductDetailPageUrl: { eq: true }
    amazonSku: { eq: "example-amazonSku-1" }
    OR:[
        {
            hasImage: { eq: true } 
        },
        {
            offerPrime: { eq: false }
        }
    ]
}

Filter options

Filter typeInput typeFilter syntax
Product IDStringid: { eq: "exampleId" }
SKUStringsku: { eq: "exampleSku" }
Amazon SKUStringamazonSku: { eq: "exampleAmazonSku" }
External IDStringexternalId: { eq: "exampleExternalId" }
Has imageBooleanhasImage: { eq: false }
Has product detail page URLBooleanhasProductDetailPageUrl: { eq: false }
Eligible for Buy with PrimeBooleanofferPrime: { eq: false }
Representative of variation groupBooleanisRepresentativeOfVariationGroup: { eq: false }
Variation group memberBooleanisVariationGroupMember: { eq: false }
Representative of purchase groupBooleanisRepresentativeOfPurchaseGroup: { eq: false }
Purchase group memberBooleanisPurchaseGroupMember: { eq: false }

Get the buyability status of a product

Buyability is a determination of whether the product is eligible for Buy with Prime. You can get the buyability status of a product synchronously by using the Catalog interface, or asynchronously by using events.

For a newly added product, it can take up to 30 minutes for the product to have the correct buyability status.

When a product's buyability status is BUYABLE and the product is eligible for Buy with Prime, display the Prime badge for the product. Don't display the Prime badge for a product if the buyability status is NOT_BUYABLE or the product isn't eligible for Buy with Prime.

The following example shows how to get the buyability status for a product.

Request 
// GraphQL query
query {
    product(identifier: $identifier)
    {
        externalId {
            value
        }
        buyability {
            status
        }
    }
}

// Query variables
{
  identifier: {
    sku: inSearchOfLostTime.sku
  }
}
Response 
{
    "data": {
        "product": {
            "externalId": {
                "value": "12345"
            },
            "buyability": {
                "status": "BUYABLE"
            }
        }
    }
}

Get the available inventory of a product

The following example shows how to get the available inventory for a product. For the fields, see InventoryItem.

Request 
// GraphQL query
query {
   product(identifier: $identifier)
    {
        externalId {
            value
        }        
        inventoryItem {
            inventoryItemId
            fulfillableQuantity {
                unit
                amount
            }
        }
    }
}

// Query variables
{
  identifier: {
    sku: inSearchOfLostTime.sku
  }
}
Response 
{
  "data": {
    "product": {
      "externalId": {
        "value": "12345"
      },
      "inventoryItem": {
        "inventoryItemId": "example-inventory-item-id",
        "fulfillableQuantity": {
          "unit": "UNIT",
          "amount": 0
        }
      }
    }
  }
}

Related topics

Updated 7 days ago