Customizing Layouts

Audience

This API surface is for integration partners building on top of the Rokt network. Rokt ecommerce partners building their own direct integration should refer to the Rokt Ecommerce SDK Integration Guide.

This recipe covers the full layout-customization lifecycle on an already-onboarded merchant: theme a layout, switch the page to the other layout type, theme the new layout, and switch back. Two endpoints carry the work — the layout PATCH and the page-switch PUT — and the registration response gives you the identifiers both need. For the underlying model (surfaces, layout types, theme tokens), see Pages and Layouts.

note

The layout-edit endpoint is the one PATCH surface in the partnership API — it accepts sparse updates. Send only the theme keys you want to change; everything else is preserved. This is the opposite of the SET semantics on the controls endpoints.

Capture layout_id and page_id from registration

Every pages[] entry on the registration (or add-pages) response carries the two identifiers this recipe uses: layout_id for theme edits and page_id for layout-type switches. Store both per merchant per surface.

{
  "account_id": "<your-account-id>",
  "pages": [
    { "surface": "confirmation", "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc", "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd", "page_identifier": "confirmation_page" }
  ]
}

Apply theme edits

Send a sparse PATCH to the layout. Five theme tokens are exposed — primaryColor, backgroundColor, textColor, borderRadius, closeButtonColor — and all five are optional.

curl -X PATCH https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/layouts/9d11d8aa-5678-4def-9abc-bbbbccccdddd \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#FF6B35",
    "backgroundColor": "#FFFFFF",
    "borderRadius": 8
  }'

{
  "status": "ok",
  "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd",
  "layout_template_version": "3.0.7"
}

layout_template_version is the template version the layout was saved on — Rokt auto-bumps to the latest published patch on every save, so it may be higher than what was stored before your edit.

Switch the page's layout type

Move the page to the other layout type (here Overlay → Embedded) with the page-switch PUT. The page_id is the one captured in step 1.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages/bfb5b9be-1234-4abc-9def-aaaabbbbcccc \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_integration": "<your-preset-key>",
    "layout_type": "Embedded"
  }'

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": {
    "status": "ok",
    "page": {
      "surface": "confirmation",
      "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc",
      "layout_id": "f8700369-5678-4def-9abc-bbbbccccdddd",
      "page_identifier": "confirmation_page"
    }
  }
}

The response's data.page.layout_id is the layout now active on the page — capture it, because subsequent theme edits must target this ID. The layout_id from step 1 now refers to the inactive layout. page_id and page_identifier are unchanged: your SDK code keeps passing the same identifier into selectPlacements, though an Embedded layout needs <div id="rokt-container"></div> on the merchant's page.

note

Requesting the layout_type the page already uses will receive a 200 response, and no change will be made. This is safe to call as part of a reconciliation loop.

Theme the new layout (optional)

The new layout starts from the canonical Rokt template for its type — theme edits from step 2 belong to the old layout, not this one. PATCH the layout_id captured from the switch response if the merchant wants the new layout themed too.

curl -X PATCH https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/layouts/f8700369-5678-4def-9abc-bbbbccccdddd \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "primaryColor": "#FF6B35",
    "borderRadius": 8
  }'

Switch back — theme edits are preserved

Switching back to a layout type the page used before restores the previous layout, including its theme edits. The response returns the original layout_id from step 1 — the primaryColor, backgroundColor, and borderRadius you set in step 2 are still applied.

curl -X PUT https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages/bfb5b9be-1234-4abc-9def-aaaabbbbcccc \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Platform-Parent-Account-Id: $PARENT" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "platform_integration": "<your-preset-key>",
    "layout_type": "Overlay"
  }'

{
  "status": 200,
  "error": null,
  "message": "ok",
  "request_id": "0e3a1b9c-1234-4abc-9def-aaaabbbbcccc",
  "data": {
    "status": "ok",
    "page": {
      "surface": "confirmation",
      "page_id": "bfb5b9be-1234-4abc-9def-aaaabbbbcccc",
      "layout_id": "9d11d8aa-5678-4def-9abc-bbbbccccdddd",
      "page_identifier": "confirmation_page"
    }
  }
}

Common errorsDirect link to Common errors

422 — unrecognised layout_type value

Returned when layout_type is not a recognised enum value (e.g. a typo or unknown string). API input validation catches this before the request reaches the transactions layer. Check the value you passed against the documented enum: Overlay and Embedded.

400 — layout_type valid but not supported for this surface

Returned when layout_type is a valid enum value but not supported for this page's surface on your integration. The error message names the values your preset accepts. Reach out to your Rokt contact if you're unsure what your integration accepts.

404 — unknown page or layout

The page_id (on the switch PUT) or layout_id (on the theme PATCH) doesn't exist on the account, has been archived, or the account_id isn't accessible to your manager account. Re-check the identifiers against the registration or add-pages response — and remember that after a switch, the theme PATCH must target the layout_id from the switch response, not the one you captured before it. See Errors for the envelope shape.

422 — page or layout not in an editable/switchable state

The page wasn't created through the partnership flow (switch PUT), or the layout wasn't created through partnership onboarding (theme PATCH). Every page_id and layout_id returned by registration or add-pages is switchable and editable, so partners using the standard flow shouldn't see this. A 422 with error: "ValidationFailed" instead means a required header is missing — check X-Platform-Parent-Account-Id.

Both endpoints share the standard write rate limits — on a 429, honor Retry-After and retry with the same Idempotency-Key.