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's not configured for your integration, you'll get a 400 with a clear "LayoutType X is not supported; supported: [...]" message 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" }
  ]
}

Store the page_identifier per merchant per 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:

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.