Subscribe to Events
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.
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.
Buy with Prime events are thin events, which means you are typically expected to call the Buy with Prime API to request further information about the event. Each Buy with Prime event contains a resources
array that describes the entities, such as catalogs or orders, to which an event pertains. You use the resource identifiers to make an API call to retrieve more data. 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.
For a full list of events, see Event Types. For example requests and responses, see:
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.
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
Key | Data Type | Description |
---|---|---|
version | String | Amazon EventBridge event version. |
id | String | Amazon EventBridge-generated UUID for an event. |
detail-type | String | Type schema for the detail of the event. Examples include ITEM_CANCELLED , RETURN_STARTED , and so on. For a list of Buy with Prime event types, see Event Types . |
source | String | Name of the partner event source in Amazon EventBridge. |
account | String | AWS account ID that hosts the partner event source. |
time | String | ISO 8601 timestamp that indicates when the event was published. |
region | String | AWS region from which the event is published. |
resources | Array of strings | Array of identifiers for the resources that triggered the event, in key-value pair format. Each resource identifier is a string that starts with businessProduct/{businessProductId}/ , followed by resource types (keys) and resource IDs (values) separated by slashes. For details about how to interpret resources , see How to process events. |
detail | Object | JSON object that contains details about the event. For most events, this object is empty, and you must call the Buy with Prime API to find further information about the resource(s) specified in the resources array. |
How to process events
When you receive an event, you typically do the following three steps:
-
Get the event type from the
detail-type
field of the event. -
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 isbusinessProduct/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
- the business product identifier is
-
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
Name | Description |
---|---|
createEventSubscription | Creates a subscription to receive one or more types of events. |
deleteEventSubscription | Deletes a subscription so that you stop receiving a certain event type. |
Queries
Name | Description |
---|---|
eventSubscription | Get event subscription details by subscription ID. |
eventSubscriptions | Get a list of subscription IDs for a given client ID. |
Related topics
Updated 8 days ago