---
title: "Create a landing page display"
method: POST
path: "/v3/pages/{page_id}/page-displays"
tags: ["Landing Pages"]
---

# Create a landing page display

`POST /v3/pages/{page_id}/page-displays`

## Request

- Base URL: `https://api.scalev.com`
- URL: `https://api.scalev.com/v3/pages/{page_id}/page-displays`
- Auth: one of:
  - HTTP bearer
  - API key in header `authorization`
  - OAuth 2
    - Authorization code: `https://api.scalev.com/v3/oauth/authorize`
    - Token URL: `https://api.scalev.com/v3/oauth/token` scopes: `page:update`

Creates a new display for an existing landing page. The request body below documents the HTML Mode page display payload. Saving the first checkout form initializes an unbound page's `store_id` from `form_display.store_id` immediately, before publication. The store must belong to the same business. An existing page store association is retained and cannot be changed or cleared by later display saves.

## Request body

- LandingPageDisplayVersionRequest: Settings-only versions may omit source fields. An omitted form_display preserves checkout configuration; explicit null removes the form only where the page's existing store-context rules allow it. Clearing an authoritative html_document is rejected with 422. Once the owner has saved tracking_config, effective changes through legacy tracking fields also require its current tracking_config_revision; unchanged legacy echoes remain compatible. Stale legacy changes return 409.
  - `tracking_config_write_version` 1, required: Required beside every supplied tracking_config, including new page creation. Version 1 declares that the writer preserves same-name channel bindings, initialization markers, legacy_document_only, legacy_document_server_only, parameter_variants and additional event metadata. It is a request capability, separate from tracking_config.schema_version. Missing or unsupported versions return 409; update the client and reload the current editor response before retrying. Omit for legacy-only writes.
  - `tracking_config` TrackingConfig: Authoritative merchant tracking selections, limited to 256 KiB. Empty selections send nothing. Trigger and event enablement flags are not used; remove an event selection to stop sending it. New-resource defaults are materialized at creation. A populated document never acquires defaults on read. Editor responses can resolve legacy selections for an owner without a saved document; public runtime responses keep tracking_config null and use legacy tracking until that owner has a saved document. Purchase eligibility remains controlled by store settings. Asset credentials and delivery history are not part of this document.
    - `purchase` object: Store-owned Purchase selections, present only on store configurations. Update through the store purchase_tracking fields. General tracking edits preserve this block and cannot change it.
      - `google_ads` StoreGooglePurchaseSelection[]
        - `destination_id` string, uuid, required
        - `action_id` string, required
    - `schema_version` 1, required
    - `assets` TrackingAssets, required: Business-owned asset references. Omitted contextual providers inherit the root selection; an empty array explicitly clears that provider.
      - `fb` integer[]
      - `tiktok` integer[]
      - `kwai_client` integer[]
      - `kwai_server` integer[]
      - `google_ads` string[]
      - `gtm` integer[]
    - `context_assets` object
    - `triggers` object[], required
      - `id` string, required
      - `context` string, required: Owner context: page, flow:<step-id>, storefront:<page-type>, paylink, or lms:<position>; optionally suffixed /widget:<widget-id>. Landing pages do not inherit storefront triggers.
      - `trigger` 'page_open' | 'product_view' | 'search' | 'cart_add' | 'checkout_start' | 'form_submit' | 'widget_click' | 'payment_methods_opened' | 'payment_method_selected' | 'banner_click', required: Interaction that invokes selected provider events. This is not a provider event name. Only interactions supported by the current surface are invoked.
      - `events` TrackingEvent[], required
        - `provider` 'fb' | 'tiktok' | 'kwai_client' | 'kwai_server' | 'google_ads' | 'gtm', required
        - `name` string, required: Exact native event or Google conversion-action name. Purchase, CompletePayment and EVENT_PURCHASE are reserved for eligible orders.
        - `initialization` true: Marks a preserved SDK default allowed only on page_open triggers with name PageView, provider fb, tiktok, or kwai_client, and channels exactly [browser]. Keep this metadata when retaining that selection. Explicit merchant-selected PageView events omit it and use the provider event call with their parameters and interaction identity.
        - `legacy_document_only` true: Preserved legacy Google delivery metadata, valid only for Google Ads page_open selections on a page or checkout-flow step. Both browser and server channels run only for an initial rendered document, including hydration. Retain this marker when keeping an existing selection. Newly selected events omit it and run on the configured page-open interaction, including client-side navigation.
        - `legacy_document_server_only` true: Preserved legacy delivery metadata, valid only for a page, checkout-flow step, or storefront page_open selection with a server channel and provider fb, tiktok, or kwai_server. The server channel runs for an initial rendered document (including hydration), not a client-only mount or SPA navigation. Browser delivery is unchanged. Retain this marker when keeping the existing selection; newly selected events omit it and retain their configured server behavior.
        - `channels` string[]: Preserve the provider's supported channels. Kwai client and GTM support browser only; Kwai server supports server only.
        - `parameters` object
        - `parameter_variants` object: Complete effective parameter maps preserving legacy renderer and channel behavior. Each present map overrides parameters for that renderer/channel; an empty map is authoritative. An absent map falls back to parameters. Preserve these maps and separate same-name channel bindings on read/write. An intentional parameter edit changes only that parameter in the selected binding's parameters and every existing variant. The actual serving renderer selects the variant, including compiled Builder HTML and Vue fallback.
          - `vue_browser` object
          - `vue_server` object
          - `html_browser` object
          - `html_server` object
        - `asset_ids` union[]: Optional subset of the provider assets selected for this context.
          - union
            - integer
            - string, uuid
        - `destination_id` string, uuid: Required for Google events; must be assigned in this context.
        - `action_id` string: Required for Google conversion actions. The server verifies action ownership and resolves the tag and label.
        - `kind` 'remarketing': Google browser remarketing uses page_view, view_item, view_search_results or add_to_cart instead of action_id. Feed matching and consent still apply.
        - `tag_id` string
        - `conversion_label` string
  - `tracking_config_revision` string: Required with tracking_config for an existing owner. Use the current editor response revision and tracking_config_write_version; stale edits or unsupported writers are rejected with 409. Asset and trigger changes are atomic.
  - `render_mode` RenderMode (unresolved $ref)
  - `html_document` string, nullable: Complete authored HTML source for HTML Mode. A non-whitespace value is authoritative and replaces all legacy html_code, css_code, js_code and additional_head_code inputs for rendering. Null, empty and whitespace-only values on legacy records use the legacy source. Reading and validation do not persist migration. Existing clients may continue sending html_code, css_code and js_code instead of html_document, including after a previous version used unified source. Send all three fields for a complete legacy snapshot, using empty strings for intentionally blank sections. Include additional_head_code when needed; omitted snapshot sections are empty. Legacy snapshots are automatically assembled into a document on every HTML Mode content save. Settings-only version writes preserve the preceding source. Clearing an already migrated document returns 422; save <!doctype html><html><head></head><body></body></html> for a deliberately blank page. Platform runtime, tokens, analytics and public data are injected only when rendered and must not be included in this field. External scripts, stylesheets, import maps and document attributes are retained. Dependencies still require directive-specific permission in csp_policy. CSP meta tags are retained in source but ignored at execution with a validation warning.
  - `html_code` HtmlCode (unresolved $ref)
  - `css_code` CssCode (unresolved $ref)
  - `js_code` JsCode (unresolved $ref)
  - `additional_head_code` AdditionalHeadCode (unresolved $ref)
  - `csp_policy` HtmlModeCspPolicy: Supported HTML Mode CSP keys. Unsupported keys are rejected.
    - `connect_src` string[]
    - `img_src` string[]
    - `script_src` string[]
    - `style_src` string[]
    - `frame_src` string[]
  - `meta` Meta (unresolved $ref)
  - `form_display` FormDisplay (unresolved $ref)
  - `google_ads_destination_ids` string[]: Business-owned Scalev Google Ads destination IDs. Server purchase timing follows the store Meta CAPI triggers.
  - `fb_pixel_ids` FbPixelIds (unresolved $ref)
  - `tiktok_pixel_ids` TiktokPixelIds (unresolved $ref)
  - `kwai_client_pixel_ids` KwaiClientPixelIds (unresolved $ref)
  - `kwai_server_pixel_ids` KwaiServerPixelIds (unresolved $ref)
  - `onload_fb_events` OnloadFbEvents (unresolved $ref)
  - `onload_tiktok_events` OnloadTiktokEvents (unresolved $ref)
  - `onload_kwai_client_events` OnloadKwaiClientEvents (unresolved $ref)
  - `onload_kwai_server_events` OnloadKwaiServerEvents (unresolved $ref)
  - `fb_events_onload_parameters` FbEventsOnloadParameters (unresolved $ref)
  - `tiktok_events_onload_parameters` TiktokEventsOnloadParameters (unresolved $ref)
  - `kwai_client_events_onload_parameters` KwaiClientEventsOnloadParameters (unresolved $ref)
  - `kwai_server_events_onload_parameters` KwaiServerEventsOnloadParameters (unresolved $ref)

## Response `200`

Landing page display

- LandingPageDisplay
  - `tracking_form_delivery` 'server_v1': Public runtime capability present only with a saved tracking_config, including an explicitly empty configuration. Absent for unmigrated displays and editor-only resolved defaults. A compatible runtime copies this value into checkout metadata, then waits for the accepted order's same-named acknowledgment before suppressing direct native server sends.
  - `tracking_config` TrackingConfig: Authoritative merchant tracking selections, limited to 256 KiB. Empty selections send nothing. Trigger and event enablement flags are not used; remove an event selection to stop sending it. New-resource defaults are materialized at creation. A populated document never acquires defaults on read. Editor responses can resolve legacy selections for an owner without a saved document; public runtime responses keep tracking_config null and use legacy tracking until that owner has a saved document. Purchase eligibility remains controlled by store settings. Asset credentials and delivery history are not part of this document.
    - `purchase` object: Store-owned Purchase selections, present only on store configurations. Update through the store purchase_tracking fields. General tracking edits preserve this block and cannot change it.
      - `google_ads` StoreGooglePurchaseSelection[]
        - `destination_id` string, uuid, required
        - `action_id` string, required
    - `schema_version` 1, required
    - `assets` TrackingAssets, required: Business-owned asset references. Omitted contextual providers inherit the root selection; an empty array explicitly clears that provider.
      - `fb` integer[]
      - `tiktok` integer[]
      - `kwai_client` integer[]
      - `kwai_server` integer[]
      - `google_ads` string[]
      - `gtm` integer[]
    - `context_assets` object
    - `triggers` object[], required
      - `id` string, required
      - `context` string, required: Owner context: page, flow:<step-id>, storefront:<page-type>, paylink, or lms:<position>; optionally suffixed /widget:<widget-id>. Landing pages do not inherit storefront triggers.
      - `trigger` 'page_open' | 'product_view' | 'search' | 'cart_add' | 'checkout_start' | 'form_submit' | 'widget_click' | 'payment_methods_opened' | 'payment_method_selected' | 'banner_click', required: Interaction that invokes selected provider events. This is not a provider event name. Only interactions supported by the current surface are invoked.
      - `events` TrackingEvent[], required
        - `provider` 'fb' | 'tiktok' | 'kwai_client' | 'kwai_server' | 'google_ads' | 'gtm', required
        - `name` string, required: Exact native event or Google conversion-action name. Purchase, CompletePayment and EVENT_PURCHASE are reserved for eligible orders.
        - `initialization` true: Marks a preserved SDK default allowed only on page_open triggers with name PageView, provider fb, tiktok, or kwai_client, and channels exactly [browser]. Keep this metadata when retaining that selection. Explicit merchant-selected PageView events omit it and use the provider event call with their parameters and interaction identity.
        - `legacy_document_only` true: Preserved legacy Google delivery metadata, valid only for Google Ads page_open selections on a page or checkout-flow step. Both browser and server channels run only for an initial rendered document, including hydration. Retain this marker when keeping an existing selection. Newly selected events omit it and run on the configured page-open interaction, including client-side navigation.
        - `legacy_document_server_only` true: Preserved legacy delivery metadata, valid only for a page, checkout-flow step, or storefront page_open selection with a server channel and provider fb, tiktok, or kwai_server. The server channel runs for an initial rendered document (including hydration), not a client-only mount or SPA navigation. Browser delivery is unchanged. Retain this marker when keeping the existing selection; newly selected events omit it and retain their configured server behavior.
        - `channels` string[]: Preserve the provider's supported channels. Kwai client and GTM support browser only; Kwai server supports server only.
        - `parameters` object
        - `parameter_variants` object: Complete effective parameter maps preserving legacy renderer and channel behavior. Each present map overrides parameters for that renderer/channel; an empty map is authoritative. An absent map falls back to parameters. Preserve these maps and separate same-name channel bindings on read/write. An intentional parameter edit changes only that parameter in the selected binding's parameters and every existing variant. The actual serving renderer selects the variant, including compiled Builder HTML and Vue fallback.
          - `vue_browser` object
          - `vue_server` object
          - `html_browser` object
          - `html_server` object
        - `asset_ids` union[]: Optional subset of the provider assets selected for this context.
          - union
            - integer
            - string, uuid
        - `destination_id` string, uuid: Required for Google events; must be assigned in this context.
        - `action_id` string: Required for Google conversion actions. The server verifies action ownership and resolves the tag and label.
        - `kind` 'remarketing': Google browser remarketing uses page_view, view_item, view_search_results or add_to_cart instead of action_id. Feed matching and consent still apply.
        - `tag_id` string
        - `conversion_label` string
  - `tracking_config_revision` string, nullable: Authoring revision from the editor response. Send it with tracking_config when creating the next display version; stale edits are rejected with 409. Asset and trigger changes are atomic. Public runtime responses may return null; do not use those responses as an editing revision.
  - `tracking_config_error` string, nullable: An actionable compatibility-resolution problem. An unresolved owner remains unmigrated.
  - `tracking_context` string
  - `id` integer
  - `version` integer
  - `schema_version` integer
  - `created_at` string, date-time
  - `created_by_id` integer, nullable
  - `is_published` boolean
  - `published_at` string, date-time, nullable
  - `render_mode` 'html_mode' | 'builder'
  - `html_document` string, nullable: Complete authored HTML source for HTML Mode. A non-whitespace value is authoritative and replaces all legacy html_code, css_code, js_code and additional_head_code inputs for rendering. Null, empty and whitespace-only values on legacy records use the legacy source. Reading and validation do not persist migration. Existing clients may continue sending html_code, css_code and js_code instead of html_document, including after a previous version used unified source. Send all three fields for a complete legacy snapshot, using empty strings for intentionally blank sections. Include additional_head_code when needed; omitted snapshot sections are empty. Legacy snapshots are automatically assembled into a document on every HTML Mode content save. Settings-only version writes preserve the preceding source. Clearing an already migrated document returns 422; save <!doctype html><html><head></head><body></body></html> for a deliberately blank page. Platform runtime, tokens, analytics and public data are injected only when rendered and must not be included in this field. External scripts, stylesheets, import maps and document attributes are retained. Dependencies still require directive-specific permission in csp_policy. CSP meta tags are retained in source but ignored at execution with a validation warning.
  - `html_code` string, nullable
  - `css_code` string, nullable
  - `js_code` string, nullable
  - `additional_head_code` string, nullable
  - `csp_policy` HtmlModeCspPolicy: Supported HTML Mode CSP keys. Unsupported keys are rejected.
    - `connect_src` string[]
    - `img_src` string[]
    - `script_src` string[]
    - `style_src` string[]
    - `frame_src` string[]
  - `form_display` LandingPageFormDisplay
    - `is_sending_email_invoice` boolean: Whether invoice emails are enabled for non-E-Payment orders from this checkout form. Applies to Builder and HTML checkout. E-Payment invoices remain enabled regardless of this preference. Store email notification settings and allowed statuses still apply. Does not control offer invitations or purchased-product access emails.
    - `order_bumps` CheckoutOrderBump[], nullable: Builder checkout offers with independent selection and placement. Null in a response denotes a legacy single-bump form; an explicit empty array removes all offers. On writes, omit to inherit the previous collection. Legacy bump edits against multiple offers return 409. HTML Mode does not support this field.
      - `key` string, required: Stable offer identity retained across versions and reorder operations.
      - `enabled` boolean, required
      - `available` boolean: False when the referenced item or its underlying catalog products are inactive or draft.
      - `type` 'variant' | 'bundle', required
      - `variant_id` integer, nullable: Required for an enabled variant offer; must belong to the form's store.
      - `bundle_price_option_id` integer, nullable: Required for an enabled bundle offer; must belong to the form's store.
      - `title` string
      - `description` string
      - `images` string[]
      - `auto_check` boolean
      - `shown` boolean
      - `toggle_position` 'top' | 'bottom'
      - `image_autoslide` boolean
      - `image_duration` integer
      - `variant` object, nullable: Existing public variant representation, including current pricing and availability.
      - `bundle_price_option` object, nullable: Existing public bundle option representation and its bundle lines.
    - `form_position` string[]: Ordered form field keys. Each configured offer must appear exactly once as order_bump:<key>, independently of the other offers.
    - `id` integer
    - `store` object, nullable
    - `variants` object[]
    - `bundle_price_options` object[]
    - `after_submit_event` string
    - `handler_assignment` string
    - `store_sales_person` object, nullable
    - `custom_phone` string
    - `other_page` object, nullable
    - `custom_url` string
    - `onsubmit_fb_events` string[]
    - `onsubmit_tiktok_events` string[]
    - `onsubmit_kwai_client_events` string[]
    - `onsubmit_kwai_server_events` string[]
  - `fb_pixels` object[]
  - `tiktok_pixels` object[]
  - `kwai_client_pixels` object[]
  - `kwai_server_pixels` object[]

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `422`: Validation failed

## Changes

- **2026-11-03** `6b9152f04622`: 11 info
  - added the new optional request property `google_ads_destination_ids`
  - added the new optional request property `tracking_config`
  - added the new optional request property `tracking_config_revision`
  - added the new optional request property `tracking_config_write_version`
  - …7 more
- **2026-10-26** `5c1373139b01`: 2 info
  - added the new optional request property `form_display/allOf[#/components/schemas/LandingPageFormDisplayRequest]/is_sending_email_invoice`
  - added the optional property `form_display/allOf[#/components/schemas/LandingPageFormDisplay]/is_sending_email_invoice` to the response with the `200` status
- **2026-10-02** `a14339bcc086`: 4 info
  - added the new optional request property `form_display/allOf[#/components/schemas/LandingPageFormDisplayRequest]/form_position`
  - added the new optional request property `form_display/allOf[#/components/schemas/LandingPageFormDisplayRequest]/order_bumps`
  - added the optional property `form_display/allOf[#/components/schemas/LandingPageFormDisplay]/form_position` to the response with the `200` status
  - added the optional property `form_display/allOf[#/components/schemas/LandingPageFormDisplay]/order_bumps` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/scalev/apis/nexus-commerce-api/changes/v3/pages/:page_id/page-displays/post.md)

---

[API](https://skmtc.dev/scalev/apis/nexus-commerce-api.md) - [All operations](https://skmtc.dev/scalev/apis/nexus-commerce-api/llms.txt) - [OpenAPI document](https://skmtc.dev/scalev/apis/nexus-commerce-api/revisions/6b9152f04622?raw)