> ## Documentation Index
> Fetch the complete documentation index at: https://help.retainful.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Event reference

> The events flowing through Retainful — from your store, from email engagement, and from your own systems.

Everything in Retainful runs on events. This page catalogs where they come from and what they're used for — useful when deciding what can trigger an [automation](/automations/triggers) or feed a [segment](/audience/segments).

## Store events

Delivered automatically by your store connection ([Shopify](/integrations/shopify) webhooks or the [WooCommerce](/integrations/woocommerce) plugin):

| Event                               | Source                | Notes                                                              |
| ----------------------------------- | --------------------- | ------------------------------------------------------------------ |
| Checkout started / updated          | Both                  | Carries cart contents and the recovery URL — powers cart recovery. |
| Order placed                        | Both                  | New order with line items, totals, discount codes.                 |
| Order paid                          | Both                  | Payment confirmed.                                                 |
| Order fulfilled                     | Both                  | Shipment created.                                                  |
| Order cancelled / refunded          | Both                  | Reversals — used to keep attribution honest.                       |
| Customer created / updated          | Both                  | Syncs the contact profile.                                         |
| Product created / updated / deleted | Both                  | Keeps the catalog fresh for email product blocks.                  |
| Product viewed                      | Both (pixel / plugin) | Browsing signal for targeting.                                     |
| Back in stock / out of stock        | WooCommerce           | Inventory transitions for back-in-stock flows.                     |

## Engagement events

Generated by Retainful's own sending pipeline:

| Event            | Meaning                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------- |
| Email delivered  | Accepted by the recipient's mail server.                                                            |
| Email opened     | Tracking pixel fired.                                                                               |
| Email clicked    | A tracked link was followed.                                                                        |
| Email bounced    | Hard or soft delivery failure — hard bounces [suppress](/audience/suppressed-contacts) the contact. |
| Email complained | Marked as spam — suppresses the contact.                                                            |
| Unsubscribed     | The contact opted out.                                                                              |

These power engagement-based triggers ("email opened", "email clicked") and segment conditions ("hasn't opened in 60 days").

## Retainful events

| Event                             | Meaning                                             |
| --------------------------------- | --------------------------------------------------- |
| Subscribed to list                | Contact joined a list — the welcome-series trigger. |
| Subscribed to email marketing     | Contact gained marketing consent.                   |
| Unsubscribed from email marketing | Consent withdrawn.                                  |

## Custom events

Anything you send through the [Events API](/developers/api/events) — your event types appear alongside the built-ins in the automation builder, with their payload fields available to filters and personalization.

There is no fixed list: any `eventName` you send is valid. The name is normalized and prefixed with your integration's key to form the event type you'll pick in the trigger list:

| `eventName` you send | Appears as                    |
| -------------------- | ----------------------------- |
| `Add to Cart`        | `REST-API.ADD_TO_CART`        |
| `Checkout Started`   | `REST-API.CHECKOUT_STARTED`   |
| `Purchase Completed` | `REST-API.PURCHASE_COMPLETED` |
| `Placed Order`       | `REST-API.PLACED_ORDER`       |

<Note>
  These custom commerce events are distinct from the [store events](#store-events) above. If your store is connected via Shopify or WooCommerce, those events already arrive automatically — you don't need to send them through the API as well. The REST API events are for storefronts and systems Retainful doesn't integrate with directly.
</Note>

An event type only appears in the trigger picker once the first event of that type has been received, or after you call `POST /api/v1/events/register`. See [Register an event schema](/developers/api/events#register-an-event-schema).

## Event data lifecycle

1. An event arrives (store webhook, engagement tracker, or your API call).
2. It's validated, deduplicated, and matched to a contact (creating one when appropriate).
3. It's recorded on the contact's [timeline](/audience/contacts).
4. Matching [automation triggers](/automations/triggers) fire.
5. Segments referencing the event re-evaluate.

Processing is near-real-time — an abandoned checkout can enter a recovery flow within seconds of the event arriving.