Pages and Layouts

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.

Most partner integrations let each merchant render Rokt placements on more than one surface. The optional pages array on POST /v1/accounts/register/partnership declares which surfaces a merchant uses and what layout style each surface gets. Rokt creates one page and one layout per entry and returns the identifiers your SDK code needs to render them.

The three surfaces

Each entry in pages picks one of three surfaces. Each maps to a distinct page context with Rokt-side rules tuned for that intent.

surface	When to use it	Counts as a transaction?
confirmation	The order confirmation page shown immediately after checkout completes.	Yes
tracking	The shipment or order tracking page the customer visits post-purchase.	No
returns	The returns portal where the customer initiates or views a return.	No

confirmation is a transactional surface. tracking and returns are post-purchase engagement surfaces; they deliberately do not record transactions even though they appear after checkout. Use the surface that matches the customer's intent on that page — not the one closest to your internal page name.

remarque

The payment surface (the page shown during checkout, before the order completes) is intentionally deferred to a later release — payment pages need their own controls and reserve-quality treatment that's still being scoped. Reach out to your Rokt contact if you have a payment-surface use case.

The two layout types

Each pages entry pairs the surface with a layout style.

Overlay

A modal that appears over the merchant's page when the placement triggers. Best for surfaces where you want the customer's full attention.

Embedded

Renders inline within an anchor element on the merchant's page. The default anchor selector is #rokt-container — the merchant's page must include <div id="rokt-container"></div> where the placement should render.

You can mix and match Overlay and Embedded — for example, Overlay on confirmation and Embedded on tracking — by listing each surface separately in the pages array with its own layout_type.

remarque

Some integrations only support a subset of layout types. If you pass a layout_type that is not a recognised enum value (e.g. a typo or unknown string), you'll get a 422 from the input validation layer. If layout_type is a valid enum value but not supported for this page's surface on your integration, you'll get a 400 from the server naming the allowed values. Reach out to your Rokt contact if you're unsure what your integration accepts.

Each integration has a default

Your integration ships with a pages default tailored to its expected surfaces and layout types. Omit the field on registration to use it. Pass pages to override — useful when you want a different layout type per surface, or only a subset of the default set. If you pass a (surface, layout_type) combination your integration doesn't support, you'll get a 400 naming the supported values. Sending pages: [] is treated the same as omitting the field.

Request and response

Pass the array on POST /v1/accounts/register/partnership:

{
  "brand": "Acme Apparel",
  "vertical_id": 1500,
  "sub_vertical_id": 1610,
  "country_code": "US",
  "platform_parent_account_id": "<your-platform-parent-account-id>",
  "store_identifier": "https://acme-apparel.example.com",
  "external_account_id": "partner-merchant-abc123",
  "pages": [
    { "surface": "confirmation", "layout_type": "Overlay"  },
    { "surface": "tracking",     "layout_type": "Embedded" },
    { "surface": "returns",      "layout_type": "Embedded" }
  ]
}

The response carries a matching pages array with one entry per surface. Each entry tells your SDK code which page_identifier string to pass into selectPlacements:

{
  "account_id": "<your-account-id>",
  "pages": [
    { "surface": "confirmation", "page_id": "bfb5b9be-...", "layout_id": "9d11d8aa-...", "page_identifier": "confirmation_page" },
    { "surface": "tracking",     "page_id": "2b9d8a5e-...", "layout_id": "f8700369-...", "page_identifier": "tracking_page" },
    { "surface": "returns",      "page_id": "7a31963a-...", "layout_id": "4865f1ab-...", "page_identifier": "returns_page" }
  ]
}

The page_identifier values (confirmation_page, tracking_page, returns_page) are fixed constants defined by Rokt for your integration type. Every merchant you register receives the same identifiers — they are not per-merchant values. Store them in your SDK integration to route placements to the correct surface.

Your SDK code reads this string and passes it into selectPlacements:

await launcher.selectPlacements({
  identifier: "confirmation_page",   // ← from the response above
  attributes: { email: customer.email, /* ... */ }
});

See SDK Integration for the full SDK setup.

Validation rules

The endpoint rejects requests with descriptive 400 errors when:

• A surface value is not one of confirmation / tracking / returns.
• A layout_type value is not declared in your integration's preset. The full set is Overlay and Embedded — your integration may support only a subset. The error message names the values your preset accepts.
• The same surface appears more than once in the array.
• The pages array is present but empty (omit the field to use the preset default, or include at least one entry).
• Your integration's preset has no LayoutSpecs configured at all. Contact Rokt if you see this error.

Customizing a merchant's layout

The registration response carries a layout_id per page. You can theme an existing layout by sending a sparse PATCH to /v1/partnership/accounts/{account_id}/layouts/{layout_id}. Five theme tokens are exposed today:

• primaryColor — interactive accents (progress controls / indicators)
• backgroundColor — outer/main and body container backgrounds
• textColor — header, paragraph, and footer text colors
• borderRadius — corner radius on containers (0–24 px)
• closeButtonColor — close button text + border (Overlay only)

All five fields are optional. Send only the keys you want to change; everything else stays as it is. Rokt also auto-bumps the underlying template to the latest published patch on every save, so your merchants pick up small upstream fixes without any action on your side.

remarque

Font family overrides are not yet exposed on this endpoint — they require the partner to first upload the font against the account, which doesn't have a partner-facing endpoint today. Custom fonts will land in a later release alongside that upload flow. If you need a non-default font in the meantime, reach out to your Rokt contact.

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
  }'

For deeper customization (new theme keys, copy overrides), reach out to your Rokt contact.

Adding pages after registration

Need to add a surface to a merchant that's already been registered (e.g. add a tracking page to a merchant who only had confirmation configured)? POST /v1/partnership/accounts/{account_id}/pages accepts the same surface + layout_type entries as the registration pages array:

remarque

The value for platform_integration is the identifier for your integration (for example, your-integration-name) — the same for every merchant you register. Rokt sets this when configuring your integration.

curl -X POST https://accounts.rokt.com/v1/partnership/accounts/<your-account-id>/pages \
  -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>",
    "pages": [
      { "surface": "tracking", "layout_type": "Embedded" }
    ]
  }'

Each entry creates a new Page and a per-merchant templated Layout linked to the canonical Rokt template for that layout type. The response carries the same pages shape as registration — store the returned page_identifier per surface and pass it into the Web SDK.

Today's add-page endpoint does not link the new pages to your account's targeting rule set. If your integration depends on rule-set linkage, configure the full surface set on the original registration call.

Calling twice for the same surface returns 422 from the underlying handler (not a clean 409) — V1 limitation. Track which surfaces exist on an account from your registration response's pages[].page_identifier.

Switching layout types

If you need to change the layout type for an existing page (for example, when a merchant wants to change from Overlay layouts on their confirmation page to Embedded layouts), call PUT /v1/partnership/accounts/{account_id}/pages/{page_id} where {page_id} is the ID for the page you want to update. The switch does not re-register the merchant or recreate the page. The page_id is the one returned in pages[].page_id on the registration or add-pages response:

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"
  }'

The layout types a page can switch to are the same set your integration's preset accepts at registration and on add-pages. If you pass a layout_type that is not a recognised enum value (e.g. a typo or unknown string), you'll get a 422 from the input validation layer. If layout_type is a valid enum value but not supported for this page's surface on your integration, you'll get a 400 from the server naming the allowed values — same contract as registration.

Three things the switch does not change:

• The page_identifier stays the same. Your SDK code keeps passing the same identifier into selectPlacements — no merchant-side change needed beyond the anchor element (an Embedded layout still needs <div id="rokt-container"></div> on the merchant's page).
• The page's URL targeting stays the same. The switch only changes how placements render, not where the page fires.
• Theme edits are preserved. Customizations applied via the layout PATCH endpoint stay with their layout — switching back to a layout type the page used before restores the previous layout, including its theme edits.

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.

The response carries the layout_id now active on the page. Use that value for subsequent theme edits — a layout_id you captured before the switch refers to the now-inactive layout:

{
  "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 endpoint returns 404 if the page_id (or account_id) doesn't exist or isn't accessible to your manager account, and 422 if the page isn't in a switchable state — every page_id returned by registration or add-pages is switchable, so partners using the standard flow shouldn't see the 422 case.