📘

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

Buy with Prime business products publish events when the state of underlying resources change. For example, a RETURN_STARTED event is published when a shopper starts a return, an DELIVERY_COMPLETED event is published when one or more items were delivered to their destination, and so on.

Buy with Prime events are represented as JSON objects that all have a similar structure. You subscribe to events by using the Buy with Prime API Event interface, and you configure event destinations through Amazon EventBridge. For instructions on how to subscribe to events, see Steps to Subscribe to Buy with Prime Events.

This topic describes event concepts, the structure of Buy with Prime events, and how to process events. For a full list of events, see Event Types. For example requests and responses, see:

• Create and Delete Event Subscriptions
• Query Event Subscriptions

Prerequisites

To subscribe to Buy with Prime events, you must have an Amazon Web Services (AWS) account. To create an AWS account, go to the Amazon Web Services home page and then click Create an AWS account.

Concepts

The following sections describe event concepts.

Event structure

Buy with Prime events are in JSON format. The following example shows an event.

Example event

{
  "version": "0", 
  "id": "example-event-id", 
  "detail-type": "RETURN_COMPLETED", 
  "source": "aws.partner/buywithprime/partner-event-source-name",
  "account": "example-aws-account-id", 
  "time": "2023-10-27T12:34:56Z", 
  "region": "us-east-1", 
  "resources": [
    "businessProduct/example-business-product-id/order/example-order-id/return/example-return-id",
  ], 
  "detail": {}
}

Event fields

How to process events

When you receive an event, you typically do the following three steps:

1. Get the event type from the detail-type field of the event.

2. Parse the resources array of the event to find the resource that triggered the event. You interpret each item of this array as a list of key-value pairs separated by slashes. Within a string, the key/value pairs are increasingly specific, ultimately pointing to a single resource.

   For example, if an entry in the resources array is businessProduct/example-business-product-id/order/example-order-id/return/example-return-id, then:

   • the business product identifier is example-business product-id
   • the order identifier is example-order-id
   • the return identifier is example-return-id

3. Call the Buy with Prime API for further information about the resource. For examples of API calls that you can make in response to specific events, see the topics for the individual Event Types.

📘

Duplicate events are possible but infrequent. Events typically won't repeat if the values of their associated attributes stay the same.

API operations

You use the following mutations and queries to subscribe to events. To access these mutations and queries, your API credentials must have at least full permission (create, view, and delete) to event subscriptions. You choose permission scopes when you generate your API credentials. For details, see Authenticate to the Buy with Prime API.

Mutations

Queries

Related topics

• Steps to Subscribe to Buy with Prime Events
• Event Types
• Create and Delete Event Subscriptions
• Query Event Subscriptions