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: customize a layout, switch the page to the other layout type, customize 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, customization properties), 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 customization properties you want to change; everything else is preserved. Vertical controls behave the same way; domains and status do not. See Update Semantics.

1. 1
   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 customizations 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" }
     ]
   }

2. 2
   Apply customizations

   Send a sparse PATCH to the layout. Eleven customization properties are exposed and every one is optional — send only what you want to change:

   Area	Tokens
   Containers	backgroundColor, borderRadius, closeButtonColor
   Header	headerBackground, headerForeground
   Text	textColor, fontFamily
   Buttons	buttonBackground, buttonForeground, buttonBorderRadius
   Progress	primaryColor

   See Pages and Layouts for what each one covers and for the font families available on every account.

   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 '{
       "headerBackground": "#102A43",
       "headerForeground": "#FFFFFF",
       "buttonBackground": "#FF6B35",
       "buttonForeground": "#FFFFFF",
       "buttonBorderRadius": 8,
       "fontFamily": "Georgia"
     }'

   The response's data field contains:

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

   layoutTemplateVersion 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.

Dry-run availability

Layout customization and page switching reject dry_run=true with 400 DryRunNotSupported before work is performed. Verify real updates on your stage merchant.

Validation

Use only the curated fonts and supported values. Unsupported fonts or a readable template that does not support the requested customization return 422 before saving. A missing internal template/schema returns 500 without saving. Expanded customization can return 503 while unavailable; original-only requests retain their existing availability.