create_form
Create a new form page for lead capture or submissions.
Use this tool when a merchant wants to publish a form that collects customer information, optionally shows custom confirmation copy, and can deliver downloadable files after submission.
Prefer a minimal request when the user is vague, and only add optional fields like custom copy, redirects, images, files, or tracking when requested.
For the page's design and customer-facing labels (including translations), set themeOverrides and hostedLayoutType; list_theme_properties lists what can be set. Set themeId (from list_themes) to use a theme.
After creation, return:
data.id: the form page IDdata.name: the internal page namedata.hostedUrl: the live form URLdata.dashboardUrl: the dashboard edit URL
If the user is building or editing a website, call add_to_website next with pageId set to data.id and pageType: "form", and put the returned code in the site. Do not wait for the user to ask for this step.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Internal page name used in your dashboard and API responses. | |
| slug | No | Page URL slug. For events and forms the slug defaults to the slugified version of your `title`. For checkouts the slug defaults to the slugified version of your `productData.title`. | |
| title | No | Public title shown to customers on the page. | |
| fields | No | Custom checkout fields to create. When provided, at least one field must be an `email` element with `type` `email` and `required` `true`. When omitted, the page gets Name and Email address fields, plus a required billing Address on checkout and event pages. Forms get Name and Email address only. | |
| locale | No | ||
| fileIds | No | Array of file IDs for downloadable files. All file IDs must exist and belong to your account. | |
| themeId | No | The theme the page uses: one of your themes or a built-in one (see List themes). `themeOverrides` apply on top. Leave it out to use your store's default theme. | |
| imageIds | No | Array of images for the page gallery. All referenced file IDs must exist and belong to your account. | |
| redirect | No | If enabled, redirects the customer to the specified URL before the page loads. | |
| testmode | No | Puts the page in test mode. While it is on, every purchase on this page is a test purchase: no money is taken, the buyer still receives everything the page delivers, and the records are created with `livemode: false`. Turn it off to take real payments again. | |
| formLayout | No | How to arrange the page's form, top to bottom. Reference a field by `fieldKey`: the `key` you gave it in `fields` in this request. Each item is one of: `field` (`fieldKey`), `heading` (`id`, `text`, `level` `heading` or `subheading`), `divider` (`id`), `discount-code` (no other properties) and `group` (`id`, optional `name`, `columns` 1 to 4, and `items` holding fields, headings, dividers or the discount code; groups never nest). You choose the `id` of each heading, divider and group: 1 to 64 characters, unique in the layout. Fields the layout leaves out are added after it, in their current order. `formLayout` on the page decides the form's order. Each field's `order` is its position among the page's fields and follows the layout: saving a layout (in the dashboard or through the API) rewrites every field's `order`. On a page that has never saved a layout, setting `order` moves the field; once a layout is saved, move fields with `formLayout` instead. A `discount-code` item only places the discount code box: the box shows while `showCouponCodeField` is on, and the item does not switch it on. Forms have no discount code, so a form layout must leave it out. More item types may be added later. When reading a layout, skip any item type you do not recognise. When updating, send every item back as you received it, including those. | |
| description | No | Page description shown to customers. Accepts HTML or plain text. | |
| formDetails | No | Form behaviour settings. | |
| funnelSteps | No | Ordered funnel configuration for this page. Supports intermediate checkout steps, one-click upsells, and confirmation behavior. | |
| googleIndex | No | Allow Google to index this page for search results. Defaults to `true`. | |
| notifyEmail | No | Email addresses to send notifications to. Supports comma separated emails. | |
| redirectUrl | No | URL to redirect to after payment. Applies if `afterPaymentAction` is `redirect`. | |
| trackingCodes | No | Custom tracking scripts to include on the page. Supports HTML `<script>` tags. | |
| redirectPageId | No | ID of the page (checkout, event or form) to redirect to after payment. Applies when `afterPaymentAction` is `checkout`. | |
| themeOverrides | No | The page's design and labels, set on top of its theme and nested by theme property path: `tokens.colorPrimary` is sent as `{ "tokens": { "colorPrimary": { "light": "#1A73E8" } } }`. Keys you leave out keep their current value, and `null` resets a property, or everything under a key, to the theme default. Call `list_theme_properties` for the supported properties, their value formats and, where a property has a fixed one, its default. | |
| invoiceSettings | No | ||
| redirectUrlPath | No | Additional path parameters appended to the `redirectUrl`. Applies if `afterPaymentAction` is `redirect` and `redirectUrl` is set. [Learn more](https://checkoutpage.com/docs/articles/add-field-and-variant-data-to-redirect-url) | |
| hostedLayoutType | No | ||
| redirectUrlQuery | No | Query parameters for the `redirectUrl`. Applies if `afterPaymentAction` is `redirect` and `redirectUrl` is set. [Learn more](https://checkoutpage.com/docs/articles/add-field-and-variant-data-to-redirect-url) | |
| allowDynamicTitle | No | Allow page title to be overridden via URL query parameters. | |
| afterPaymentAction | No | Behavior after checkout. `confirmation` shows the confirmation page. `checkout` redirects to `redirectPageId`. `redirect` sends the customer to `redirectUrl`. Defaults to `confirmation`. | |
| sendEmailConfirmation | No | Send an email confirmation to the customer. Defaults to `true`. | |
| redirectUrlInsideEmbed | No | If the page is embedded, redirect the customer within the embed instead of redirecting the main browser window. Defaults to `false`. | |
| allowDynamicDescription | No | Allow page description to be overridden via URL query parameters. | |
| sendPaymentNotification | No | Send payment/submission notification emails to the store owner. | |
| closePopupOnClickOutside | No | Whether a popup embed closes when clicking outside the container. Defaults to `false`. | |
| confirmationEmailMessage | No | Custom confirmation email message. Accepts HTML or plain text. Write `{{id}}` where a customer's own details go, and it is filled in for each customer: `{{field_<field id>}}` for their answer to one of the page's fields, `{{variant_<variant id>}}` and `{{variant_<variant id>_sku}}` for their variant choice, or one of `price` (Amount), `amountDue` (Payment amount due), `amountPaid` (Payment amount paid), `currentPeriodEnd` (Next payment date), `planIterations` (No. of payments), `createdAt` (Created date), `status` (Status), `payment_method` (Payment method), `orderId` (Order ID), `product_title` (Product title), `order_summary` (Order summary), `variant_breakdown` (Variant selection), `license_key` (License key), `sku` (SKU), `form_title` (Form title), `event_name` (Event name), `event_date` (Event date/time), `event_location` (Event location), `event_tickets` (Tickets purchased), `booking_fee` (Booking fee), `event_meeting_link` (Virtual meeting link), `customer_portal_link` (Customer portal link), `coupon_code` (Coupon code), `coupon_discount` (Coupon discount). Product, variant, license key and billing variables apply to checkout pages, event variables to events, `form_title` to forms; a variable that does not apply is left blank. To show paragraphs only to some customers, wrap them in `<if variable="<id>" operator="<operator>" value="<value>">...</if>`, with operator one of equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, greater_than_or_equal, less_than_or_equal. | |
| confirmationEmailSubject | No | Custom confirmation email subject. | |
| confirmationCheckoutTitle | No | Confirmation title. | |
| confirmationEmailShowLogo | No | Show store logo in confirmation email. | |
| customizeEmailConfirmation | No | Use a custom email confirmation template. If enabled, provide `confirmationEmailSubject` and `confirmationEmailMessage`. | |
| confirmationCheckoutMessage | No | Confirmation message. Accepts HTML or plain text. Write `{{id}}` where a customer's own details go, and it is filled in for each customer: `{{field_<field id>}}` for their answer to one of the page's fields, `{{variant_<variant id>}}` and `{{variant_<variant id>_sku}}` for their variant choice, or one of `price` (Amount), `amountDue` (Payment amount due), `amountPaid` (Payment amount paid), `currentPeriodEnd` (Next payment date), `planIterations` (No. of payments), `createdAt` (Created date), `status` (Status), `payment_method` (Payment method), `orderId` (Order ID), `product_title` (Product title), `order_summary` (Order summary), `variant_breakdown` (Variant selection), `license_key` (License key), `sku` (SKU), `form_title` (Form title), `event_name` (Event name), `event_date` (Event date/time), `event_location` (Event location), `event_tickets` (Tickets purchased), `booking_fee` (Booking fee), `event_meeting_link` (Virtual meeting link), `customer_portal_link` (Customer portal link), `coupon_code` (Coupon code), `coupon_discount` (Coupon discount). Product, variant, license key and billing variables apply to checkout pages, event variables to events, `form_title` to forms; a variable that does not apply is left blank. To show paragraphs only to some customers, wrap them in `<if variable="<id>" operator="<operator>" value="<value>">...</if>`, with operator one of equals, not_equals, contains, not_contains, starts_with, ends_with, greater_than, less_than, greater_than_or_equal, less_than_or_equal. | |
| customizeCheckoutConfirmation | No | If set to true `confirmationCheckoutMessage` and `confirmationCheckoutTitle` will be displayed on the confirmation page. Defaults to `false`. | |
| confirmationEmailShowStoreName | No | Show store name in confirmation email. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |