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 use the Catalog interface to upload your catalog to Buy with Prime, you can use the Buy with Prime Catalog interface to query products in the catalog. The following examples show how to query products for different attributes.

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"
};

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
      }
    }
  }
}

// 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"
      }
    }
  }
}

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
                    }
                }
            }
        }
    }
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"
            }
          }
        },
        {
          "cursor": "example-id-3",
          "node": {
            "id": "example-id-3",
            "externalId": null,
            "sku": {
              "value": "example-sku-3"
            },
            "amazonSku": null,
            "offerPrime": false,
            "productDetailPageUrl": null,
            "image": null
          }
        }
      ]
    }
  }
}

Get the buyability status of a product

Buyability is a determination of whether you successfully set up a product to be purchasable by eligible shoppers through 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 you offer Buy with Prime for the product, you should render Prime badging for the product. When a product's buyability status is NOT_BUYABLE or you don't offer Buy with Prime for the product, you shouldn't render Prime badging for the product.

The following example shows how to use the Catalog interface 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 23 days ago