Skip to main content
Reference docs tell you what every field does. Guides tell you how to ship a specific outcome — a working checkout, a metered AI product, a subscription upgrade flow — without stitching the pieces together yourself. Each guide is self-contained: a concrete scenario, the exact API calls and SDK snippets, and the result you should see at the end. Because Macropay is your merchant of record, most of these flows also mean sales tax, VAT, and PCI scope are handled for you — you wire up the product, we handle the seller-of-record obligations.

​
Start here

New to Macropay? These three cover the path from zero to your first live payment.

Quickstart

Create a product and take your first payment end to end

Checkout sessions

Spin up a hosted, PCI-compliant checkout from the API

Webhooks

Receive and verify lifecycle events in your backend

​
Pick a guide by what you’re building

​
Frameworks & SDKs

Drop Macropay into your existing stack with a framework adapter or a typed SDK.

Next.js

Wire checkout, the customer portal, and webhooks into a Next.js app

Laravel

Integrate billing into a Laravel application

Python

Use the Python SDK to manage products, checkouts, and orders

Encore

Add Macropay to an Encore backend

​
AI & agent billing

Monetize models and autonomous agents by usage, activity, or verified outcome — Macropay tracks the AI cost behind each call so you can see margin, not just revenue.

AI billing

Meter token usage, bill per outcome, and route calls through the AI proxy

Grant credits after purchase

Top up a customer’s prepaid usage balance once an order completes

Grant credits before purchase

Seed trial or free-tier credits before a customer pays

Automate link sharing

Deliver a resource link automatically after a successful purchase

​
Subscriptions & plan changes

Handle the lifecycle most billing bugs hide in: upgrades, downgrades, proration, and seats.

Subscription upgrades

Move a customer to a higher plan and charge correctly

Subscription downgrades

Schedule a step-down so it takes effect at the period boundary

Proration

Control how mid-cycle plan changes are credited and charged

Seat-based pricing

Bill per seat and keep counts in sync as a team grows

Multiple subscriptions

Let one customer hold more than one active subscription

Migrate seats to members

Move an existing seat-based plan onto the member model

​
Checkout & customer experience

Tune what buyers and existing customers see — branding, product order, and self-serve management.

Customer portal

Give customers self-serve invoices, upgrades, and cancellations

Theme switching

Match checkout to your brand’s light and dark themes

Order products in checkout

Control the sequence products appear in

Order benefits in checkout

Reorder the entitlements shown to buyers

Product variants

Offer multiple variants of a single product

Lock the email field

Prevent buyers from editing a pre-filled email at checkout

​
Account & operations

Org setup, merchant-side housekeeping, and scheduled jobs.

Multiple organizations

Run several brands or businesses from one account

Change merchant email

Update the email on your merchant account

Restrict portal changes

Disable subscription edits in the customer portal

Schedule downgrades with QStash

Trigger a delayed downgrade with a scheduled job
Every guide runs against the sandbox with the same API and SDKs as production — build and test the full flow before going live, with no charges and no risk.

​
Missing a guide?

If there’s a flow you’d like us to document, email sales@macropay.ai and tell us what you’re trying to build.