Pausing & Resuming a Partnership

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.

The status PUT is a single coarse switch that cascades active/paused across every non-archived page variant on the account. Archived variants are unaffected. There is no per-page or per-variant pause via the Partnerships API — that's a Rokt-internal operation.

Use this for: merchant-requested temporary pauses, fraud holds, dispute resolution, planned platform maintenance.

1. 1
   Pause the partnership

   PUT /v1/partnership/accounts/{account_id}/status with { "status": "paused" }. Every non-archived variant gets disabled in one transaction.

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{ "status": "paused" }'

   The response is the same envelope wrapping StatusCascadeResponse you get from GET — aggregate plus per-variant detail under data.

2. 2
   Verify the pause

   Round-trip the status GET. Aggregate status should be "paused", and every entry in variants should show "paused".

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT"

   {
     "status": 200,
     "error": null,
     "message": "ok",
     "request_id": "0e3a1b9c-...",
     "data": {
       "accountId": "<your-account-id>",
       "status": "paused",
       "variants": [
         { "pageVariantId": "...", "pageId": "...", "name": "Confirmation - Default", "status": "paused" },
         { "pageVariantId": "...", "pageId": "...", "name": "Confirmation - Mobile",  "status": "paused" }
       ]
     }
   }

3. 3
   Resume the partnership

   When you're ready to re-enable, PUT status: "active". Same cascade in the opposite direction.

   curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{ "status": "active" }'

4. 4
   Verify the resume

   GET status. Aggregate should be "active" and every non-archived variant should show "active".

   curl https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/status \
     -H "Authorization: Bearer $TOKEN" \
     -H "X-Platform-Parent-Account-Id: $PARENT"

Round-trip identity

After a successful PUT status=paused, GET status must return "paused". After PUT status=active, GET status must return "active".

warning

The interpretation of "mixed" depends on whether it came from the PUT response or a GET.

• "mixed" returned by the PUT itself (or by a GET status issued immediately after a PUT, before any other actor could have touched the account) is a bug condition: the cascade failed to update some variants. File a support ticket with your Idempotency-Key and the request_id from the PUT response envelope. Include the per-variant breakdown from the GET so support can target the specific stuck variants.
• "mixed" returned by a steady-state GET status (i.e. you haven't just issued a PUT, or enough time has passed that other actors may have changed things) is not necessarily a bug — see the next section for legitimate causes.

What "mixed" means on a GET

Outside the immediate post-PUT window, "mixed" is a legitimate steady-state value — it doesn't only show up after a failed cascade. You'll see it on GET status when:

• The partner archived some page variants and not others, and the non-archived set is split.
• Rokt support has manually toggled individual variants outside the Partnerships API (e.g. during an incident).
• A previous status cascade partially failed and was never retried.

The aggregate status is computed across non-archived variants only. The variants array shows you exactly which variant is in which state — use it to decide whether "mixed" is expected (partner-driven archiving, Rokt-side toggle) or a problem (cascade bug, in which case escalate as described in the warning above).

Idempotency

The status PUT is fully idempotent on Idempotency-Key:

• Re-sending the same { "status": "paused" } with the same key within the 24-hour dedup window returns the cached result.
• After the 24h window the key expires; re-using it triggers a fresh execution. Use a fresh UUID per logical retry group.
• Re-sending the same payload with a fresh key is a no-op write — already-paused variants stay paused, the server returns the current cascade response in data.

Retries are free. Use exponential backoff if you hit a 5xx.

Why coarse-grained?

The Partnerships API intentionally exposes only an account-level pause. Per-page and per-variant control belongs in the Rokt One Platform UI, where Rokt operations and the partner's own internal tools can coordinate. Keeping the partner-facing surface coarse avoids two failure modes:

1. Partners building UIs that drift out of sync with Rokt-side variant changes.
2. Hard-to-debug partial-pause states where revenue silently halves because half the variants are down.

If you need per-variant control, file a Partnerships engineering request — we'll evaluate whether it belongs in the API or in a supported back-channel.