Skip to main content
Use a Nautilus checkout page or storefront as a hosted link, button destination, or auto-resizing inline embed. Both surfaces support preselecting a location and product.

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:
  1. Open the checkout page you want to integrate.
  2. Click Copy link to copy its hosted URL.
  3. Click Embed code, select Inline embed, and click Copy code.
  4. Click View live page to test the customer experience.
For the full storefront:
  1. Click Preview to open the organization’s storefront.
  2. Or open Edit Storefront, select a location, and click Live Checkout.
Use the exact URL Nautilus generates. The examples below use placeholders that you must replace.

Preselect a location and product

Nautilus reads these case-sensitive query parameters:

Select a location

Checkout page:
Storefront:
The customer lands on the selected location and chooses from that location’s available products.

Select a location and product

Checkout page:
Storefront:
Always include 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:
  1. Open the live checkout page or storefront from Nautilus.
  2. Select the intended location.
  3. Select the intended product.
  4. Copy the resulting browser URL. Nautilus adds locationId and productId as the selection changes.
  5. Open the copied URL in a clean browser session.
  6. Confirm the visible location, product name, price, and purchase terms.
You can also retrieve sites, products, and checkout links through the Nautilus API.
Invalid, hidden, or mismatched IDs can return a valid page that falls back to the location or product selection screen. An HTTP 200 response does not prove that preselection worked.
Use the preselected URL as a normal link:
For a storefront, change the href to the storefront URL:

Embed a checkout page

The Nautilus loader creates the iframe, enables payment and geolocation permissions, adds embedded=true, and automatically resizes the iframe as its content changes.
Paste the <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 with data-nautilus-embed="storefront":
To show the host website’s background behind the storefront, add 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.
Replace every placeholder in both 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 with new 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

Set onSuccess before loading the Nautilus script. It can redirect the host page:
Or it can run a callback:
Treat the callback as a conversion signal, not as the source of payment truth. Use Nautilus purchase records or a server-side integration for reconciliation.

Use the loader on a dynamic site

If your application adds an embed container after loader.js has loaded, initialize new containers after rendering:
You can also create an embed directly:

Use a plain iframe

Use the Nautilus loader whenever possible. If a CMS blocks custom JavaScript, use a fixed-height iframe:
This fallback does not resize automatically. Replace its 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 load loader.js or jsDelivr:
Move the example’s CSS and JavaScript into same-origin files, or authorize the inline blocks with your normal nonce or hash mechanism. Do not add 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:
If your policy requires a nonce or hash for inline scripts, apply your normal CSP mechanism to the 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 in data-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:
  1. Click the website’s source link or button.
  2. Confirm the destination URL contains the expected locationId and productId.
  3. Reload that exact URL in a clean browser session.
  4. Confirm the visible location, product name, price, recurrence or trial terms, and organization branding.
  5. For a drawer, confirm it opens from the right on desktop and from the bottom on mobile.
  6. Inspect the iframe and confirm it includes allow="geolocation; payment". Test browser-wallet availability on an eligible browser and device.
  7. 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.
  8. Close the drawer with Escape, the close button, and a backdrop click.
  9. Confirm the page behind the drawer does not scroll while open. Confirm its original scroll position and scroll behavior return after every dismissal method.
  10. 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.
  11. For a loader-based inline embed, test desktop and mobile widths, automatic height changes, scrolling, and browser-wallet availability.
Only complete a test purchase when the environment, payment method, and customer scope are explicitly authorized.

Troubleshoot the integration

The wrong product is selected

  • Confirm the parameter names are exactly locationId and productId.
  • 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.com or cdn.jsdelivr.net.
  • Confirm loader.js loads after window.NautilusEmbedConfig is 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-height so 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.