Skip to main content
Every Macropay checkout already adapts to the visitor’s system preference. But when your buy page lives inside a dark dashboard, a marketing site, or an in-app modal, you usually want the checkout to match your surface — not the customer’s OS setting. The theme query parameter lets you pin the look to light or dark with zero extra API calls. It works identically whether you launch checkout from an API-created session or from a reusable checkout link — and because Macropay is the Merchant of Record, the page you’re theming is also the one that handles tax, PCI, and the receipt your customer sees.
theme accepts exactly two values: light and dark. Omit it entirely to fall back to the customer’s system preference (the default).

​
Theming an API checkout session

1

Create the session and grab its url

Spin up a Checkout Session as shown in the Create a checkout session guide. The response includes a hosted url — that’s what you redirect the customer to.
2

Pin it to dark mode

Append ?theme=dark to the url before redirecting:
3

Or force light mode

Swap the value to light to do the opposite:
Building the redirect in code? Reuse the session url straight from the API response and tack the parameter on the end — no need to template the full path by hand.
Reusable checkout links redirect through Macropay before landing on the hosted page, so the theme parameter goes on the link’s /redirect URL.
1

Create the checkout link

Follow the Create a checkout link guide to mint a link you can drop into a button, email, or QR code.
2

Pin it to dark mode

Add ?theme=dark to the redirect URL:
3

Or force light mode

Use light instead — the parameter carries through the redirect to the final checkout page:
The example above points at sandbox-api.macropay.ai so you can test the flow safely. Swap the host for your production checkout link once you’ve confirmed the theme renders the way you want.

​
Quick reference

That’s the entire feature — no SDK flag, no dashboard toggle, no extra request. Set the value that matches the page your customer came from, and Macropay handles the rest of the transaction underneath it.