reporting-subscriptions
/reporting-subscriptions
Serve or subscribe to AdCP 3.3 principal-level reporting subscriptions (experimental media_buy.reporting_subscriptions) with @adcp/sdk. Use when a seller enables subscriptions on its Reliable Reporting service, when a buyer registers, changes or removes a reporting subscription, or when code calls syncPrincipal with reporting_subscriptions or reporting_destinations, accounts.ensure, or reporting storage and migrations.
- Author
- adcontextprotocol ↗
- Repository
- adcp-client ↗
- Licence
- Apache-2.0
- Last repository change
- 12.11.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 12.11.2026, without references to retired models or APIs.
Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.
What it does and when to use it
Serve or subscribe to AdCP 3.3 principal-level reporting subscriptions (experimental media_buy.reporting_subscriptions) with @adcp/sdk. Use when a seller enables subscriptions on its Reliable Reporting service, when a buyer registers, changes or removes a reporting subscription, or when code calls syncPrincipal with reporting_subscriptions or reporting_destinations, accounts.ensure, or reporting storage and migrations.
Original author description
Serve or subscribe to AdCP 3.3 principal-level reporting subscriptions (experimental media_buy.reporting_subscriptions) with @adcp/sdk. Use when a seller enables subscriptions on its Reliable Reporting service, when a buyer registers, changes or removes a reporting subscription, or when code calls syncPrincipal with reporting_subscriptions or reporting_destinations, accounts.ensure, or reporting storage and migrations.
How it works
- Buyer: the five calls
- Seller: one block
- Do / don't
- Read next
SKILL.md preview
---
name: reporting-subscriptions
description: Serve or subscribe to AdCP 3.3 principal-level reporting subscriptions (experimental media_buy.reporting_subscriptions) with @adcp/sdk. Use when a seller enables subscriptions on its Reliable Reporting service, when a buyer registers, changes or removes a reporting subscription, or when code calls syncPrincipal with reporting_subscriptions or reporting_destinations, accounts.ensure, or reporting storage and migrations.
---
# Reporting subscriptions (AdCP 3.3, experimental)
A buyer registers reporting once on its principal (`sync_principal`), and the subscription follows its grants across every account. Wire payloads stay snake_case exactly as in the spec; only method and option names are camelCase.
## Buyer: the five calls
```ts
await client.reporting.subscribe(subscription, { registerDestination }); // upsert one; version chosen for you
await client.reporting.unsubscribe('pacing-hourly'); // the only deactivation path
await client.reporting.listSubscriptions(); // states
await client.reporting.preview(subscription); // seller dry run + offeringIds
const outcome = await client.accounts.ensure(key, { billing: 'operator' }); // ready | pending | ambiguous | rejected
```
`client.reporting.replaceSubscriptions(list, { deactivateOmitted: true })` is the expert complete-set write; `[]` needs `deactivateAll: true`. `client.reporting.reconcile()` lists every owed period with its status, reason and responsible party; `client.reporting.explain({ accountId, period })` returns `CoverageTrace`s. `client.reporting.poll()` returns the events since the last `batch.ack()` (call `ack()` after handling; ids are deterministic, so deduplicate on `event.id`); `events({ signal })` is the loop; `handleWebhook(VerifiedWebhook.fromOutcome(verification, body))` is a doorbell, and a webhook body is never event content. Receipts: never send one on read. `reconcile({ receipts: { mode: 'verified', commit } })` receipts after the SDK verified the revision and your `commit` returned `{ commitRef }`; billing lines without a receipt read `receipt: { status: 'owed_by_buyer' }`. Never auto-accept adjustments.
## Seller: one block
```ts
import { postgresStorage } from '@adcp/reporting-storage'; // memoryStorage() from '@adcp/sdk/storage' in development
const reporting = createReliableReportingService({
storage: postgresStorage({ pool, acknowledgeIsolatedDatabase: true }),
...producerConfig,
subscriptions: { principal: { agentUrl, notifications, resolvePrincipal }, maxAccounts: 500 },
});
const server = createAdcpServerFromPlatform(reporting.install(platform), { protocol: reporting.principals!.protocol });
```
Run `npx adcp-reporting-storage migrate` before starting a release. The service reconciles on writes and sweeps in `runCycle`; you do not call the engine.
## Do / don't
| Don't | Do |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Raw `syncPrincipal({ configuration: { reporting_subscriptions: [newOne] } })`: every omitted subscription is deactivated and every omitted destination revoked | `client.reporting.subscribe(newOne)`. The raw call is refused with `SUBSCRIPTION_WOULD_DEACTIVATE` / `DESTINATION_WOULD_REVOKE` unless you pass `allowDeactivation` / `allowRevocation` |
| Omit `subscription_version` or forget to bump it | Let `subscribe` choose it |
| `scope: {}`, or rely on an implicit all-accounts scope | `scope: { all_authorized_accounts: true }` or `{ account_ids: [...] }`, plus `operator_domains` for agencies |
| Compute periods with `new Date()` and local time | Read owed periods from the SDK (`client.reporting.reconcile` / `explain`); never default a timezone |
| Treat a pending account as an error and retry with a new key | Switch on `outcome.kind` and `nextStep(outcome)`; a repeat `ensure` returns the open request |
| Fetch `pending_action.url` | Show it to a person: `formatPendingAction(outcome.action)` |
| Revoke a grant to end a relationship | `windDownGrant(account.authorization)` keeps reconciliation tasks |
| Reduce a grant to tasks without `get_reporting_status` and expect coverage to continue | That is a loss of reporting authority (AdCP 3.3.0-beta.4): `accounts_unauthorized[]`, `SCOPE_INSUFFICIENT`; adding it back is a re-grant. Keep `get_reporting_status`, as `windDownGrant` does |
| Add a package to a confirmed buy and serve it like the original packages | Serve `packages[].added_at` on `get_media_buys` for every package added after `confirmed_at`: the package is owed from the period containing it, never as a cutover |
| List `reporting_subscription_probe` without `reset_state` | Pass `resetState` with `reportingSubscriptionProbe`: it unpins the sandbox clock and undoes the probe's grant and timezone changes |
| Set `authorized_at` to now on a re-grant, or compute the chain | The SDK's grant journal is the only source of `authorized_at` |
| Pass `durability: 'durable'` to a store | Durability is read from the store; use `memoryStorage()` / `postgresStorage({ pool })` |
| Call `engine.reconcile` from request handlers | Use the managed `subscriptions` block (the engine is rung 3, `@adcp/sdk/reporting/advanced`) |
## Read next
- `docs/guides/REPORTING-SUBSCRIPTIONS-SELLER.md` and `docs/guides/REPORTING-SUBSCRIPTIONS-BUYER.md`
- `docs/guides/REPORTING-SUBSCRIPTIONS-COVERAGE.md`, `-ERRORS.md` and `-MIGRATION.md`
- `docs/guides/FIRST-CALL-TO-A-SELLER.md` for `accounts.ensure` outcomes and `accounts.change` (a separate account's `subscriptionsNotCovering`)
- `docs/guides/REPORTING-LEDGER.md` for the building blocks
Versions
The database has no other skills named reporting-subscriptions.
Database snapshot: 13.11.2026 · package version 218c1131f3e0 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100adcp
Interact with AdCP (Ad Context Protocol) advertising agents over MCP or A2A protocols. Use when the user wants to call AdCP tools (get_products, create_media_buy, sync_creatives, etc.), discover an agent's capabilities, run protocol compliance tests, look up brands or properties… - 100triage-storyboard-failure
Use when an AdCP compliance storyboard fails on an adapter you believe is spec-correct. Walks the rubric for deciding whether to fix the SDK, the adapter, or file upstream against the spec/storyboard. - 100rc-subscriptions
Use this skill when modeling subscriptions through RevenueCat's object model on Android. Covers Offerings, Packages, StoreProduct, SubscriptionOption, PricingPhase, and how they map to Google Play's Subscription, Base Plan, and Offer hierarchy. - 100azure-servicebus-py
Azure Service Bus SDK for Python messaging. Use for queues, topics, subscriptions, and enterprise messaging patterns. Triggers: "service bus", "ServiceBusClient", "queue", "topic", "subscription", "message broker". - 100azure-servicebus-py
|" Azure Service Bus SDK for Python messaging. Use for queues, topics, subscriptions, and enterprise messaging patterns. Triggers: "service bus", "ServiceBusClient", "queue", "topic", "subscription", "message broker". - 100absinthe-subscriptions
Use when implementing real-time GraphQL subscriptions with Absinthe. Covers Phoenix channels, PubSub, and subscription patterns.