Tracking Add-to-Cart Events

Add-to-cart activity is one of the most useful signals for Amazon Personalize in a WooCommerce store. It indicates stronger intent than a product view while occurring frequently enough to provide useful behavioral data before purchases are available. For agencies, the implementation challenge is making the event reliable across guest sessions, logged-in customers, product variations, consent requirements, and server-side checkout flows.

Define the interaction event before writing code

Choose one event type and use it consistently in the Amazon Personalize dataset, event tracking requests, reporting, and model evaluation. For example, an interaction schema might use AddToCart as the event type:

{"eventType":"AddToCart","itemId":"SKU-123","quantity":2}

The event type is a value in the interactions dataset schema, so its capitalization and spelling must match the value sent through the Amazon Personalize Events API. If the existing schema uses add-to-cart, do not introduce AddToCart as a second value without a deliberate migration and retraining plan.

Use the catalog item identifier, not only the product post ID

The itemId sent to Amazon Personalize must match the item identifier in the Items dataset and in recommendation requests. A WooCommerce product ID is acceptable only when it is also the stable catalog identifier used by the integration. Stores with variable products should decide whether recommendations operate at the parent-product level or at the variation level.

Use a variation SKU or variation ID when color, size, stock, or price differs meaningfully by variation.
Use the parent product ID when recommendations are displayed at the product level and all variations share one catalog record.
Do not send a transient cart item key as itemId; cart item keys are generated for a specific cart state and do not identify catalog items.
Keep the identifier format identical in product feeds, event payloads, recommendation requests, and reporting exports.

Capture the event at the WooCommerce add-to-cart action

The woocommerce_add_to_cart action is a practical server-side integration point. It runs after WooCommerce has accepted an item into the cart and provides the product, quantity, variation, and cart item key. A custom plugin can subscribe to this action and enqueue an event for delivery to Amazon Personalize.

add_action( 'woocommerce_add_to_cart', function ( $cart_item_key, $product_id, $quantity, $variation_id, $variation, $cart_item_data ) {
    $item_id = $variation_id ? wc_get_product( $variation_id )->get_sku() : wc_get_product( $product_id )->get_sku();

    if ( ! $item_id ) {
        return;
    }

    my_personalize_queue_event( array(
        'eventType' => 'AddToCart',
        'itemId'    => (string) $item_id,
        'quantity'  => (int) $quantity,
    ) );
}, 10, 6 );

The example illustrates the hook rather than a complete Amazon Web Services client. Production code should validate that the product exists, handle a missing SKU according to the store’s identifier policy, and avoid making a blocking API request during the customer’s page response.

Send events with PutEvents

Amazon Personalize real-time event ingestion uses the PutEvents operation. The request includes the event tracker’s trackingId, a userId, a sessionId, and an eventList. Each event includes an eventType, itemId, eventAt, and optional properties.

{
  "trackingId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "userId": "customer-4821",
  "sessionId": "wc-session-9f31...",
  "eventList": [
    {
      "eventType": "AddToCart",
      "itemId": "SKU-123",
      "eventAt": "2025-01-15T14:32:10Z",
      "properties": "{\"quantity\":2,\"source\":\"product-page\"}"
    }
  ]
}

The exact SDK request shape varies by language, but the event properties value is represented as a JSON string inside the request. Store timestamps in UTC and generate eventAt from the actual add-to-cart time rather than the time a retry worker happens to process the event.

Handle guests and authenticated customers consistently

WooCommerce stores commonly receive add-to-cart activity from both logged-in customers and guests. Create a stable anonymous identifier for the browser or store session and use the same identifier for subsequent events in that session. When a customer logs in, apply the identity strategy defined for the Amazon Personalize integration rather than abruptly creating unrelated identifiers for every request.

userId: use a stable, non-sensitive customer identifier for authenticated users and a privacy-approved anonymous identifier for guests.
sessionId: use the WooCommerce session identifier or an equivalent first-party session value, with a defined expiration policy.
trackingId: use the Amazon Personalize event tracker associated with the dataset group and environment.

Do not send raw email addresses, names, or other unnecessary personal data as identifiers. If an identifier is derived from customer data, document the hashing and normalization process and apply it consistently across systems.

Choose browser-side or server-side delivery deliberately

Browser-side tracking can record an event immediately after an AJAX add-to-cart response and can include page context such as a campaign or placement. It also depends on JavaScript execution, browser privacy controls, consent, and network availability. Never expose long-lived AWS credentials in browser code.

Server-side delivery from a WooCommerce plugin or ingestion service keeps AWS credentials private and is less dependent on the browser. It should be asynchronous: write a small event record to a queue or durable table, then let a worker call PutEvents. Include retry handling with exponential backoff, monitor failed requests, and prevent one Amazon Personalize outage from delaying the add-to-cart response.

A hybrid implementation is possible, but it must prevent duplicate events. For example, choose the server-side hook as the authoritative source and use browser code only for page-level metadata that cannot be obtained on the server.

Account for quantity and repeated additions

An add-to-cart event can represent one user action that adds multiple units, or several separate actions for the same item. Send the quantity as an event property when the business needs that detail:

{"quantity":3,"cart_item_key":"internal-value-if-needed"}

Do not use the cart’s final quantity as though it were always the quantity added in the latest action. A customer may update quantity later, remove an item, or merge two cart lines. If the store tracks quantity changes, define separate event types or properties rather than rewriting the original add-to-cart event.

Prevent duplicate and invalid events

Retries and AJAX responses can cause the same action to be submitted more than once. Record an internal event identifier, such as a generated UUID tied to the WooCommerce request, and use it in the integration’s idempotency or deduplication layer. Amazon Personalize event ingestion should not be treated as a transactional cart system; WooCommerce remains the source of truth for cart state.

Before sending an event, validate the following:

The item exists in the current catalog mapping.
The event type is allowed by the interactions schema.
The user and session identifiers meet the integration’s privacy and format rules.
The timestamp is valid and reasonably close to the action time.
The event has not already been queued by both a browser and server integration.
The customer has granted any consent required for behavioral personalization.

Test the complete WooCommerce flow

Test simple products, variable products, AJAX add-to-cart, product-page add-to-cart, shop and archive buttons, logged-in users, guests, quantity changes, sold-out products, and stores with caching or a CDN. Confirm that the identifier in each event matches the corresponding Amazon Personalize Items dataset record.

For operational verification, log a redacted event envelope containing the event type, item identifier, timestamp, delivery status, and an internal correlation ID. Do not log credentials or unnecessary customer data. Compare WooCommerce add-to-cart counts with accepted event counts over a controlled test period, allowing for consent refusals, blocked scripts, queue failures, and events rejected because an item is not present in the catalog.

Use add-to-cart data in model evaluation

Add-to-cart events can be useful as an intermediate signal, but they are not equivalent to purchases. Decide whether the recommendation objective should optimize for AddToCart, Purchase, or a weighted combination supported by the selected Amazon Personalize recipe. Keep event definitions stable while evaluating changes so that an apparent model improvement is not actually a tracking change.

When an item is purchased, continue sending a separate purchase event rather than converting or deleting the earlier add-to-cart event. The sequence of view, add-to-cart, and purchase interactions gives the recommender more information about intent and helps the agency identify where tracking or merchandising changes affect the funnel.

Table of contents :