Tracking Purchases

Purchase events are the most important conversion signal in an Amazon Personalize integration. Product views and cart additions describe intent, but a completed purchase tells Personalize which recommendations contributed to revenue. For WooCommerce agencies, reliable purchase tracking is therefore more important than simply increasing the number of events sent to the service.

What a purchase event represents

Amazon Personalize receives purchase activity through the event tracker associated with a dataset group. A purchase event normally contains the customer or anonymous visitor identity, the session identifier, the WooCommerce product or variation identifier, the event type Purchase, and an event timestamp.

For an order containing multiple products, send one purchase event for each purchased line item. Keep the same session identifier and order context for all events in that order.

{"eventType":"Purchase","itemId":"variation-4821","properties":"{\"quantity\":\"2\",\"price\":\"29.95\",\"orderId\":\"WC-10482\"}"}

Event properties are sent as a JSON string. Define the properties you intend to use in the interactions schema and use consistent names and value formats across historical imports and real-time events. A property such as orderId is useful for operational tracing, while quantity and price provide additional business context.

Send the event after payment is confirmed

Do not record a purchase when a customer merely submits checkout. WooCommerce orders can remain pending, fail payment, be cancelled, or be abandoned. Trigger the integration when the order reaches the payment-confirmed path, such as the woocommerce_payment_complete action or a controlled transition to a paid status.

For gateways with asynchronous confirmation, use the gateway’s confirmed payment callback and then enqueue the event. This avoids reporting purchases that have not actually been paid. If the business treats orders placed with an invoice or bank transfer as purchases before payment, document that rule and apply it consistently.

Use stable identifiers

• Item ID: Use the same identifier in WooCommerce, the Amazon Personalize items dataset, historical interaction imports, view events, cart events, and purchase events. Decide explicitly whether the catalog uses parent products or variations; do not mix both for the same recommendation model.
• User ID: Use a stable internal customer identifier when the shopper is authenticated. Avoid sending email addresses or other direct personal information.
• Session ID: Generate or reuse a stable identifier for the browsing session. Anonymous visitors can be tracked with a session ID, while logged-in visitors can provide both a user ID and a session ID.
• Event ID: Generate a unique value for each line-item purchase event when your integration uses event IDs for tracing and replay control.

Do not generate a new session ID on every page request, and do not use the WooCommerce order number as the user ID. An order identifies a transaction, not a person.

Prevent duplicate purchase events

WooCommerce hooks may run more than once because of payment retries, status changes, webhook delivery, administrator edits, or Action Scheduler retries. Amazon Personalize should not receive multiple logical purchases simply because the integration retried a job.

Create an idempotency record in WordPress, a queue database, or the integration service. Store the order ID, line-item ID, event ID, payload hash, attempt count, and delivery status. Mark a line item as sent only after the request has succeeded. If a retry is required, reuse the same event ID and payload rather than creating a new purchase representation.

A practical key is the combination of the WooCommerce order ID and line-item ID. This is more precise than using only the order ID because one order can contain several products.

Queue delivery instead of blocking checkout

Sending events synchronously during the customer-facing checkout request can slow the thank-you page and make a temporary AWS error look like a payment failure. Queue a small delivery job after payment confirmation, then send the event from a worker or scheduled process.

The worker should retry transient failures with backoff, record the response and request ID, and alert the agency when events remain undelivered. AWS credentials should stay on the server. Never expose an AWS access key in browser JavaScript or send events directly from a public checkout page.

<?php $order->get_items(); $events = array(); foreach ( $order->get_items() as $item_id => $item ) { $product = $item->get_product(); if ( ! $product ) { continue; } $events[] = array( 'eventType' => 'Purchase', 'itemId' => (string) $product->get_id(), 'eventId' => 'wc-' . $order->get_id() . '-' . $item_id, 'sentAt' => time(), 'properties' => wp_json_encode( array( 'quantity' => (string) $item->get_quantity(), 'price' => (string) $item->get_total(), 'orderId' => (string) $order->get_id(), ) ), ); } // Pass $events to a server-side worker that calls Amazon Personalize PutEvents.

The example deliberately stops before the AWS call. In production, the worker should call PutEvents with the event tracker ID, session ID, optional user ID, and the event list. Keep the code that builds WooCommerce events separate from the delivery client so it can be tested without making AWS requests.

Respect consent and data minimisation

Purchase tracking can involve customer and order data, so connect it to the site’s consent and privacy policy. Do not include names, email addresses, phone numbers, full addresses, payment details, coupon codes containing personal information, or free-text checkout fields in event properties. Use an internal pseudonymous customer ID and send only the fields required for recommendation training and reporting.

Where consent is required, queue or suppress the event according to the site’s documented policy. Also provide a deletion or suppression workflow for customer data held in the integration’s own event queue and identity store.

Validate the complete purchase path

1. Place a test order containing one simple product and one variation.
2. Confirm that the item IDs exactly match the Amazon Personalize items dataset.
3. Verify that each line item produces one Purchase event.
4. Retry the payment callback and confirm that no duplicate logical event is queued.
5. Test failed, cancelled, refunded, and partially refunded orders separately.
6. Inspect the event properties and confirm that no prohibited customer data is present.
7. Compare WooCommerce paid-order counts with successfully delivered purchase events over the same period.

Refunds are a separate business decision. A normal purchase event should not be rewritten after a refund. If recommendations must account for returns, model that requirement explicitly with a supported event or downstream business rule, and keep the original purchase history auditable.