Implementing Seat-Based Pricing

Most billing assumes the person who pays is the person who uses the product. Team plans break that assumption: a finance lead buys ten seats, then ten engineers each get their own license key, Discord role, or download. Seat-based pricing models that split — billing on one side, entitlements on the other — and Macropay handles the seller-of-record paperwork (global sales tax and VAT, disputes, PCI) on top.

Seat-based pricing is in private beta. Reach out to support to enable it for your organization before you build against it.

The three entities

A seat-based product introduces a layer that single-buyer products don’t have. Get these three concepts straight and every API call, webhook, and portal screen will make sense.

Entity	Answers	Notes
Customer	Who pays?	The billing entity. Owns subscriptions, orders, payment methods. On the first seat-based purchase it is permanently upgraded to `type: "team"`.
Member	Who uses?	A person under a customer, with their own email and role (`owner`, `billing_manager`, or `member`). Receives benefit grants independently. The purchaser becomes an `owner`.
CustomerSeat	Who’s assigned to what?	The link between a product and a member. Tracks status (`pending`, `claimed`, `revoked`), holds the invitation token, and carries optional metadata.

Roles map directly to capability. Both owner and billing_manager can assign seats, change or cancel the subscription, and manage payment methods. A plain member sees only their own benefits. (The owner role may gain extra management powers later.) Here’s how it fits together for a six-seat team plan, of which four seats are in use:

Customer: Maya (purchaser, type: "team")
  ├── Member: Maya   (owner)            → runs the team; can self-assign a seat for access
  ├── Member: Devon  (member)           → access via seat
  ├── Member: Priya  (member)           → access via seat
  └── Member: Sol    (member)           → access via seat

Subscription: "Studio Pro" — 6 seats
  ├── CustomerSeat → Devon  (claimed)   → benefits granted
  ├── CustomerSeat → Priya  (claimed)   → benefits granted
  ├── CustomerSeat → Sol    (claimed)   → benefits granted
  └── CustomerSeat → unassigned ×2      → available

Why the split is worth it

Members outlive any single purchase. One member can hold seats from several subscriptions or one-time orders under the same customer.
Entitlements attach to people, not invoices. Benefits are granted when a seat is claimed, never at checkout.
The portal adapts to the role. Owners and billing managers get team management; members get a personal benefits view.

The most common integration bug: reading grant.customer_id to decide who gets access. That field is always the payer. The end user lives on grant.member. Use grant.member everywhere you provision access.

The lifecycle, in one line:

Purchase → Assign seats → Members claim → Benefits granted

What you’ll need

A Macropay organization with seat-based pricing enabled (private beta)
The latest Macropay SDK — npm install @macropayments/sdk or pip install macropay
Familiarity with Macropay products and subscriptions

This guide covers both subscription and one-time seat products. The assignment and claim flow is identical; only how you add seats later differs (modify the subscription vs. buy another order).

Step 1 — Create the product

Open Products

In the dashboard, go to Products and click Create Product.

Set pricing

Under Pricing:

Product type — Subscription (recurring) or One-time (perpetual licenses)
Pricing type — Seat-based
Min seats — 1, or your minimum team size

Seat pricing is volume-based: the total seat count picks a tier, and that tier’s rate applies to every seat. Buy 7 seats and you land in the 5–9 tier, so all 7 bill at that tier’s rate (7 ×

9 =

63/mo).

Tier	Up to	Per seat
1	4	$10/mo
2	9	$9/mo
3	∞	$8/mo

Attach benefits

Add the benefits each seat holder receives — license keys, file downloads, Discord roles, GitHub repo access, and so on. These are granted on claim, not at purchase.

Step 2 — Checkout

Pass seats and let Macropay compute the volume price from your tiers. Because Macropay is the merchant of record, the sales tax or VAT for the buyer’s jurisdiction is calculated and remitted for you — it never lands on your tax filings.

const checkout = await macropay.checkouts.create({
  products: ["prod_studio_pro"],
  seats: 7,
  customer_email: "ops@northwind.example",
  success_url: "https://app.northwind.example/billing/done",
});

// Send the buyer to checkout.url

Step 3 — Assign seats

Once the order is paid, an owner or billing manager can run seat management straight from the Customer Portal — no UI to build. The portal lets them:

Assign a seat to a teammate by email
Revoke a seat to cut access and free it for reuse
Resend the invite for a still-pending seat
Adjust the seat count on a subscription

Assigning a seat fires an invitation email with a secure claim link. The moment the teammate claims it, their benefits are granted.

The invite and claim flow is fully hosted by Macropay. Members click the link, claim the seat, and get immediate access — you don’t render or send anything.

Assigning seats from your own backend

If you already authenticate users and want to wire seats to signups, call the Customer Seats API directly:

const seat = await macropay.customerSeats.assign({
  subscription_id: subscriptionId,
  email: "new.hire@northwind.example",
  immediate_claim: true, // skip the email, grant benefits now
});

Set immediate_claim: true when your app owns identity. It bypasses the invitation email and grants benefits on the spot — ideal for auto-provisioning a seat the instant a user joins a workspace you already control.

Step 4 — Provision on benefit grants

Listen for benefit-grant webhooks and mirror access in your own system. The recipient is grant.member; grant.customer_id is the payer.

Always verify the webhook signature before trusting an event. The handler below omits verification for brevity only.

app.post("/webhooks/macropay", async (req, res) => {
  // Verify the Standard Webhooks signature first — see the webhook docs.
  const event = req.body;

  switch (event.type) {
    case "benefit_grant.created": {
      const grant = event.data;
      await grantAccess(grant.member.id, grant.member.email, grant.benefit);
      break;
    }
    case "benefit_grant.revoked": {
      const grant = event.data;
      await revokeAccess(grant.member.id, grant.benefit);
      break;
    }
  }

  res.sendStatus(200);
});

Step 5 — Change the seat count

Subscriptions — patch the seat total:

await macropay.subscriptions.update({
  id: subscriptionId,
  seats: newTotal, // must be ≥ currently assigned seats (pending + claimed)
});

You can’t drop below the number of assigned seats (pending plus claimed). Revoke the seats you no longer need first, then reduce the count.

One-time purchases — buy another order; each has its own independent seat pool:

const checkout = await macropay.checkouts.create({
  products: [productId],
  seats: additionalSeats,
  success_url: "https://app.northwind.example/billing/done",
});

Giving members the portal

To drop a member into the customer portal — to see their benefits or, for managers, to run the team — create a member session and redirect to the returned URL:

const session = await macropay.memberSessions.create({
  member_id: "mem_4f2a",
});
// Redirect to session.member_portal_url

What they see depends on their role:

Owners and billing managers — full team management: assign seats, manage members, review utilization.
Members — their own benefits and account details, nothing more.

Webhook reference

Event	Fires when	Key fields
`order.paid`	The purchase completes	`customer_id`, `product`
`subscription.updated`	Seat count changes	`customer_id`, `seats`
`customer_seat.assigned`	Seat assigned, invite sent	`member`, `email`, `status: "pending"`
`customer_seat.claimed`	Member claims the seat	`member`, `status: "claimed"`
`customer_seat.revoked`	Seat revoked	`member`, `status: "revoked"`
`benefit_grant.created`	Benefit granted to a member	`member`, `customer_id` (payer)
`benefit_grant.revoked`	Benefit removed from a member	`member`, `customer_id` (payer)

Cancellations fan out. Each seat is revoked individually, so a 5-seat subscription carrying 3 benefits emits 1 + 5 + 15 = 21 events. Make every handler idempotent.

Patterns worth adopting

Provision off grant.member, never grant.customer_id. It’s the single most reliable way to attribute access to the right person.
Use seat metadata for your own bookkeeping — stash a department, cost center, or internal user ID on the seat (up to 10 keys / 1KB).
Tell billing managers they aren’t auto-enrolled. A manager who also wants the product must assign a seat to themselves.

Troubleshooting

Symptom	Fix
Can’t reduce the seat count	Revoke assigned seats first; you can’t go below pending + claimed.
Claim link no longer works	Tokens expire after 24 hours. Resend from the portal or via `macropay.customerSeats.resend({ seat_id })`.
Wrong user provisioned	You read `customer_id`. Switch to `grant.member`.

Subscriptions vs. one-time

	Subscription	One-time
Payment	Recurring (monthly / yearly)	Single charge
Seat duration	While subscribed	Perpetual
Adding seats	Modify the subscription	Buy a new order
Benefits	While the subscription is active	Forever after claim

Limits

Seats are assigned one at a time (script the API for bulk).
Claim links expire after 24 hours.
Up to 1,000 seats per subscription.
Seat metadata: 10 keys, 1KB max.

Getting Started

Guides

Implementing Seat-Based Pricing

The three entities

Why the split is worth it

What you’ll need

Step 1 — Create the product

Step 2 — Checkout

Step 3 — Assign seats

Assigning seats from your own backend

Step 4 — Provision on benefit grants

Step 5 — Change the seat count

Giving members the portal

Webhook reference

Patterns worth adopting

Troubleshooting

Subscriptions vs. one-time

Limits

Where to go next

​The three entities

​Why the split is worth it

​What you’ll need

​Step 1 — Create the product

​Step 2 — Checkout

​Step 3 — Assign seats

​Assigning seats from your own backend

​Step 4 — Provision on benefit grants

​Step 5 — Change the seat count

​Giving members the portal

​Webhook reference

​Patterns worth adopting

​Troubleshooting

​Subscriptions vs. one-time

​Limits

​Where to go next

The three entities

Why the split is worth it

What you’ll need

Step 1 — Create the product

Step 2 — Checkout

Step 3 — Assign seats

Assigning seats from your own backend

Step 4 — Provision on benefit grants

Step 5 — Change the seat count

Giving members the portal

Webhook reference

Patterns worth adopting

Troubleshooting

Subscriptions vs. one-time

Limits

Where to go next