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 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 prideAndPrejudice = {
    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"
};

Get a product from the catalog

In the Buy with Prime catalog, each product is represented by a MappingProduct. The MappingProduct 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 mappingProduct($identifier: ItemIdentifierInput) {
    mappingProduct(identifier: $identifier) {
      productExternalId {
        value
      }
      productSku {
        value
      }
      productMsku {
        value
      }
      isPrimeIntended
      url
      image {
        sourceUrl
      }
    }
  }
}

// Query variables
{
  identifier: {
    SKU: inSearchOfLostTime.sku
  }
}
Response 
{
  "data": {
    "mappingProduct": {     
      "productExternalId": "12345",
      "productSku": "12345",
      "productMsku": "12345",   
      "isPrimeIntended": true,      
      "url": "https://www.amazon.com/dp/1234567",
      "image": "https://example.com/image-12345.jpg"
    }
  }
}

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 get the buyability status for a product.

Request 
// GraphQL query
query {
    mappingProduct(identifier: $identifier)
    {
        productExternalId {
            value
        }
        buyability {
            status
        }
    }
}`;

// Query variables
{
  identifier: {
    SKU: inSearchOfLostTime.sku
  }
}
Response 
{
    "data": {
        "mappingProduct": {
            "productExternalId": {
                "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 {
    mappingProduct(identifier: $identifier)
    {
        productExternalId {
            value
        }        
        inventoryItem {
            inventoryItemId
            buyableQuantity {
                unit
                amount
            }
        }
    }
}`;

// Query variables
{
  identifier: {
    SKU: inSearchOfLostTime.sku
  }
}
Response 
{
  "data": {
    "mappingProduct": {
      "productExternalId": {
        "value": "12345"
      },
      "inventoryItem": {
        "inventoryItemId": "example-inventory-item-id",
        "buyableQuantity": {
          "unit": "UNIT",
          "amount": 0
        }
      }
    }
  }
}

Related topics

Updated 3 days ago