📘

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

Elements are web components that you can add to your site to get information from the Buy with Prime API and display it as HTML. To add an element to your site, include a script tag in your page header that connects to the Buy with Prime API with your target ID, and then embed the element tag where you want the component to appear. You can also configure the element to display information for specific products through product ID references, and customize its appearance with element-specific attributes.

Prerequisites

To use elements, your organization must have the following prerequisites:

• Your own ecommerce site.
• A professional Seller Central account or an Amazon Supply Chain account.
• A Buy with Prime account. For information about the Buy with Prime account associated with your site, see your ecommerce manager.
• Populate your Buy with Prime catalog with products. After you populate your Buy with Prime catalog, you can query inventory levels for any products in your catalog, regardless of whether the products offer Buy with Prime.
• Each element uses a target ID to connect to your Buy with Prime sales channel. For details about how to get your target ID, see Generate API credentials.
• Identify which domains to allow Buy with Prime to display elements on. On the Buy with Prime merchant console, under Settings, choose Domains, and then add your domains. For example, you might add your website domain, testing domains, and localhost.

Step 1: Add the script tag

In the header of the page, add a script tag that references the following:

• The JavaScript file that contains the element source, hosted by Amazon. You can find the location of the file in the element reference pages. For details, see Elements Reference.

• Your target ID. For details, see the prerequisites.

  HTML

  <script data-target-id="[YOUR-TARGET-ID]" async type="module" src="[ELEMENT-SOURCE-JS]">
  </script>
  

Step 2: Add the element tag

In the body of the page where you want the element to appear, add the element tag.

To indicate which item an element refers to, set one of the following product ID attributes on the element tag:

• product-external-id: An identifier from your ecommerce platform.
• product-id: A Buy with Prime generated product ID.
• product-sku: A SKU from your ecommerce platform.

If you provide an invalid product ID, the element doesn't render. You can also optionally specify a marketplace by using the product-marketplace-id attribute, which is set to US by default.

Step 3: (Optional) Handle product variants

When a shopper changes their selection between variants of a product, do one of the following:

• For a site that doesn't use Shopify, use a JavaScript hook that listens for a product variant change event. The following example shows how to set all elements that have a product ID to the new variant.

  JavaScript

  window.addEventListener("YourVariantChangeEvent", (event) => {
     
     /* Add error guards such as:
        if(!event.detail.externalId) throw new Error("variantEventChange event is missing externalId property")
        */
     
     // Select the elements to update
     const elements = document.querySelectorAll("[amazon-delivery-card],[amazon-delivery-message]");
     /* Alternatively, add a custom data attribute such as `data-amazon-pdp-element`
        to the elements you want to update, and then select the elements by attribute:
        const elements = document.querySelectorAll("[data-amazon-pdp-element]");
        */
  
     // Update the elements with the new product ID
     elements.forEach((element) => {
        element.setAttribute("product-external-id",event.detail.productId )
     })
  
  });
  

• For a site that uses Shopify, use the following attributes in the element tag.

  Attribute	Value	Description
  provider	"shopify"	Sets the ecommerce service provider.
  variant-helper	"true" "false"	Determines whether the element automatically updates when a shopper selects a new variant on a product detail page. The default is "true".

Step 4: Change the appearance of the element

Each element has attributes you can use to change the appearance of the element, for example the color and font. For details, see the individual element pages under Elements Reference.

Related topics

• Elements Overview
• Delivery Card Element
• Delivery Message Element
• Sign-In Card Element