Buy with Prime | Developer Documentation
Documentation

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.

Sign Up

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 your catalog is associated with 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.

For details about uploading your product 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.
  • 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 is a unique, user-provided product ID that uniquely identifies a product in the Buy with Prime catalog. You provide this ID when you upload a catalog. You can use this ID to store any of your own identifiers, such as a listing ID. We recommend that you use this identifier when you interact with the Buy with Prime API so that you don't need to store any Buy with Prime product identifiers. For details, see Create and Manage Catalogs.

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 identifier is used when you Create Delivery Previews. This SKU is often called 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. For details, see Create and Manage Catalogs.

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. You typically use this method 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 information about the fields, see Catalog feed file.

Catalog feed processing result file

A catalog feed processing result file is a CSV file that provides the result of a catalog feed upload as a list of issues or as a report. For a description of the fields in the report, see Catalog feed processing result file. For instructions on how to download the report, see Get the Result of a Catalog Upload.

Delivery preview

A delivery preview is a set of delivery options that include an estimated delivery date. To formulate a delivery preview, Amazon's fulfillment systems optimize combinations of requested products in requested quantities with the amount of inventory available across the Amazon 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. Encapsulates information like delivery date range, messaging, and Prime badging.

Delivery term

A delivery term is context that you provide to the Delivery Preview query. Delivery terms are fundamental in shaping the outcome of the API response. You can provide the following delivery terms:

  • Location: The delivery location, allowing for granularity in options such as IP address, zip code, and shipping address.
  • Shopper identity: The shopper's identity, which enables more personalized delivery offers based on their Amazon account information.

Delivery terms contribute significantly to the accuracy, confidence level, and latency of the returned delivery offers. The more shopper and delivery information provided in the API request, the higher the confidence level of the offer returned. Higher specificity comes with higher latency.

Shopper identity token

A shopper identity token is an Amazon shopper token that the Buy with Prime API uses 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 customer 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 customer or someone the customer chooses to receive the order.

Line item

A line item is a single product to fulfill 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 customer 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.

Returns and refunds

The following terms relate to returns and refunds.

Return

A Buy with Prime return is an action that a customer takes to return previously-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 by which a customer is reimbursed for an item that they ordered, which is 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 found 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 customer 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. For details, see Subscribe to Events.

All Buy with Prime events are thin events. After receiving a thin event, you typically need to call the Buy with Prime API to request further information. For example, a REFUND_REQUESTED event specifies the order ID and refund ID, but you must make an API call for further information about the refund.

Resource

A resource is a Buy with Prime entity, such as a catalog or order, to which an event pertains. Each Buy with Prime event consists of a resources array that contains resource identifiers that you can use to make an API call to retrieve more data.

Amazon EventBridge

Amazon EventBridge is a serverless event bus that you can configure to receive events from services. In this case, Buy with Prime is the service that publishes the events. With Amazon EventBridge, you set up routing rules to determine where to send the data. For details, see What is Amazon Event Bridge?

Target

A target is an endpoint that Amazon EventBridge sends an event to when the event matches the event pattern that you define in a rule. An example of a target is Amazon Simple Queue Service. For a list of targets that EventBridge accepts, see Amazon EventBridge targets.

Partner event source

A partner event source is an entity in Amazon EventBridge that you can associate with a target to receive and process events. For details about partner event sources, see Receiving events from a SaaS partner with Amazon EventBridge.

Business product

A business product, within the context of an event, is a specifically managed selling experience, often a sales channel or store.

Dead letter queue

A dead letter queue is a type of queue that temporarily stores events and messages that weren’t processed due to system errors. You can optionally create a dead letter queue for Buy with Prime events. For details, see Event retry policy and using dead-letter queues.

User event

A user event is a specific action or occurrence within your e-commerce platform that you can track using Buy with Prime analytics. User events are 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. For details, see Get Analytics Reports.

Related topics

Updated 2 days ago