Overview
This API surface is for integration partners building on top of the Rokt network. Rokt ecommerce partners integrating placements on their own checkout should use the Rokt Ecommerce developer docs instead.
The Rokt Partnerships API is a REST API for partner platforms that onboard and manage merchants on the Rokt network. Use it to register merchants, configure marketplace controls, manage placement status, and start payout onboarding without using the Rokt UI.
Access is granted by Rokt. The Partnerships API is not self-serve yet. Rokt issues your platform's long-lived API credentials (client_id + client_secret) once, during onboarding, and you reuse the same credentials for every access-token exchange. Email smb-partnerships@rokt.com with your platform name, expected merchant volume, and the manager account ID you've been assigned; see Authentication for the full flow.
Your category taxonomy is seeded before you register anything. Rokt maps your platform's categories to its own, once per platform, during onboarding. An unmapped category fails register with a 400, so send your complete category list to smb-partnerships@rokt.com early and confirm the rows landed with GET /v1/partnership/vertical-mappings. See Check what's mapped.
This API surface is in active development. Payloads, endpoints, and behavior may shift. Rokt will notify you of any breaking change.
Key conceptsDirect link to Key concepts
Your platform is represented as a manager account. The merchants you onboard are managed accounts. Rokt authorizes every request using your API token and the target {account_id} in the request path: the target account must be managed by your manager account, and requests for unrelated accounts are rejected server-side.
your platform (manager)
│
├── merchant A (managed account)
├── merchant B (managed account)
└── merchant C (managed account)
These four concepts are required to integrate safely. Read these before writing any code.
How Rokt derives caller context from your API token and authorizes against the target account_id.
Every write call requires an Idempotency-Key. Sending the same key twice returns the cached response, so it's safe to retry.
PUT replaces the full list. Controls endpoints (MCL, status) have no PATCH or merge. Send the complete desired state every time. The layout-edit endpoint is the one PATCH surface in V1; it accepts sparse updates of the five theme tokens.
dry_run=true runs the full validation and returns the would-be response without persisting state. Use it to validate payloads before going live.
What you can doDirect link to What you can do
- Register a merchant:
POST /v1/accounts/register/partnership. Idempotent onexternal_account_id(your stable identifier for the merchant; keep it non-sensitive; see Idempotency for the uniqueness scope). - List managed accounts:
GET /v1/partnership/accounts?parent_account_id=<your-parent>. A single-account detail endpoint is not yet exposed; use the per-resource reads below to inspect an individual managed account. - Check your seeded vertical mappings:
GET /v1/partnership/vertical-mappings?parent_account_id=<your-parent>returns your seeded category mappings, in your own taxonomy. Read-only; Rokt creates the rows. An empty list means nothing is seeded and every register will fail with a400. See Check what's mapped. - Read & update marketplace controls:
GET/PUT /v1/partnership/accounts/{account_id}/marketplacecontrolslists. Block verticals in your partner taxonomy; Rokt translates server-side. - Pause or resume placements:
PUT /v1/partnership/accounts/{account_id}/statuscascades active/paused across every non-archived page variant. - Edit a merchant's theme:
PATCH /v1/partnership/accounts/{account_id}/layouts/{layout_id}accepts a sparse update of the five theme tokens (primaryColor,backgroundColor,textColor,borderRadius,closeButtonColor). See Pages and Layouts and the Customizing Layouts workflow. - Add a surface post-launch:
POST /v1/partnership/accounts/{account_id}/pagesattaches another surface (confirmation, tracking, returns) to an already-onboarded merchant without re-registering. See Pages and Layouts. - Switch a page's layout type:
PUT /v1/partnership/accounts/{account_id}/pages/{page_id}moves an existing page between Overlay and Embedded without changing itspage_identifieror URL targeting. See Pages and Layouts and the Customizing Layouts workflow. - Start payout onboarding:
POST /v1/partnership/accounts/{account_id}/payout-setupinitiates Stripe Connect onboarding for a merchant. In V1, Rokt pays the partner-side payout (your platform's revenue share, per your partnership agreement) to your manager account, not to individual managed accounts; distributing each merchant's portion is your platform's responsibility. See the merchant onboarding workflow. - Submit consumer network privacy requests:
POST /v1/partnership/network-privacy-requestshandles network opt-out and network data deletion by consumer identifier. See Privacy Requests. - Submit managed-account data deletion:
POST /v1/partnership/accounts/{account_id}/data-deletion-requestsrequests account-level deletion for a merchant your platform manages. See Privacy Requests. - Poll long-running operations: every write returns
X-Operation-Id.GET /v1/partnership/operations/{operation_id}recovers from network timeouts without re-issuing the write. Operation IDs are opaque and only readable by the authorized manager, so polling cannot expose status for unrelated accounts.