Billing API

REST endpoints for billing in ServFlo: 4 operations with parameters, request and response fields, permissions and curl examples.

Base URL: https://app.servflo.ai/api. Every call needs Authorization: Bearer sfk_… (Authentication); {organizationId} ($ORGANIZATION_ID in the examples) is your business's id.

Operation	Endpoint	Risk
Get the ServFlo plan	`GET /organizations/{organizationId}/billing/plan`	`read`
List the plans to choose from	`GET /organizations/{organizationId}/billing/plan-options`	`read`
Choose a plan (first run)	`POST /organizations/{organizationId}/billing/choose-plan`	`sensitive`
List AI credit packs	`GET /organizations/{organizationId}/billing/credit-packs`	`read`

Get the ServFlo plan

GET /organizations/{organizationId}/billing/plan

The business's ServFlo plan: tier, trial, which plan features are included, and this period's AI credits, texts and ServFlo emails (used, allowance, purchased credits, remaining). Also lists every plan for comparison. Read-only; any member.


Permission	`organization.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`billing_plan` (toolset `settings`)

Parameters

Name	In	Type	Required	Description
`fresh`	query	boolean	No	Ask Base316 again instead of the cached minute (after returning from the billing portal; at most every 10 seconds per business).

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/billing/plan" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`tier`	enum or null	Null when billing is not set up on this server. One of `core`, `connect`, `grow`, `pro`.
`planName`	string or null
`status`	string or null	TRIALING, ACTIVE, PAST_DUE, CANCELED, ...
`trialEndsAt`	string or null
`trialDaysLeft`	integer or null	Whole days left in the trial; null when not trialing.
`currentPeriodEnd`	string or null
`cancelAtPeriodEnd`	boolean
`features`	object	Plan feature key → included.
`usage`	object
`usage.ai_credits`	object or null
`usage.ai_credits.used`	number
`usage.ai_credits.limit`	number or null	Null is unlimited.
`usage.ai_credits.credits`	number	Purchased or granted on top of the plan's allowance.
`usage.ai_credits.remaining`	number or null	Below zero: past the allowance (texts are then billed per segment).
`usage.ai_credits.overage`	boolean
`usage.sms`	object or null
`usage.sms.used`	number
`usage.sms.limit`	number or null	Null is unlimited.
`usage.sms.credits`	number	Purchased or granted on top of the plan's allowance.
`usage.sms.remaining`	number or null	Below zero: past the allowance (texts are then billed per segment).
`usage.sms.overage`	boolean
`usage.emails`	object or null	ServFlo emails this period (allowance, used); null when the plan version predates the email allowance (then see `emails` below).
`usage.emails.used`	number
`usage.emails.limit`	number or null	Null is unlimited.
`usage.emails.credits`	number	Purchased or granted on top of the plan's allowance.
`usage.emails.remaining`	number or null	Below zero: past the allowance (texts are then billed per segment).
`usage.emails.overage`	boolean
`usage.ai_voice_minutes`	object or null	AI receptionist minutes this period (billed at cost + 20%); null when the plan version does not price them.
`usage.ai_voice_minutes.used`	number
`usage.ai_voice_minutes.limit`	number or null	Null is unlimited.
`usage.ai_voice_minutes.credits`	number	Purchased or granted on top of the plan's allowance.
`usage.ai_voice_minutes.remaining`	number or null	Below zero: past the allowance (texts are then billed per segment).
`usage.ai_voice_minutes.overage`	boolean
`usage.visit_safety_checks`	object or null	Visit safety lookups this period ($0.25 each); null when the plan version does not price them.
`usage.visit_safety_checks.used`	number
`usage.visit_safety_checks.limit`	number or null	Null is unlimited.
`usage.visit_safety_checks.credits`	number	Purchased or granted on top of the plan's allowance.
`usage.visit_safety_checks.remaining`	number or null	Below zero: past the allowance (texts are then billed per segment).
`usage.visit_safety_checks.overage`	boolean
`usage.telephony_usage`	object or null	Telephony billed this period, in cents (numbers, call minutes, recordings at Twilio's cost + 20%); null when not priced.
`usage.telephony_usage.used`	number
`usage.telephony_usage.limit`	number or null	Null is unlimited.
`usage.telephony_usage.credits`	number	Purchased or granted on top of the plan's allowance.
`usage.telephony_usage.remaining`	number or null	Below zero: past the allowance (texts are then billed per segment).
`usage.telephony_usage.overage`	boolean
`visitSafety`	object or null	Visit safety lookups counted here this month; null when they cannot be counted.
`visitSafety.usedThisMonth`	number	Paid visit safety lookups this calendar month (UTC).
`visitSafety.monthlyCap`	number	The business's monthly limit (Settings → Visit safety).
`emails`	object or null	ServFlo email against the plan's allowance; null when it cannot be counted.
`emails.usedThisMonth`	number	Emails sent through ServFlo email this calendar month (UTC), counted here.
`emails.allowance`	number or null	The plan's monthly email allowance (null: unknown plan).
`officeUsers`	object	Owners, admins, dispatchers and office staff against the plan's number.
`officeUsers.used`	integer or null	Office members plus pending office invitations; null when it could not be counted.
`officeUsers.limit`	integer or null	Office users allowed: the plan's included ones plus the extra ones bought. Null is unlimited. Technicians are never counted.
`officeUsers.included`	integer or null	The plan's own office users (null is unlimited).
`officeUsers.extra`	integer	Extra office users bought ($35/month each; `billing.setOfficeSeats`).
`officeUsers.extraMonthlyPrice`	number	USD per extra office user per month.
`officeUsers.extraYearlyPrice`	number	USD per extra office user per year (yearly plans).
`officeUsers.maxExtra`	integer
`spend`	object	Whether ServFlo may spend money for the business now (the cost gate).
`spend.standing`	enum	PAYMENT_METHOD_REQUIRED: a trial without a card: everything can be explored, but numbers, registrations, texts and calls to customers, the AI receptionist, ad spend, visit safety checks and campaigns wait for a card (402 PAYMENT_METHOD_REQUIRED). Add one in the billing portal (`billing.portal` with `page: "payment-methods"`); nothing is charged until the trial ends. One of `OK`, `PAYMENT_METHOD_REQUIRED`, `BILLING_UNAVAILABLE`.
`spend.cardOnFile`	boolean or null	A card is on file (read during the trial and on Core); null when not read.
`spend.comped`	boolean	A 100% coupon: never needs a card.
`spend.noCardAiCredits`	integer	AI credits a trial without a card may use in all.
`spend.noCardEmailsPerDay`	integer	Test emails a day to the team's own addresses without a card.
`degraded`	boolean	Billing could not be reached: this is the last known plan, or (`planSource` outage) none, and paid add-ons and new office users are paused.
`subscriptionRequired`	boolean	The business has no live subscription (cancelled, unpaid, expired): ServFlo is read-only until a plan is chosen (`billing.choosePlan`). Reads, exports, billing and winding down still work; other writes answer 402 SUBSCRIPTION_REQUIRED.
`planSource`	enum	Where the plan came from: live (Base316), memory or stored (the last answer, Base316 unreachable), outage (nothing known), fake (development). One of `live`, `memory`, `stored`, `outage`, `fake`.
`tiers`	array of object	Every plan, cheapest first, for comparison and upgrade prompts.
`tiers[].key`	string
`tiers[].name`	string
`tiers[].tagline`	string
`tiers[].monthlyPrice`	number
`tiers[].yearlyPrice`	number
`tiers[].features`	array of string
`tiers[].officeUsers`	number or null
`tiers[].aiCredits`	number
`tiers[].smsSegments`	number
`tiers[].emails`	number	ServFlo emails a month.
`trial`	object
`trial.tier`	string
`trial.days`	number
`addons`	array of object	Paid add-ons sold on any plan, and whether this business has each one.
`addons[].key`	string	Add-on key: `phone`, `ai_receptionist`, `ads`, `service_reports` or `extra_office_user` (seats: `billing.setOfficeSeats`).
`addons[].feature`	string or null	The plan feature it includes; null for extra office users.
`addons[].model`	enum	PER_UNIT: priced per unit (one per extra office user). One of `FLAT`, `PER_UNIT`.
`addons[].includedInTiers`	array of string	Plans that already include it (not sold to them).
`addons[].soldOnPlan`	boolean	Can be added on this business's plan (false when the plan includes it).
`addons[].quantity`	integer	Units attached now (extra office users); 0 or 1 otherwise.
`addons[].name`	string
`addons[].description`	string
`addons[].monthlyPrice`	number	USD per month on a monthly plan.
`addons[].yearlyPrice`	number	USD per year on a yearly plan.
`addons[].includedInTrial`	boolean	The free trial includes it, within the trial's telephony limits.
`addons[].requires`	string or null	The add-on it needs first (`phone`).
`addons[].includedNumbers`	integer	Local numbers it includes.
`addons[].draft`	boolean	Not on sale yet: its price is not decided, and adding it is refused (409).
`addons[].attached`	boolean	On this business's subscription now.
`addons[].terms`	object	The fee and every usage rate today: shown and accepted before adding it.
`addons[].terms.key`	string
`addons[].terms.name`	string
`addons[].terms.monthlyPrice`	number	USD per month on a monthly plan.
`addons[].terms.yearlyPrice`	number	USD per year on a yearly plan.
`addons[].terms.includedNumbers`	integer	Local numbers whose monthly charge is included.
`addons[].terms.requires`	string or null	The add-on it needs (`phone`), or null.
`addons[].terms.markup`	number	Usage is billed at cost × this (1.2 = cost + 20%).
`addons[].terms.rates`	array of object	Every usage rate at the price the business pays.
`addons[].terms.example`	object
`addons[].terms.trial`	object	What the free trial includes before the phone and AI receptionist pause.
`addons[].terms.ratesSource`	enum	Twilio's Pricing API today, or ServFlo's documented fallback table. One of `twilio`, `fallback`.
`addons[].terms.priceVersion`	string	Send this back in `acknowledgement.priceVersion`.
`addons[].acknowledgement`	object or null	The last acceptance of its terms (who, when, which version), or null.
`addons[].acknowledgement.userId`	string
`addons[].acknowledgement.userName`	string or null
`addons[].acknowledgement.acceptedAt`	string (date-time)
`addons[].acknowledgement.priceVersion`	string
`addons[].acknowledgement.context`	enum	One of `ADD_ADDON`, `MANAGED_TELEPHONY`, `REVIEW`.
`addons[].acknowledgement.terms`	object or null	Exactly what was shown and accepted (“View terms”).
`addons[].needsReview`	boolean	Attached, and its prices changed since they were accepted: an owner should review and accept them again (`billing.acknowledgeTerms`). Nothing is removed.
`billingInterval`	enum or null	The subscription's interval: usage is billed in arrears at the end of each. One of `month`, `year`.

List the plans to choose from

GET /organizations/{organizationId}/billing/plan-options

The ServFlo plans a business can choose, cheapest first, as Base316 sells them: name, description, monthly and yearly price (integer cents), office users included (null = unlimited), the features included, and the free-trial days on the trial plan. Also trial (the plan and days a new business starts on with no card) and whether this business still has to choose (needsChoice). Read-only; any member. Choose with POST /billing/choose-plan.


Permission	`organization.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`billing_planOptions` (toolset `settings`)

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/billing/plan-options" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`plans`	array of object
`plans[].key`	string
`plans[].name`	string
`plans[].description`	string or null
`plans[].monthlyCents`	integer or null
`plans[].yearlyCents`	integer or null
`plans[].officeUsers`	integer or null
`plans[].features`	array of string
`plans[].trialDays`	integer or null
`trial`	object
`trial.tier`	string
`trial.days`	integer
`needsChoice`	boolean

Choose a plan (first run)

POST /organizations/{organizationId}/billing/choose-plan

Money: the owner's plan choice after sign-up. plan: "trial" keeps the free trial the business started on (no card, nothing billed) and returns url: null. A plan key (with interval month or year) returns a one-time Base316 checkout link for that plan, where the owner enters a card and pays; the trial ends once the paid plan starts. Either way the business no longer sees the plan screen. Owner only.


Permission	`organization.accessBillingPortal` (Owner)
Risk	`sensitive`, OAuth scope `servflo.sensitive`. Sensitive: moves money, deletes, sends or shows something to a customer, or grants or revokes access.
MCP tool	`billing_choosePlan` (toolset `settings`)
Approval	Waits for your approval in ServFlo when called with an API key or a connected app: the first call answers `428 APPROVAL_REQUIRED`; once you approve it, repeat the call with the `X-ServFlo-Approval` header. See Approvals.

Request body

Field	Type	Required	Description
`plan`	enum	Yes	"trial" to keep the free trial, or a plan key from GET /billing/plan-options. One of `trial`, `core`, `connect`, `grow`, `pro`.
`interval`	enum	No	One of `month`, `year`. Default `month`.

Example

curl -X POST "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/billing/choose-plan" \
  -H "Authorization: Bearer $SERVFLO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan":"trial"}'

Response

200: the answer's fields

Field	Type	Description
`url`	string or null	The Base316 checkout page to open; null when nothing is to be paid.

List AI credit packs

GET /organizations/{organizationId}/billing/credit-packs

The AI credit packs on sale (credits, price), cheapest first. Buy one with billing.buyCredits. Read-only.


Permission	`organization.read` (Owner, Admin, Dispatcher, Technician, Member)
Risk	`read`, OAuth scope `servflo.read`. Read: reads only.
MCP tool	`billing_creditPacks` (toolset `settings`)

Example

curl "https://app.servflo.ai/api/organizations/$ORGANIZATION_ID/billing/credit-packs" \
  -H "Authorization: Bearer $SERVFLO_API_KEY"

Response

200: the answer's fields

Field	Type	Description
`packs`	array of object
`packs[].key`	string
`packs[].name`	string
`packs[].credits`	number
`packs[].price`	string
`packs[].currency`	string

On this page