Choose a surface
A checkout page exposes only the locations and products configured on that page. If the page is deactivated or deleted, its direct links and embeds stop working.
A storefront reads the organization’s public catalog. Only storefront-visible locations and published products appear.
Get the base URL
In Nautilus, open Checkout Pages. For a checkout page:- Open the checkout page you want to integrate.
- Click Copy link to copy its hosted URL.
- Click Embed code, select Inline embed, and click Copy code.
- Click View live page to test the customer experience.
- Click Preview to open the organization’s storefront.
- Or open Edit Storefront, select a location, and click Live Checkout.
Preselect a location and product
Nautilus reads these case-sensitive query parameters:Select a location
Checkout page:Select a location and product
Checkout page:locationId when you include productId. Products are location-specific. The product must belong to the selected location and be available on the chosen surface.
Do not substitute a POS item ID, Stripe price ID, product name, location name, or organization slug for a Nautilus site or product ID.
Get the correct IDs
The safest method is to copy them from a working customer flow:- Open the live checkout page or storefront from Nautilus.
- Select the intended location.
- Select the intended product.
- Copy the resulting browser URL. Nautilus adds
locationIdandproductIdas the selection changes. - Open the copied URL in a clean browser session.
- Confirm the visible location, product name, price, and purchase terms.
Add a link or button
Use the preselected URL as a normal link:href to the storefront URL:
Embed a checkout page
The Nautilus loader creates the iframe, enables payment and geolocation permissions, addsembedded=true, and automatically resizes the iframe as its content changes.
<div> where the checkout should appear. Define window.NautilusEmbedConfig before you load loader.js. Load loader.js only once per page.
data-height sets the initial minimum height while automatic resizing starts.
Embed a storefront
Use the same loader withdata-nautilus-embed="storefront":
transparent=true to data-src:
Open checkout in a drawer
Use a drawer when you want customers to start checkout without leaving the current page. The host website owns the trigger, backdrop, drawer shell, responsive layout, and accessibility behavior. Nautilus supplies the checkout page or storefront that runs inside the iframe.loader.js does not provide a drawer API.
On desktop, open the shell as a drawer from the right. On mobile, present the same shell as a bottom sheet. Build the iframe URL from the checkout page or storefront URL. Add locationId, optional productId, and embedded=true. Set allow="geolocation; payment" on the iframe.
The following example uses one script block for every trigger on the page. Each trigger can use a different checkout page or storefront URL, location, product, and accessible title. Keep the direct URL in each trigger’s href. It remains available when JavaScript is disabled. The open drawer also includes a direct link in case a browser extension or Content Security Policy blocks the iframe.
href and the matching data attributes. data-nautilus-url accepts either a checkout page or storefront base URL. data-nautilus-location-id is required. data-nautilus-product-id is optional. Use data-nautilus-title for a concise title that identifies the experience to screen-reader users.
The script creates text nodes and assigns textContent for the per-trigger title. Do not insert titles or other data-attribute values with innerHTML.
Implement the drawer in React
In React, keep the selected URL and open state in the host application. Store the trigger in a ref so you can restore focus after closing. Build the direct and iframe URLs in a pure helper withnew URL() and URLSearchParams. Render the shell in a portal, lock both root and body scrolling in an effect, and set title and allow="geolocation; payment" on the iframe.
You can implement the focus trap and responsive shell with the native <dialog> element. Libraries such as Vaul or Radix Dialog can instead supply focus, dismissal, and touch-gesture primitives. Neither library is required. The host application still owns the shell and passes the constructed Nautilus URL to the iframe.
Style the drawer and checkout
The parent page can style the trigger, backdrop, loading state, and drawer shell. The Nautilus page is cross-origin, so parent-page CSS cannot style anything inside the iframe. Configure checkout colors, logos, and other branding in Nautilus.Handle a completed purchase
SetonSuccess before loading the Nautilus script. It can redirect the host page:
Use the loader on a dynamic site
If your application adds an embed container afterloader.js has loaded, initialize new containers after rendering:
Use a plain iframe
Use the Nautilus loader whenever possible. If a CMS blocks custom JavaScript, use a fixed-height iframe:src with the storefront URL when embedding a storefront.
The payment permission is required for browser wallets such as Apple Pay or Google Pay when the browser and payment configuration support them.
Configure Content Security Policy
If your website uses a restrictive Content Security Policy, allow Nautilus as a frame source. The framework-agnostic drawer does not loadloader.js or jsDelivr:
unsafe-inline only for this integration.
For a loader-based inline embed, also allow the Nautilus script and the iframe-resizer dependency. Merge these origins into your existing policy:
NautilusEmbedConfig block.
The loader fetches @iframe-resizer/parent from jsDelivr. Contact Nautilus if you must self-host that dependency.
Preserve campaign attribution
The loader preserves parameters already present indata-src. It also forwards non-empty query parameters from the host page, supporting attribution parameters such as UTMs and click IDs.
Do not place customer personal information, credentials, access tokens, or other secrets in the host page URL.
Verify the integration
Test every location and product combination your website exposes:- Click the website’s source link or button.
- Confirm the destination URL contains the expected
locationIdandproductId. - Reload that exact URL in a clean browser session.
- Confirm the visible location, product name, price, recurrence or trial terms, and organization branding.
- For a drawer, confirm it opens from the right on desktop and from the bottom on mobile.
- Inspect the iframe and confirm it includes
allow="geolocation; payment". Test browser-wallet availability on an eligible browser and device. - Navigate by keyboard. Confirm focus enters and stays within the open dialog, the close button has an accessible name, and focus returns to the original trigger after closing.
- Close the drawer with Escape, the close button, and a backdrop click.
- Confirm the page behind the drawer does not scroll while open. Confirm its original scroll position and scroll behavior return after every dismissal method.
- Disable JavaScript and confirm each trigger opens its
href. Block the Nautilus frame in a test policy and confirm the drawer’s direct link still works. - For a loader-based inline embed, test desktop and mobile widths, automatic height changes, scrolling, and browser-wallet availability.
Troubleshoot the integration
The wrong product is selected
- Confirm the parameter names are exactly
locationIdandproductId. - Confirm both values came from the same working location and product selection.
- Confirm the product belongs to the selected location and remains available on the checkout page or storefront.
- Test from a clean URL instead of relying on browser history.
The embed is blank
- Open the direct checkout page or storefront URL and confirm it works.
- For a checkout page, confirm the page is active.
- Confirm the host site allows custom scripts and iframes.
- Check the browser console for blocked requests to
www.nautilus-app.comorcdn.jsdelivr.net. - Confirm
loader.jsloads afterwindow.NautilusEmbedConfigis defined.
The embed does not resize
- Confirm the host can load
https://cdn.jsdelivr.net/npm/@iframe-resizer/parent@5. - Confirm the iframe URL includes
embedded=true. The loader adds it automatically. - Keep a reasonable
data-heightso the checkout remains usable if the resize script is blocked.
Apple Pay or Google Pay is missing
- Use the Nautilus loader, which grants the iframe payment permission.
- For a manual iframe, include
allow="geolocation; payment". - Wallet display still depends on browser, device, domain, and payment-provider eligibility.

