---
title: "Create a landing page"
method: POST
path: "/v3/pages"
tags: ["Landing Pages"]
---

# Create a landing page

`POST /v3/pages`

Creates a business-scoped landing page using the same page creation behavior as Landing Page Studio. The request body below documents the HTML Mode payload. To create and publish an HTML Mode page in one call, include `is_published: true` with `page_display`. If `is_published` is omitted or false, the nested `page_display` is saved as an unpublished draft and is not returned as the page's current display; create or pick a page display, then call `PATCH /v3/pages/{id}` with `is_published: true` and `current_page_display_id` to publish it.

## Request body

- LandingPageCreateRequest
  - `name` string, required
  - `slug` string, required
  - `is_published` boolean — When true, publishes the created nested `page_display` and makes it the current display. When omitted or false, the nested display is saved as an unpublished draft; the page response will have `current_page_display_id: null`, `page_display: null`, and a page-level `render_mode` fallback until a display is published.
  - `store_id` integer, nullable — Optional top-level store association. HTML Checkout store context is configured through `page_display.form_display.store_id`.
  - `page_display` LandingPageDisplayRequest, required
    - `render_mode` 'html_mode' | 'builder', required — HTML Mode requests use `html_mode`. Builder payload details are intentionally not documented here and remain unsupported for public integration guidance; use HTML Mode for API-created pages.
    - `html_code` string — Body-only HTML for HTML Mode.
    - `css_code` string
    - `js_code` string
    - `additional_head_code` string — Additional HTML Mode document head code. Supports title, meta, link, style, script, and noscript tags. User-authored entries override managed SEO, crawler, and favicon convenience tags with the same identity, but do not override Scalev runtime tags or the document language.
    - `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` object, required
    - `form_display` LandingPageFormDisplayRequest
      - `store_id` integer — Required for HTML Checkout pages. After a page has a saved `store_id`, new displays for that page must use the same `form_display.store_id`; a different store or missing store context is rejected.
      - `variant_ids` integer[] — Selected product variants. HTML Checkout requires at least one `variant_id` or `bundle_price_option_id`.
      - `bundle_price_option_ids` integer[] — Selected bundle price options. HTML Checkout requires at least one `variant_id` or `bundle_price_option_id`.
      - `after_submit_event` 'success_page' | 'direct_to_whatsapp' | 'direct_to_custom_whatsapp' | 'other_page' | 'custom_url' | 'is_sending_email_invoice' | 'order_page'
      - `handler_assignment` 'rotator' | 'fixed' — Required for `direct_to_whatsapp`. When fixed, send `store_sales_person_id`.
      - `store_sales_person_id` integer, nullable
      - `custom_phone` string — Required for `direct_to_custom_whatsapp`.
      - `other_page_id` integer, nullable — Required for `other_page`.
      - `custom_url` string — Required for `custom_url`.
      - `onsubmit_fb_events` string[] — Meta/Facebook events fired after HTML Checkout order creation succeeds.
      - `onsubmit_tiktok_events` string[] — TikTok events fired after HTML Checkout order creation succeeds.
      - `onsubmit_kwai_client_events` string[] — SnackVideo browser events fired after HTML Checkout order creation succeeds.
      - `onsubmit_kwai_server_events` string[] — SnackVideo server events fired after HTML Checkout order creation succeeds.
      - `fb_events_onsubmit_parameters` object
      - `tiktok_events_onsubmit_parameters` object
      - `kwai_client_events_onsubmit_parameters` object
      - `kwai_server_events_onsubmit_parameters` object
    - `fb_pixel_ids` integer[] — Scalev record IDs for Meta/Facebook pixels to attach to this page display. These are the numeric Scalev pixel records, not the provider pixel code. Send an empty array for no Meta/Facebook pixels.
    - `tiktok_pixel_ids` integer[] — Scalev record IDs for TikTok pixels to attach to this page display. These are the numeric Scalev pixel records, not the provider pixel code. Send an empty array for no TikTok pixels.
    - `kwai_client_pixel_ids` integer[] — Scalev record IDs for SnackVideo browser pixels to attach to this page display. Send an empty array for no SnackVideo browser pixels.
    - `kwai_server_pixel_ids` integer[] — Scalev record IDs for SnackVideo Events API pixels to attach to this page display. Send an empty array for no SnackVideo server pixels.
    - `onload_fb_events` string[], required — Meta/Facebook events fired automatically when the page loads.
    - `onload_tiktok_events` string[], required — TikTok events fired automatically when the page loads.
    - `onload_kwai_client_events` string[], required — SnackVideo browser events fired automatically when the page loads.
    - `onload_kwai_server_events` string[], required — SnackVideo server events fired automatically when the page loads.
    - `fb_events_onload_parameters` object, required
    - `tiktok_events_onload_parameters` object, required
    - `kwai_client_events_onload_parameters` object, required
    - `kwai_server_events_onload_parameters` object, required

## Response `200`

Landing page

- LandingPage
  - `id` integer
  - `unique_id` string
  - `name` string
  - `slug` string
  - `render_mode` 'builder' | 'html_mode'
  - `is_published` boolean
  - `published_at` string, date-time, nullable
  - `store_id` integer, nullable
  - `store` object, nullable
  - `tags` string[]
  - `is_pinned` boolean
  - `created_by` object, nullable
  - `last_updated_by` object, nullable
  - `created_at` string, date-time
  - `last_updated_at` string, date-time
  - `uuid` string
  - `business` object, nullable
  - `is_sending_email_invoice` boolean
  - `is_disable_custom_font` boolean
  - `is_disable_client_tagging` boolean
  - `client_analytics_config` 'head' | 'body_close_delay' | 'web_worker', nullable
  - `custom_domains` object[]
  - `homepage_custom_domains` object[]
  - `current_page_display_id` integer, nullable
  - `page_display` LandingPageDisplay
    - `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_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
      - `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
- `422` — Validation failed

---

[API](https://skmtc.net/scalev/apis/nexus-commerce-api.md) · [All operations](https://skmtc.net/scalev/apis/nexus-commerce-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/scalev/nexus-commerce-api/versions/4354959d76dc/schema)