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
When to send
How to send
Send the customer’s full 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:

Copied to clipboard.

// 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:

Copied to clipboard.

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