Operation Polling

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 write response carries an X-Operation-Id header. Capture it. If your HTTP client times out before reading the response, you can recover the original result by polling GET /v1/partnership/operations/{operation_id} — the server-side state machine has the canonical record, including the full response body of the original write.

When polling matters

The Partnerships API is mostly synchronous — happy-path writes return in well under one second. You only need polling when:

• Your HTTP client timed out and you never read the response.
• A network blip dropped the connection mid-write.
• You're orchestrating from a serverless / lambda runtime where re-invocation is cheaper than long-held sockets.

If you got a 200 back, don't poll — you already have the answer.

Capture the operation ID on every write

resp = requests.put(
    f"https://accounts.rokt.com/v1/partnership/accounts/{account_id}/marketplacecontrolslists",
    headers={
        "Authorization": f"Bearer {token}",
        "X-Platform-Parent-Account-Id": parent_account_id,
        "Idempotency-Key": idem_key,
    },
    json=payload,
    timeout=10,
)
operation_id = resp.headers.get("X-Operation-Id")
# Persist `operation_id` to durable storage BEFORE acting on resp.json().

The X-Operation-Id header is set as soon as the server allocates the operation row — even on errors. Log it before parsing the body so it survives a deserialization crash.

Operation IDs are scoped to your manager

Operation IDs are opaque strings — don't parse them or assume any structure. They are readable only by the authorized manager account that issued the write. Any cross-tenant read — whether the caller's authenticated parent doesn't own the operation or the X-Platform-Parent-Account-Id header doesn't match the operation's owner — returns 403. Possession of an operation ID alone never grants cross-account visibility. X-Platform-Parent-Account-Id is required on every poll; missing it returns 422.

Operation states

pending  ──▶  in_progress  ──▶  completed
                            ╲
                             ╲─▶  failed

State	Meaning
pending	Operation row created; processing hasn't started yet. Rare to observe — usually transient.
in_progress	Operation is executing steps. Keep polling.
completed	All steps succeeded. response_body contains the original write's response payload.
failed	At least one step failed and the operation rolled back what it could. response_body contains the error envelope.

Polling cadence

Use exponential backoff, capped, with a deadline. Recommended: start at 1s, double each attempt up to 30s, give up after 5 minutes.

python

import time, requests

def poll_operation(operation_id, token, parent_account_id, *, deadline_s=300):
    delay = 1.0
    start = time.monotonic()
    while time.monotonic() - start < deadline_s:
        resp = requests.get(
            f"https://accounts.rokt.com/v1/partnership/operations/{operation_id}",
            headers={
                "Authorization": f"Bearer {token}",
                "X-Platform-Parent-Account-Id": parent_account_id,
            },
            timeout=10,
        )
        envelope = resp.json()
        op = envelope["data"]
        if op["status"] in ("completed", "failed"):
            return op
        time.sleep(delay)
        delay = min(delay * 2, 30.0)
    raise TimeoutError(f"operation {operation_id} did not settle in {deadline_s}s")

node

async function pollOperation(operationId, token, parentAccountId, { deadlineMs = 300_000 } = {}) {
  let delay = 1000;
  const start = Date.now();
  while (Date.now() - start < deadlineMs) {
    const resp = await fetch(
      `https://accounts.rokt.com/v1/partnership/operations/${operationId}`,
      {
        headers: {
          Authorization: `Bearer ${token}`,
          "X-Platform-Parent-Account-Id": parentAccountId,
        },
      }
    );
    const envelope = await resp.json();
    const op = envelope.data;
    if (op.status === "completed" || op.status === "failed") return op;
    await new Promise((r) => setTimeout(r, delay));
    delay = Math.min(delay * 2, 30_000);
  }
  throw new Error(`operation ${operationId} did not settle`);
}

curl

# One-shot poll
curl https://accounts.rokt.com/v1/partnership/operations/9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e \
  -H "Authorization: Bearer $ROKT_TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT"

Response shape

Operation reads return the standard envelope; the operation record lives in data. The top-level status field is the HTTP status code — the operation lifecycle state (pending / in_progress / completed / failed) is data.status.

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": {
    "operation_id": "9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e",
    "status": "completed",
    "mode": "sync",
    "operation_type": "configure_partnership",
    "created_at": "2026-05-14T18:21:09Z",
    "completed_at": "2026-05-14T18:21:11Z",
    "next_retry_at": null,
    "retry_count": 0,
    "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
    "response_body": {
      "accountId": "<your-account-id>",
      "marketplaceControlsListId": "8c8e1c12-...",
      "contentHash": "h_xyz789"
    },
    "error": null
  }
}

For completed or failed operations, data.response_body is the exact payload the original write returned. You can take it and continue your workflow — no need to re-issue the PUT.

Walkthrough: recover from a client-side timeout

1. 1
   Register a merchant; client times out

   Your POST /v1/accounts/register/partnership call hits a 5-second client timeout. You never read the response.

2. 2
   But you logged the operation ID

   Your HTTP client buffered the response headers before the body timeout. You have:

   X-Operation-Id: 9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e

   (If you don't have the header either, fall back to Idempotency-Key replay — same key, same write.)

3. 3
   Poll until terminal

   curl https://accounts.rokt.com/v1/partnership/operations/9c7b1d2e-3a4f-4b5c-9d8e-1f2a3b4c5d6e \
     -H "Authorization: Bearer $ROKT_TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT"

   Response after ~2s:

   {
     "status": 200,
     "error": null,
     "message": "ok",
     "request_id": "0e3a1b9c-...",
     "data": {
       "operation_id": "9c7b1d2e-...",
       "status": "completed",
       "operation_type": "register_partnership",
       "response_body": { "account_id": "<your-account-id>" }
     }
   }

4. 4
   Use data.response_body as if it were the original response

   Treat data.response_body.account_id exactly like you would have treated the original 200 body. The write already happened; you've just recovered the receipt.

astuce

Polling and Idempotency-Key replay are two paths to the same recovery. Polling is preferred when you have the operation ID — it's a cheap GET that doesn't re-run validation. Replay is the fallback when only the key survived your crash.

Related

Idempotency Keys

The other recovery path for lost responses.

Operations API

Endpoint reference for GET /v1/partnership/operations/{operation_id}.