Skip to main content
POST
Subscribe a Client to a Plan
This is not a hosted-checkout redirect. The subscription is created directly against your agency’s saved card, so a script can run it. It was the last step of client onboarding that needed a browser.

Endpoint

  • Method: POST
  • Path: /api/agency/billing/subscribe
  • Auth: Authorization: Bearer tucoagency_xxxxxxxxxxxxx (agency key)

Body

You need a card on file first

The charge goes to the agency owner’s saved payment method, off-session. If there isn’t one, you get 400 no_card — add it from Agency view → Billing, then retry. Any agency member (or key) can subscribe a workspace; the charge always lands on the owner’s card, so nobody can mis-bill anyone else. The setup fee, if your agency pays one, lands on the subscription’s first invoice together with the first month — the same site pricing a direct customer pays, minus whatever discount is attached to your agency.

If Tuco invoices your agency directly

Agencies on invoice billing don’t need a card at all. The same call puts the client on a plan, creates no Stripe subscription, and charges nothing — Tuco bills your agency offline for the whole group.
subscriptionId is null and the client workspace gets no stripeCustomerId. That absence is the point: your clients cannot be dunned, emailed about a failed payment, or sent to a checkout page, because they do not exist in Stripe at all. Add-on lines work the same way — the slot is granted and appears on your agency’s next invoice. Invoice billing is set by Tuco on your agency account, not self-serve. Ask us.

Why the plan is still required either way

It’s tempting to read “we invoice our own clients” as “no subscription record at all”. That breaks the product: a workspace’s plan is what grants its entitlements. organizations.plan sets how many phone and email lines it may hold, and an agency workspace left at subscriptionStatus: 'none' is refused outright by the line guard — it cannot order a line, and a transfer into it is rejected with “Target workspace has no active subscription”. So subscribe every client, in either mode. A plan is an entitlement, not a charge. What you control is the price: on Stripe billing that’s your agency’s discount coupon; on invoice billing it’s whatever we agreed. Either way, what you charge your client on your own invoice is separate and Tuco never sees it.

Error responses