Terminology

📘

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.

This topic describes terminology that you encounter as you integrate with Buy with Prime.

Product

A product is an item that shoppers can purchase. Each product in the Buy with Prime catalog is associated with product attributes (such as a link to the product detail page, the quantity of the item in inventory, and so on) and one or more product identifiers that uniquely identify the product within a specific context.

When you interact with the Buy with Prime API, each product is represented by a mapping that contains the product's attributes and IDs. For details about how to upload product information to the Buy with Prime catalog, see Create and Manage Catalogs.

Product attribute

A product attribute is a piece of information associated with a product. Products have the following attributes:

  • Product detail page URL: A link to the product detail page.
  • Image URL: A link to the product image.
  • Inventory: Available inventory.
  • Is Prime intended: Whether the product is intended to be eligible for Prime.
  • Buyability: A determination of whether a product is eligible for Buy with Prime.

Product identifier

A product identifier is a unique identifier that identifies a product within a specific context. You can use any of the product identifiers when interacting with the Buy with Prime API. Buy with Prime business processes also use identifiers, for example, when an order is fulfilled. There are four types of product identifiers, described in the following sections:

Buy with Prime product ID

A Buy with Prime product ID is a unique identifier for a product in the Buy with Prime catalog. Buy with Prime assigns this ID when you upload a catalog. You don't need to rely on this identifier or store it in your system. Rely on your own identifiers (such as external product ID) instead.

External product ID

An external product ID or external ID is a product identifier that you, rather than Amazon, provide. External IDs must be unique in a catalog. An example of an external ID is a listing ID. You can use this identifier when you interact with the Buy with Prime API to avoid having to store Buy with Prime product identifiers.

Amazon SKU

An Amazon stock keeping unit (SKU) is a unique identifier specified in Seller Central or Supply Chain Portal that identifies a product in Amazon.com. This SKU is often called mSKU.

📘

Important

When you create orders, the product identifiers must be unique. If your catalog contains products with non-unique mSKUs, use external ID as the product identifier instead of mSKU.

SKU assigned by your service

A SKU assigned by your service is a unique identifier that identifies a physical item in your system. You provide this ID for example when you upload a catalog. SKUs are usually human-readable, which can be useful to quickly identify your product in a report.

📘

Important

When you create orders, the product identifiers must be unique. If your catalog contains products with non-unique SKUs, use external ID as the product identifier instead of SKU.

Product mapping

A product mapping is the representation of a product in the Buy with Prime catalog. This mapping contains the product's attributes, which provide information about the product, and product identifiers, which uniquely identify the product.

Buyability

Buyability is a determination of whether a product is eligible for Buy with Prime. Buyability depends on multiple factors, such as whether you correctly configured the product for Buy with Prime.

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.

If products are consistently in stock, buyability status typically changes infrequently. You can track the buyability status of a product in two ways:

  • Synchronously: You can get the buyability status of a product at any time, for example when you populate an empty buyability cache or in scenarios where 1) buyability consistency is more important than the added latency of an API call, or 2) you don't want the additional complexity required to handle buyability events and store buyability status.
  • Asynchronously: You can subscribe to the BUYABILITY_CHANGED event, which is published when the buyability status of a product changes. To reduce storefront rendering latencies, we recommend this method. In other words, you subscribe to the BUYABILITY_CHANGED event and cache buyability status in a local data store such as a catalog. By using buyability events instead of synchronously querying buyability, you omit the latency of querying buyability at the cost of slight delays in consistency. Also, if you store buyability in a catalog, you can retrieve buyability status in the same request that retrieves the product detail page.

Inventory

Inventory is the number of buyable units of an item. You can get the inventory for a product in the following three ways:

Catalog feed

A catalog feed is a bulk data import operation of Buy with Prime products. To create a catalog feed, you first put your product details in a catalog feed file in CSV format, and then upload the file.

Catalog feed file

A catalog feed file is a CSV file of products that you upload to the Buy with Prime catalog. For the required format of the feed file, download the template. For details, see Upload a Catalog.

Delivery preview

A delivery preview is a set of delivery options that include an estimated delivery date. To create a delivery preview, Amazon's fulfillment systems optimize combinations of requested products in requested quantities with the amount of inventory available across Amazon's fulfillment network. For details, see Create Delivery Previews.

Delivery group

A delivery group is a collection of items that will be packed and delivered together in a shipment, along with the relevant delivery offers available for the group.

Delivery offer

A delivery offer is a set of delivery options that you can show to shoppers that encapsulates information like delivery date range, messaging, and the Prime badge.

Delivery terms

Delivery terms are the terms of the delivery offer to generate, and help shape the response. You can provide the following delivery terms:

  • Location: The delivery location, including options such as IP address, zip code, and shipping address.
  • Shopper identity: The shopper's identity, for more personalized delivery offers based on the shopper's Amazon account information.

Delivery terms contribute to the accuracy, confidence level, and latency of the returned delivery offers. The more shopper and delivery information you provide, the higher the confidence level. Higher specificity comes with higher latency.

Shopper identity token

A shopper identity token is an Amazon shopper token that enables the Buy with Prime API to provide a more accurate delivery preview for the shopper. The Buy with Prime API currently supports two types of identity tokens: Login with Amazon (LWA) access tokens and Amazon Pay checkout session tokens.

Order

An order is a set of purchases that a shopper submits when they click a button such as Create order. For details, see Create and Manage Orders.

Customer

A customer is the shopper who creates an order.

Recipient

The recipient is the person who receives the order. The recipient might be the shopper or someone the shopper chooses to receive the order.

Line item

A line item is a single product on an order.

Order link

An order link is a link surfaced as call to actions to manage the order on your site.

Order total

An order total is the total price the shopper paid for the order on your site.

Delivery information

Delivery information is the details about delivery of items in the order. This information includes the state of delivery, estimated delivery date, and so on. You can use this information to sync the delivery information for Buy with Prime items to other systems.

Discount allocations

Discount allocations are information about discounts allocated to orders, line items, or delivery offers.

Package information

Package information is details about packages associated with the delivery of products in the order. This information includes the state of the package, estimated delivery date, and so on. You can use this information to sync the package information for Buy with Prime products to other systems.

Taxes

Buy with Prime doesn't customize any tax calculations on the order, so we expect that you provide only minimal information about tax (that is, the tax amount at the applicable granularities). The Buy with Prime API supports the ingestion of tax information at the order, line item, and delivery levels.

Returns and refunds

The following terms relate to returns and refunds.

Return

A Buy with Prime return is an action that a shopper takes to return delivered items that they purchased in a Buy with Prime order. For details, see Process Returns and Steps to Process Returns.

Refund

A Buy with Prime refund is a process to reimburse a shopper for an item that they ordered and then returned or cancelled. For details, see Synchronize Refunds and Steps to Process Refunds.

Reversal

Reversal is a term that the Buy with Prime API uses to encompass the concepts of returns, refunds, and cancellations. A Buy with Prime reversal offer specifies whether the item (or multiple items that are bought together) can be returned by evaluating a set of conditions specified in the returns policy at About Our Returns Policies, which you must follow and incorporate into your existing policies.

Event

An event is a change in a Buy with Prime resource as a result of certain actions. Examples of actions that trigger events include when a shopper requests a return, cancels an item, and so on. The term event also refers to the notifications that you can subscribe to receive when such a change occurs. For a full list of Buy with Prime event types, see Event Types. To receive events, you Subscribe to Events.

User event

In the context of Buy with Prime analytics, a user event is a specific action or occurrence within your e-commerce platform. User events can include various shopper interactions such as page views, clicks, and so on. Every user event has a name (such as page-load), an associated schema, and a unique event ID.

Related topics


Did this page help you?