create_checkout_page
Create a new checkout page with an attached product and pricing.
Use this tool whenever a merchant wants to start accepting payments. The page is always created published and is immediately available at its hosted URL.
When the request is vague, create a minimal checkout page. Do not overcomplicate the setup with extra fields, redirects, discounts, variants, images, tracking, or copy unless the user asked for them or they are clearly required.
Prefer plain text for titles, descriptions, confirmation copy, and email copy. Only use HTML when it is genuinely needed to accomplish the task, such as when the user explicitly asks for formatting that plain text cannot express.
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.
Fields:
Omit
fieldsto get the defaults: Name, Email address, and a required billing Address.If you pass
fields, include at least oneemailelement withtype: "email"andrequired: true, or the request fails.When tax is off and nothing is shipped, pass
fieldswith just a name and a required email field so customers are not asked for an address.To collect an address, prefer a single
element: "address"field withcollect: "billing"(or"billing_and_shipping"when you also need a shipping address). It renders a grouped address with country selector. The flat-field types (address-line1,shipping-address-line1, etc.) still work for niche cases but should not be the default.
Tax settings:
Tax is enabled by default with
mode: "stripe". Omittaxentirely unless the merchant explicitly asks to change tax behaviour.Three modes are available via
tax.mode:"stripe"- Stripe Tax calculates tax automatically based on the customer's address. Requires an address field on the page (useelement: "address") and Stripe Tax configured in the merchant's account."fixed"- A fixed tax rate is applied. Calllist_tax_ratesfirst to find an existing rate. Pass itsidasproductData.fixedTaxRateIds, or omit it to use the account's default rate. If no suitable rate exists, usecreate_tax_rateto create one first."none"- No tax is collected. Settax.enabled: falseandtax.mode: "none"(or justtax.enabled: false).
If the merchant sells B2B, add a Tax ID field such as a VAT number.
Payment options:
Only these enabled combinations are supported:
full,invoice,partial,cash_on_delivery,full + invoice,full + partial, orfull + cash_on_delivery.
Example uses:
"Create a checkout page for my $49 online course" - set name, productData.title, price.amount: 4900, price.currency: "usd"
"Create a monthly subscription at $29/month" - set price.amount: 2900, price.currency: "usd", price.recurring: { interval: "month", intervalCount: 1 }
"Create a 3-payment plan of $100 each" - set price.amount: 10000, price.currency: "usd", price.paymentPlan: { interval: "month", intervalCount: 1, planIterations: 3 }
"Create a pay-what-you-want page with a $5 minimum" - set price.amount: 500, price.payWhatYouWant: true
"Create a checkout page with a one-time price and a monthly subscription option" - set productData.prices: [{ billingType: "one_time", amount: 4900, currency: "usd", label: "One-time" }, { billingType: "recurring", amount: 1000, currency: "usd", label: "Monthly", recurring: { interval: "month", intervalCount: 1 } }]
"Create a checkout page with annual and monthly plans" - set productData.prices: [{ billingType: "recurring", amount: 9900, currency: "usd", label: "Annual", recurring: { interval: "year", intervalCount: 1 } }, { billingType: "recurring", amount: 1000, currency: "usd", label: "Monthly", recurring: { interval: "month", intervalCount: 1 } }]
After creation, return:
data.id: the checkout page IDdata.name: the internal page namedata.hostedUrl: the live checkout page 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: "checkout", 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 |
|---|---|---|---|
| tax | No | Tax configuration for this page. Defaults to Stripe Tax when omitted. | |
| fees | No | ||
| 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`. | |
| 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 | ||
| 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. | |
| 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. | |
| productData | No | ||
| 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. | |
| paymentMethods | No | ||
| paymentOptions | No | ||
| 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) | |
| allowDynamicLabel | No | ||
| allowDynamicPrice | No | ||
| allowDynamicTitle | No | Allow page title to be overridden via URL query parameters. | |
| savePaymentMethod | No | ||
| afterPaymentAction | No | Behavior after checkout. `confirmation` shows the confirmation page. `checkout` redirects to `redirectPageId`. `redirect` sends the customer to `redirectUrl`. Defaults to `confirmation`. | |
| limitSubscriptions | No | Deprecated — superseded by `productData.limitSubscriptions.enabled`. Accepted and applied to the page's product. | |
| checkoutAbandonment | No | ||
| showCouponCodeField | No | ||
| 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. | |
| allowDynamicRedirectUrl | No | ||
| sendPaymentNotification | No | Send payment/submission notification emails to the store owner. | |
| showCouponCodeFieldType | No | ||
| 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. | |
| confirmationEmailSubject | No | Custom confirmation email subject. | |
| limitSubscriptionsStripe | No | Deprecated — superseded by `productData.limitSubscriptions.limitSubscriptionsStripe.enabled`. Accepted and applied to the page's product. | |
| confirmationCheckoutTitle | No | Confirmation title. | |
| confirmationEmailShowLogo | No | Show store logo in confirmation email. | |
| allowDynamicPlanIterations | No | Allow subscription plan iterations to be overridden via URL query parameters. | |
| customizeEmailConfirmation | No | Use a custom email confirmation template. If enabled, provide `confirmationEmailSubject` and `confirmationEmailMessage`. | |
| confirmationCheckoutMessage | No | Confirmation message. Accepts HTML or plaintext. | |
| allowDynamicPreselectedPrice | No | ||
| 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. | |
| allowDynamicDiscountedFromPrice | No | ||
| sendCanceledSubscriptionNotifications | No | Send notifications when subscriptions are canceled. | |
| sendRecurringPaymentFailedNotifications | No | Send notifications when recurring payments fail. | |
| enableFileAccessForInactiveSubscriptions | No | Deprecated — superseded by `productData.enableFileAccessForInactiveSubscriptions`. Accepted and applied to the page's product. | |
| sendRecurringPaymentSucceededNotifications | No | Send notifications when recurring payments succeed. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| data | Yes |