Manager & Managed Accounts

Audience

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.

Every Partnerships API call resolves two account identities: the manager (your partner platform) and the managed account (the merchant you onboarded). The manager-managed relationship is the auth boundary — your API token proves manager identity, and the {account_id} in the path identifies the managed account.

The two roles

• Manager account — your partner platform's parent account on Rokt. There is exactly one per partnership integration. Your API token is scoped to this account.
• Managed account — each merchant you've onboarded through the API. Created by POST /v1/accounts/register/partnership and identified by the Rokt-issued account_id returned in that response.

Manager Account  (your partner platform's parent)
        │
        │  manages
        ▼
┌───────┬───────────────┬───────────────┐
│       │               │               │
Managed A      Managed B       Managed C
(merchant)     (merchant)      (merchant)

Your merchant key: external_account_id

external_account_id is your stable identifier for the merchant — your platform's own primary key for that store, however you choose to format it. Rokt persists it on the managed account record and uses it for two distinct purposes:

• Idempotency on register. POST /v1/accounts/register/partnership is idempotent on (platform_parent_account_id, external_account_id). Re-sending the same registration payload with the same external_account_id returns the original account_id instead of creating a duplicate — register has no Idempotency-Key requirement, this field is the dedup key.
• Conflict surface on collision. If a different store registered earlier under the same external_account_id (for your platform_parent_account_id), or a different partner platform already owns this merchant's store_identifier, register returns 409. The two collision keys are independent — external_account_id collisions are your-side duplicates; store_identifier collisions are cross-platform conflicts.

Choosing a good external_account_id

• Stable. Pick a value that doesn't change for the lifetime of the merchant on your platform. Register is idempotent on this exact string — changing it on a retry creates a duplicate Rokt account.
• Unique per manager. Scope is (platform_parent_account_id, external_account_id). The same string under two different partner platforms is fine; the same string twice under your own platform is the 409 case above. You don't need a globally unique ID.
• Non-sensitive. This value appears in Rokt server logs, support tickets, and the response envelope. Use an opaque platform-internal merchant ID; don't put the merchant's email, billing identifier, or any PII in it.
• Pick one canonical value per merchant in your system and never reuse it across merchants.

How you tell the server who you are

Every write call must carry the X-Platform-Parent-Account-Id header with your partner platform's parent account ID:

X-Platform-Parent-Account-Id: <your-platform-parent-account-id>

The server uses it to verify you actually manage the target account_id in the path. Missing it on a write returns 422. Sending a value that doesn't match the managed account's real parent returns 403. Reads accept the header as optional but recommended on every call for clarity.

POST /v1/accounts/register/partnership is a special case: platform_parent_account_id is part of the request body (the managed account doesn't exist yet so there's no path account to verify against), and you should also send X-Platform-Parent-Account-Id as the header for consistency.

note

A future release will let you drop the header. Your Rokt contact will let you know when this happens.

Enumerating your managed accounts

List every merchant you currently manage. The list endpoint requires ?parent_account_id=<your-parent> as a query param (the same value you put in the header):

curl

curl 'https://accounts.rokt.com/v1/partnership/accounts?parent_account_id=<your-platform-parent-account-id>' \
  -H "Authorization: Bearer $ROKT_TOKEN" \
  -H "X-Platform-Parent-Account-Id: <your-platform-parent-account-id>"

python

import requests

resp = requests.get(
    "https://accounts.rokt.com/v1/partnership/accounts",
    params={"parent_account_id": parent},
    headers={
        "Authorization": f"Bearer {token}",
        "X-Platform-Parent-Account-Id": parent,
    },
)
managed_accounts = resp.json()["data"]

node

const url = new URL("https://accounts.rokt.com/v1/partnership/accounts");
url.searchParams.set("parent_account_id", parent);
const resp = await fetch(url, {
  headers: {
    Authorization: `Bearer ${token}`,
    "X-Platform-Parent-Account-Id": parent,
  },
});
const { data: managedAccounts } = await resp.json();

The response wraps the list in the standard envelope; the array lives in data:

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-...",
  "data": [
    {
      "account_id": "<your-account-id>",
      "brand": "Acme Apparel",
      "country_code": "US",
      "external_account_id": "partner-merchant-abc123",
      "status": "active",
      "created_at": "2026-04-12T18:21:09Z",
      "updated_at": "2026-05-02T14:00:00Z"
    }
  ]
}

Inspecting a single managed account

A consolidated single-account endpoint (GET /v1/partnership/accounts/{account_id}) is not yet exposed on the partner surface. To inspect one merchant, query the per-resource reads:

• GET /v1/partnership/accounts/{account_id}/marketplacecontrolslists
• GET /v1/partnership/accounts/{account_id}/status
• GET /v1/partnership/accounts/{account_id}/payout-setup/status

Each one verifies that the caller (resolved from your API token, optionally cross-checked against X-Platform-Parent-Account-Id) is the current manager of the path account before returning. Anyone else gets 403.

When you get 403

If you call any read or write endpoint on a managed account you don't manage — or whose manager-managed relationship was revoked — you get 403 Forbidden with this envelope:

{
  "error": "API token valid but missing required relationship grant",
  "request_id": "req_01HX9F2J7M3K8N5VYBQZP4R6T2"
}

The API token is fine; the relationship is the problem. Common causes:

• The managed account was migrated to a different partner platform.
• The merchant disconnected your integration from inside their Rokt admin.
• You hardcoded an account_id belonging to a different partner.

warning

Don't retry a 403. It's not transient. Pass the request_id to smb-partnerships@rokt.com if the relationship should still be active.

Related

Idempotency Keys

Required header on every write call.

SET Semantics

Why PUT replaces, never merges.