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

# Reliable Reporting registration preview

> How to test Reliable Reporting registration and setup actions in staging.

> [!NOTE]
>
> Reliable Reporting registration is available for staging validation.
> Apostra does not send registration requests in production yet.

In staging, Reliable Reporting registration connects each active seller
account and its media buys to the reporting feeds that the seller advertises
through AdCP. Apostra keeps this registration current automatically. Sellers
do not need to ask a buyer to register each media buy by hand.

## What Apostra sends

During the staging preview, when a seller advertises AdCP 3.2 Reliable
Reporting support, Apostra calls the seller's `sync_accounts` task for each
active account. The request contains the account ID, the exact media-buy scope,
the selected reporting offering, and an idempotency key. Apostra sends a new
configuration version when that scope changes.

The seller must treat an identical idempotency key as the same request. A retry
must not create a second destination, grant, or reporting configuration.

## Registration lifecycle

The seller returns one lifecycle state for every requested configuration:

| State | Meaning |
| - | - |
| `pending_validation` | The seller is validating the configuration. |
| `pending_setup` | Provider or destination setup is still in progress. |
| `ready` | Reporting is active for the accepted scope. |
| `action_required` | A named party must complete a specific setup or repair step. |
| `inactive` | The seller rejected or deactivated the configuration. |

Apostra periodically reads non-final registrations until the seller reports
`ready` or `inactive`. It records `action_required` separately from ordinary
setup waits and raises it for operational follow-up.

## Return a useful setup action

For `pending_setup` or `action_required`, return either a structured `setup`
object or a structured issue. A setup object contains:

* a closed action: `grant_access`, `activate_recipient`,
  `authorize_provider`, or `repair_access`;
* a short message that tells the operator what to complete;
* an optional HTTPS setup URL and expiry.

The setup URL is a human entry point, not a bearer credential. Do not put
tokens, signed credentials, or user information in it. Apostra does not fetch
or execute the URL. After the operator completes the action, return `ready`
from the account status read so registration can finish.

## Changing the media-buy scope

Apostra creates a new immutable configuration generation when media buys join
or leave an account's active route set. The accepted generation becomes the
current registration only after the seller reports it as ready. This prevents
a delayed response for an earlier generation from replacing the current
scope.

## Reporting status

Apostra records what it expects to receive for a media buy. For each media buy,
`get_seller_reporting_receipts` returns the current state under `canonical`. A
media buy with nothing recorded returns an empty `obligations` list. Each
reporting item it lists, called an obligation, carries:

* the period it covers, `periodStart` and `periodEnd`, with `expectedAt` and
  `nextExpectedAt`;
* `requiredFinality`, which is `snapshot` or `official`;
* `coverage`, which is `full`, `partial` or `none`;
* `health`, one of five states.

| `health` | Meaning |
| - | - |
| `waiting` | No report is due yet. |
| `healthy` | Every report currently due has been produced and has met the required delivery or reconciliation step. |
| `delayed` | A report is late, but automatic recovery is still running. |
| `action_required` | Automatic recovery has finished, or a named party needs to act. |
| `complete` | The scope is closed and every required final report is satisfied. |

When an obligation needs attention it also carries an `issue`: a `code`
(`REPORT_OVERDUE` or `RESOURCE_EXPIRED`), the party that has to act, and a
`recommendedAction` of `wait_for_retry` or `contact_seller`.

Coverage and finality are separate. A fresh report can cover only part of what
is due, and a complete report can still be a snapshot. `canonical` also gives the
media buy's overall `health`, its `freshness` (`current` or `stale`), `dataThrough`
and `nextExpectedAt`. Reading it does not request a new report.

## Corrections are new revisions

Apostra holds a report as a revision. A revision's `kind` is `snapshot` for a
provisional report, `official` for the seller's official result for the period,
or `restatement` for a later revision that corrects an earlier one. A revision
is never edited: a correction adds a new revision and the earlier one stays, so
both what was first reported and what replaced it can be read.

Finality belongs to a revision, not to a receipt. An accepted receipt does not
make a report official. Each obligation's `latestRevision`, and the media buy's
`lastSuccessfulRevision`, show only when managed delivery is on for the buyer.
For other buyers they read `null`.

To deliver the reports themselves and read what Apostra received, see
[Deliver reporting to Apostra](https://docs.apostra.com/v3/seller-reporting-delivery.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.