Watchlist
Open Beta Documentation Amazon offers this technical
documentation as part of a pre-release, open beta. The features described might change as Amazon receives feedback
and iterates on the features. For the most current feature information, see the Release
Notes.
These instructions are for the addition and removal of content from the customer’s watchlist. Fire TV may use watchlist information to update the customer’s universal watchlist.
What to send
For each trigger (see when to send), send events with the fields below. There is no need to filter the data you send or check for duplicates. Amazon does this as necessary.
| Field Name | Required (Y/N) | Description |
|---|---|---|
| Content ID | Y | Corresponds to the content ID provided to Fire TV through the catalog integration. |
| Date When Added | Y | Timestamp for when the customer added the entry to the watchlist. |
| Internal Profile ID | Y | An obfuscated Profile ID so Fire TV can associate the activity with the correct app customer. |
When to send
- On initial app launch and sign-in.
- On adding or removing an item from the customer’s watchlist. This action can occur off-device.
- When asked to refresh by Fire TV’s on-device service.
- When switching to a new profile.
How to send
To share the latest title the customer added to the watchlist, use the following TypeScript code:
// Example customer entry event generated when user starts watching content
const customerListEntry: ICustomerListEntry = new CustomerListEntryBuilder()
.addedTimestampMs(Date.now())
.contentId(
new ContentIdBuilder()
.id('string')
.idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
.build(),
)
.profileId(
new ProfileIdBuilder()
.id('myProfileId1')
.idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
.build(),
)
.build();
// Send the event
ContentPersonalizationServer.reportNewCustomerListEntry(
CustomerListType.WATCHLIST,
customerListEntry,
);
Send the customer’s full watchlist
The following TypeScript code demonstrates how to send the customer’s full watchlist when requested by the Content Personalization data service:
const customerListEntriesHandler: ICustomerListEntriesHandler = {
getAllCustomerListEntries: (
listType: CustomerListType,
customerListEntriesProvider: ICustomerListEntriesProvider,
) => {
let listEntries: ICustomerListEntry[] = [];
const customerListEntry1: ICustomerListEntry = new CustomerListEntryBuilder()
.addedTimestampMs(Date.now())
.contentId(
new ContentIdBuilder()
.id('content1_CDF_ID')
.idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
.build(),
)
.profileId(
new ProfileIdBuilder()
.id('myProfileId')
.idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
.build(),
)
.build();
listEntries.add(customerListEntry1);
const customerListEntry2: ICustomerListEntry = new CustomerListEntryBuilder()
.addedTimestampMs(Date.now())
.contentId(
new ContentIdBuilder()
.id('content2_CDF_ID')
.idNamespace(ContentIdNamespaces.NAMESPACE_CDF_ID)
.build(),
)
.profileId(
new ProfileIdBuilder()
.id('myProfileId')
.idNamespace(ProfileIdNamespaces.NAMESPACE_APP_INTERNAL)
.build(),
)
.build();
listEntries.add(customerListEntry2);
customerListEntriesProvider.addCustomerListChunk(listType,listEntries);
customerListEntriesProvider.commit();
}
};
// Remeber to set your customer list entries handler in the onStart function of your HeadlessService
ContentPersonalizationServer.setCustomerListEntriesHandler(
customerListEntriesHandler,
);
Last updated: Sep 30, 2025
