# MeetROAS Partner Event API

A destination platform sends business events to MeetROAS once; MeetROAS handles traffic-platform reporting from mr_click_id and customer configuration.

- Production endpoint: `POST https://api.meetroas.com/v1/events`
- Validation endpoint: `POST https://api.meetroas.com/v1/events/validate`
- Machine event catalog: `GET https://api.meetroas.com/v1/events/catalog`
- OpenAPI: https://developers.meetroas.com/openapi.json

## Credentials

The customer account Admin opens Conversions → Destination partner API in MeetROAS and creates a Key ID and Secret. The Secret is shown once and must be stored in a server-side secrets manager; no MeetROAS contact is required.

## Authentication

1. Serialize JSON once and preserve the final raw body.
2. Generate a Unix-seconds timestamp.
3. `signature = "v1=" + lowercase_hex(HMAC_SHA256(secret, timestamp + "." + raw_body))`
4. Send headers: `Content-Type: application/json`, `X-MeetROAS-Key`, `X-MeetROAS-Timestamp`, `X-MeetROAS-Signature`.

## Request

```json
{
  "event_id": "test-dd76e98e-7c1b-481a-a693-a13b4573d0ec",
  "mr_click_id": "mrc_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "event": "purchase",
  "occurred_at": "2026-08-10T17:03:07.110Z",
  "value": 49.95,
  "currency": "USD"
}
```

- `event_id`: 1–128 character idempotency key; preserve it when retrying the same fact.
- `mr_click_id`: Opaque ID received from and persisted from the destination URL.
- `occurred_at`: ISO-8601 UTC within 31 days.
- `value`: Optional decimal amount from 0 to 1,000,000,000 with up to six decimals; not minor units.
- `currency`: Optional uppercase ISO 4217 code; requires value when present.

## Accepted events

| event | Meaning | repeatability | monetary |
|---|---|---|---|
| `account_registration` | The user completed the destination platform's account registration flow; a page view or incomplete form does not qualify. | once_per_click | forbidden |
| `first_deposit` | The account's first verified deposit became effective; pending or failed transactions do not qualify. | once_per_click | optional |
| `deposit` | A verified deposit became effective; this event is repeatable. | repeatable | optional |
| `purchase` | A payment or purchase was verified and settled successfully; pending, failed, or refunded transactions do not qualify. | repeatable | optional |

## Validation and go-live

First send the same schema and signature to the validation endpoint. After HTTP 200 with valid=true, test production using a real mr_click_id from a test visitor. Validation creates no production event.

## Responses

- `200`: Validation passed or a duplicate was already processed.
- `202`: Production event accepted for the first time.
- `400/415`: Fix the body, fields, or Content-Type.
- `401`: Check credentials, server time, and the signed raw body.
- `404`: mr_click_id cannot be resolved or owned.
- `409`: event_id identifies different business facts.
- `429/5xx`: Retry with exponential backoff and jitter while preserving event_id and body.

## Supported traffic platforms

TrafficStars, PropellerAds, RichAds, ExoClick.

Planned: Adsterra, MGID, BidVertiser, HilltopAds, GeeMee, MGSkyAds.