Open Checkout in a Modal

A buyer clicks Buy on your sales page and lands somewhere else: the checkout page, wrapped in your theme’s header, menu and footer. The page they were reading is gone, and every link on the new one is a way out.

Modal Checkout opens your checkout in a window on top of the page they’re on, so they pay without leaving it. Any button or link can open it, and each one can limit the payment methods it offers.

Turn On the Modal

1. Switch on On-page Checkout and Modal Checkout under Stackless → Dashboard. The modal shows On-page Checkout’s embedded checkout, so without it the Modal Checkout card says “Needs the On-page Checkout module enabled.”
2. Go to Stackless → Settings → Modal Checkout.

Open the Modal from a Button or Link

Add the class stackless-modal-checkout to a button or link. In the block editor it goes in Advanced → Additional CSS class(es), and in page builders in the CSS classes field. The class also works on a block that wraps the button.

Or end a link with #stackless-checkout. What the modal checks out depends on what was clicked:

• A link to a product page checks out that product, or its default variation.
• An Add to cart or Buy now button checks out what it would add, including the variation and quantity chosen on the product page.
• A link to the checkout page checks out the visitor’s cart.
• #stackless-checkout=34 checks out product or variation 34. A page address that ends with it opens the checkout as soon as the page loads, which suits email and ad links.
• A buy link for one product, such as ?stackless-buy=34, checks out that product. Signed links and links with several products work as normal Buy Links.

Add stackless-no-modal to keep a button out. Clicks with Ctrl, Cmd, Shift or Alt held open the link as usual.

Open Every Buy Button Without a Class

Two settings turn the modal on across the store. Both are off by default:

• Add to cart and Buy now: every Add to cart and Buy now button opens the modal, in shop grids, on product pages, in product blocks and on Buy link buttons. Grid buttons for variable, grouped and external products keep their normal links, and buttons set to open in a new tab are left alone.
• Checkout links: links to the checkout page, such as mini-cart and menu links, check out the visitor’s whole cart without leaving the page.

Limit the Payment Methods a Button Offers

Add a payment method class next to the modal class to offer only that method, for example stackless-modal-checkout pay-via-bacs. Add two classes to offer both. Without one, every payment method shows.

Each class is pay-via- plus the payment method’s id. The Classes table under Payment method classes lists every method with its id, its class and a Copy button. For the Stackless gateways:

Payment method	Class
Stripe (Stackless)	pay-via-stripe_gateway
PayPal (Stackless)	pay-via-stackless_paypal
Polar (Stackless)	pay-via-stackless_polar
Paddle (Stackless)	pay-via-stackless_paddle
Dodo Payments (Stackless)	pay-via-stackless_dodo

• Hyphens and underscores count as the same, so pay-via-stripe-gateway works too.
• To use a shorter class, type it in the method’s box, such as polar for pay-via-polar. It can be up to 40 characters, and the id keeps working. A name another method already uses, or another method’s id, isn’t saved.
• Each copy made with Payment Gateway Tools has its own id, so pay-via-stackless_polar_copy2 pays into that account only. pay-via-stackless_polar means the original, not its copies.

The limit is enforced on the server, not only in the browser. Both checkouts hide the other methods, and an order placed with one of them is refused with “This payment method is not offered for this purchase. Choose one of the payment methods shown.”

• A class for a method that’s switched off, or that can’t take the order, is ignored. If none of the named methods can take it, every method shows, so a buyer is never left with none.
• An order with nothing to pay skips the check.
• The limit applies inside the modal only. The classes don’t change the checkout page itself.

What Happens After Payment

After Place order, the whole page moves to the receipt or the payment page, not just the modal. Hosted payment pages, such as PayPal’s approval page or Polar’s checkout, open in the full window.

A product checkout runs on its own cart, so the visitor’s store cart stays as it was, receipt included. A checkout link pays for the store cart itself.

Closing the modal never loses the order. Opening the same checkout again brings back the cart and what the buyer entered. A checkout-link modal reloads each time, since the cart may have changed.

Other Settings

• Close the modal with: The Close button or the Esc key only (default), or The Close button, the Esc key or a click outside.
• Modal heading: up to 80 characters. Empty by default, which shows “Secure checkout”.
• Coupon from the page address: on by default. Applies a ?coupon= code from the page address. A ?coupon= in the clicked link wins.

For Developers

• On a button with the modal class, data-stackless-product (a product or variation id), data-stackless-quantity and data-stackless-coupon set what it checks out. A data-stackless-modal-checkout attribute works like the class.
• stacklessModalCheckoutApi.open(34, 1, 'CODE', ['bacs']) opens a checkout from your own script. openCart() and close() are there too.
• A stackless:modal-checkout event fires on the document for open, ready, error, close and complete. When the page has a dataLayer, it also gets a stackless_modal_checkout event.
• The stackless_modal_checkout_enabled filter turns the modal off on a page, and stackless_modal_checkout_config filters its settings.

Limits

• The modal doesn’t load on the checkout page itself.
• Quantities run from 1 to 100.
• Grouped and external products can’t be bought in the modal. A product page link to one opens as a normal link.
• A checkout that hasn’t loaded after 20 seconds shows “Checkout is taking too long to load.” and an “Open the checkout page instead” link.
• Only pages on your own site can embed the checkout.
• New product checkouts count toward the New checkouts per connection limit in On-page Checkout.