# Retroactive events

Retroactive events let an Advertiser report qualifying actions together with a Signed Token Callback connection. They are
useful when a user completes an action during sign-up, before Onward knows which Platform and Advertiser identities belong
to the same person.

For example, a user may create an account and make a first deposit before the Advertiser backend calls
`POST /v1/users/connect-account`. Supplying that deposit as a retroactive event lets Onward evaluate the relevant task as
soon as the account connection is established.

## When to use them

Use `retro_events` only for Advertiser actions that:

- occurred before the account connection was confirmed;
- belong to the Advertiser user identified by `advertiser_user_id`;
- may satisfy a task in the user's active quest chains;
- have a trustworthy event timestamp and event type.

Events that happen after the connection should be sent through the normal Event API instead of being attached to another
connection request.

## Event fields

| Field | Required | Description |
| --- | --- | --- |
| `event_type` | Yes | Advertiser-defined event type, such as `deposit.completed`. |
| `timestamp` | Yes | Moment the event occurred, formatted as an ISO 8601 UTC timestamp. |
| `amount` | No | Non-negative measured value associated with the event. |
| `currency` | No | Currency or unit associated with `amount`. |
| `reference` | No | Stable Advertiser-side idempotency or audit reference. |
| `metadata` | No | Additional Advertiser-defined attributes. |

One connection request can contain at most 100 retroactive events.

## Example

```json
{
  "token": "<opaque-connection-token>",
  "advertiser_user_id": "advertiser-user-123",
  "retro_events": [
    {
      "event_type": "signup.completed",
      "timestamp": "2026-08-05T08:55:00.000Z",
      "reference": "signup-123"
    },
    {
      "event_type": "deposit.completed",
      "amount": 100,
      "currency": "USD",
      "reference": "deposit-987",
      "timestamp": "2026-08-05T09:00:00.000Z",
      "metadata": {
        "payment_method": "bank_transfer"
      }
    }
  ]
}
```

Onward links the accounts first and then evaluates the supplied events against the user's active tasks. The exact request
and response schemas are documented under
[`POST /v1/users/connect-account`](/docs/api-reference/account-connection-api#complete-oauth-account-linking).

## Integration guidance

- Preserve the original event timestamp; do not replace it with the connection time.
- Use the same event taxonomy and units as subsequent Event API calls.
- Supply a stable `reference` whenever the Advertiser has one.
- Include only events for the user being connected.
- Keep metadata small and limited to attributes needed for task evaluation or audit.
- Do not resend ordinary post-connection activity through `retro_events`.

Retroactive events are part of the connection request, so protect them and the connection token according to the
[account-linking security requirements](/docs/account-linking/security-requirements).