Guides / Billing API

Billing API

Read subscription dates, plan allowances, AI usage warnings, credit balances, and fixed credit packs through the Goliath developer API

About

Read your organization’s plan, subscription dates, seat utilization, and credit balances. Check AI credit usage and low-balance warnings, look up fixed credit packs, and direct a human to the appropriate purchase page.

All operations go through the developer API gateway — one endpoint, called by operationId. If you haven’t set up a key yet, start with the Developer API Overview.

Operations

operationId	Scope	What it does
`getBillingSummary`	`ADMIN`	Read the organization’s plan, subscription lifecycle, seat utilization, feature limits (including `phoneNumbersCap` and `callingMinutesCap`), and credit balances, including `AI_CREDITS` and `SMS_CREDITS`. Read-only — never spends.
`getAiCreditUsage`	`READ`	AI credits consumed over a trailing window, the live balance, `outOfCredits`, `lowOnCredits`, and `lowCreditThresholdCredits`. Optional `windowDays` defaults to 30 and is clamped to 1–90; the response reports the window used. `planAllowance` splits the balance into this period’s included AI credits and the purchased wallet.
`getCreditUsageByType`	`ADMIN`	What used the credits this billing period, per credit type: `series[].totalUnits` for `AI_CREDITS`, `SMS_CREDITS` (outbound text segments), `CALLING_MINUTES`, `SKIPTRACE`, `EMAIL_VERIFICATION`, and `EXPORT_PROPERTIES` — the Billing page usage chart’s figures. Pass `timeZone` (`getMyProfile.resolvedTimezone`) so days fall as the person’s chart draws them; omitted, they are UTC days. Null before a first billing period. Quote it as what used the credits; what is left is `getBillingSummary`’s `planUsage`.
`getCreditPrices`	`READ`	The fixed credit-pack catalog, live from Stripe. Each `packs` row contains `creditType`, `code`, `units`, whole-pack `priceCents`, and `available`. Legacy unit-price fields remain for compatibility and are not sellable prices.
`getCreditsPurchaseUrl`	`READ`	The in-app Billing → Credits page URL where a human buys more credits.
`getAddOnPrices`	`READ`	The current monthly price of one extra seat in cents, live from Stripe.
`getSeatsPurchaseUrl`	`READ`	The in-app Billing page URL where a human buys extra seats. Compare `extraSeats.seatsUsed` with `extraSeats.seatsCap` before recommending a purchase.
`getPhoneNumbersPurchaseUrl`	`READ`	The in-app Team & Phones page URL where a human registers and purchases phone numbers.
`checkBillingAction`	`READ`	The check the app runs before a skip trace, export or email verification of `count` records. Read `state` and `reason` first: a `BLOCKED` organization (payment needed) shows 0 whatever it holds. For those three actions `unitsAvailable` is unused plan allowance plus wallet credits — the answer to “how many skip traces do I have left”. `willTriggerAutoRecharge.chargeCents` is a card charge: confirm with the person first.
`getPlanCatalog`	`READ`	Every plan on sale: monthly and annual price, and what each includes per month. Quote the `Formatted` values; never divide `Cents`. The current plan is `getBillingSummary`.

Subscription dates and seats

Use trialEnds to report when a trial ends and cancelAt to identify a scheduled cancellation. A deferred plan change appears in pendingPlanCode, pendingPlanIsAnnual, and pendingPlanEffectiveAt; until that date, planType is still the current plan. Those pending fields are null when no change is scheduled. isGrandfathered identifies a legacy price, and currentUnitAmountCents is the amount paid for the core plan.

extraSeats.seatsCap is total capacity, including add-ons. Compare it directly with extraSeats.seatsUsed; do not add extraSeatQuantity again. featureLimits.seatsCap is only the plan’s included seats. A null unusedPaidSeats means the count is unknown, not zero; unusedPaidSeatsReleaseAt reports the scheduled release date when available.

featureLimits.phoneNumbersCap and featureLimits.callingMinutesCap report the plan’s phone-number and calling-minute allowances. These fields describe allowances; they do not report current usage or prove that quota enforcement is enabled for your organization.

Credit packs

Quote top-ups from getCreditPrices.packs, using each pack’s units and total priceCents. Offer only rows with available: true; false means the Stripe price is unavailable or mismatched. Do not calculate a purchase quote from the legacy per-credit fields. Send getCreditsPurchaseUrl to the human who will complete the purchase.

Texting credits

creditLedger includes SMS_CREDITS, and featureLimits.smsCreditsCap is the plan’s included monthly texting-credit allowance. One credit equals one outbound carrier text segment; a multi-segment message consumes multiple credits. Inbound texts do not consume texting credits. Use the texting packs from getCreditPrices.packs to quote a top-up.

AI credit usage

getAiCreditUsage returns creditsConsumed, balanceCredits, and outOfCredits, plus lowOnCredits and lowCreditThresholdCredits. One AI credit represents one cent of AI cost. Balances may be negative; featureLimits.aiCreditsCap in the billing summary is the plan’s included monthly allowance.

planAllowance is this billing period: includedCredits the plan includes, usedThisPeriod, includedRemaining, purchasedBalance (bought or granted credits, spent once the included ones run out or during a trial when lockedDuringTrial is true), and periodResetsAt, when the included credits renew.

lowOnCredits: true is an early warning: the balance is still positive but at or below lowCreditThresholdCredits. It is mutually exclusive with outOfCredits; report the warning and threshold without claiming AI work has already stopped.

Operations that spend credits or money

Every operation below spends from the organization’s plan allowance first, then purchased credits (or, for phone numbers, the card on file), exactly as the same action in the app does. Check checkBillingAction before a large skip trace or export, and confirm the count and the cost with the person.

operationId	Spends	Scope	Page
`enrichContact`, `createContactFromProperty`	Skip-trace credits	`ADMIN`	Contacts
`skipTraceProperty`, `manualSkiptrace`	Skip-trace credits	`ADMIN`	Properties
`skipTraceContacts`, `skipTraceAndExportProperties`, `skipTraceAndCreateContactsFromProperties`	Skip-trace credits, one per record	`ADMIN`	Files
`exportContacts`, `exportProperties`	Export credits	`ADMIN`	Files
`confirmLibraryFileRun`	Skip-trace credits, when the run is a skip trace	`WRITE`	Library
`decideCatchUpCard`	Skip-trace credits, when an accepted row is a skip trace	`WRITE`	Notifications
`queueMemoryDream`	AI usage	`WRITE`	Library
`provisionPhoneNumber`, `buyDialingPoolNumbers`	Money: a recurring monthly charge per number ($5/month past the plan’s included numbers)	`ADMIN`	Communications
`updateOrganizationAreasOfOperation`	Money, when the phone-number plan buys numbers for an added market	`ADMIN`	Account

Usage the app meters also applies to what the API sets in motion: each outbound text segment (sendText, a workflow, an AI employee) uses one texting credit, and Ask Goliath and AI employee work uses AI credits. getCreditUsageByType shows what used them.

Example

Check the skip-trace balance before a batch enrichment:

curl -X POST https://server.goliathdata.com/api/v1/call \
  -H "Authorization: Bearer gsk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "operationId": "getBillingSummary", "variables": {} }'

Full variable schemas, response shapes, and worked examples for every operation are available from the discovery endpoint.