Advertiser integration

As an advertiser you fund rewards in advance, bind that funding to your creatives or campaigns, and pay only when a viewer claims a verified view. This page covers the account, the funding model, creative binding, and how you observe and reconcile every claim.

1. Your account

Advertiser access lives in the business portal. You sign in with email (one-time code) or Google; the advertiser role is granted to your account by the My Ad Rewards team at onboarding. Portal data is scoped to your account: a funding program belongs to the account that owns it, and programs owned by someone else are invisible to you — requests for another owner's program return 404, exactly as if it didn't exist.

2. Funding: programs, deposits, bindings

Your rewards budget is a funding program — a prepaid points balance the platform draws from only at claim time. Three pieces make it work:

Piece	What it holds
Program	Your budget container: an owner (your account), a funding kind (advertiser-funded, publisher-funded, or platform seed), a points balance, and per-action reward amounts (`action_rates`) for each claim surface — for example the `view` rung for a verified view and the `scan` rung for a scan claim.
Deposit	Tops the program up: a deposit adds a points `amount` to the balance. Deposits, balance, and the full transaction history are visible in the portal.
Binding	Attaches the program to traffic: a `creative_id`, a `campaign_id`, or a `publisher_id`. Bindings are how an event finds its funder.

Programs, deposits, and bindings are administered with our team during onboarding and managed day-to-day in the business portal. The funding API is listed in the API reference.

Which funder pays for a view?

Exactly one — never two. When a pair verifies, funding resolves in this order:

1
An advertiser-funded program bound to the event's creative_id.
2
Else, an advertiser-funded program bound to its campaign_id.
3
Else, a publisher-funded program bound to the publisher_id (the publisher paying for its own audience's loyalty).
4
Else the view verifies with no reward attached.

Nothing is drawn when a view verifies — the draw happens at claim, as a single transaction covering the viewer's award, the platform issuance fee, and any configured venue share. Unclaimed rewards expire and draw nothing. If the matched program's balance can't cover a claim, the claim is refused (402) rather than partially paid.

3. Creative and campaign binding

Binding works on the IDs your creatives already carry. The publisher's tag reports a creative_id (and campaign_id when set) with every event, so the IDs in your bindings must match the IDs on the trafficked creative exactly. Two ways the tag gets onto your creative:

Riding the creative (ad server). The publisher traffics the tag with your creative in their ad server; the creative's ID is passed through the tag. See the publisher guide, §6.
On the page. The publisher places the tag in the page and sets data-creative-id on the slot your creative fills.

Campaign-level bindings are the forgiving option during rollout: bind the campaign first, then add creative-level bindings for tighter control — creative bindings win when both match.

4. Reporting and webhooks

Three views of the same ledger:

Business portal — your programs, balances, bindings, and claim activity, scoped to your account.
Webhooks — a real-time event stream to your endpoint (below).
Reports API — the platform's daily aggregates and per-publisher reconciliation are operator-run today; your portal and webhook stream carry the same underlying transactions. The endpoints are documented in the API reference.

Webhooks

Webhook delivery is configured for your deployment at onboarding — give our team your HTTPS endpoint and store the shared secret we issue. Every delivery is a POST with this envelope:

POST https://your-endpoint.example/hooks
X-AdRewards-Signature: <hex HMAC-SHA256 of the raw body, keyed with your secret>

{
  "event": "points.issued",
  "data": {
    "txn_id": "…", "user_id": "…", "device_id": "…",
    "publisher_id": "pub_123", "app_id": "app_9",
    "creative_id": "adv_42:cre_7",
    "mode": "advertiser", "award": 25,
    "source_kind": "ad_view", "rung": "view"
  },
  "sent_at": "2026-09-27T20:01:03Z"
}

Field	Meaning
`event`	`points.issued` when a claim pays out; `survey.response` when a rewarded survey is answered (`survey_id`, `response_id`, `reward_points`, `txn_id`).
`data.mode`	Which funding kind paid: `advertiser`, `publisher`, or `seed`.
`data.source_kind`	What earned it: `ad_view`, `survey`, `bonus`, `cashback`, `scan`, or `capture`.
`data.award`	Points issued to the viewer for this transaction.
`data.txn_id`	The ledger transaction ID — the join key for reconciliation.

Verify X-AdRewards-Signature before trusting a delivery. Failed deliveries (network errors, 5xx, 429) are retried up to 5 attempts with backoff starting at 1 second and doubling; other 4xx responses are treated as permanent failures.

5. Reconciliation

One claim, one transaction. Every payout has a unique txn_id, delivered in the claim response and the points.issued webhook. Match on it.
Draws happen at claim time, inside the claim window (24 hours by default) — so a day's views and a day's draws are related but not identical. Unclaimed views never draw.
Claim outcomes are explicit: 200 claimed, 409 already claimed, 410 expired, 402 the funding program couldn't cover it. Your balance and transaction history in the portal reflect every draw.
Duplicates can't double-pay. The events API deduplicates reports, a verified pair settles once, and a scan token outstanding on a view blocks the device-claim path for the same view.