> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goliathdata.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Billing API

> Read your plan, credit balances, and credit prices through the Goliath developer API

## About

Read-only visibility into your organization's plan and credit balances, plus
current credit prices — enough for an integration or agent to check whether a
credit-spending call (like a skip trace) can proceed, and to tell a human
where to top up.

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](/developer-api/overview).

## Operations

| operationId             | Scope   | What it does                                                                                                                           |
| ----------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `getBillingSummary`     | `ADMIN` | Read the organization's plan, feature limits, and credit balances (skip trace, email verification, exports). Read-only — never spends. |
| `getCreditPrices`       | `READ`  | Current per-credit prices (cents/unit) for skip trace, property export, and email verification — live from Stripe.                     |
| `getCreditsPurchaseUrl` | `READ`  | The in-app Billing → Credits page URL where a **human** buys more credits.                                                             |

<Note>
  **The API never purchases**

  There is no operation that buys credits or changes your plan. When a balance
  is low, send the user the URL from `getCreditsPurchaseUrl` — purchasing
  always happens in the app, by a person.
</Note>

<Warning>
  **Which operations spend credits?**

  Credit-spending operations require the `ADMIN` scope and are flagged on
  their own pages: `enrichContact` and `createContactFromProperty`
  ([Contacts API](/developer-api/contacts)), `skipTraceProperty` and
  `manualSkiptrace` ([Properties API](/developer-api/properties)).
  Each consumes one skip-trace credit.
</Warning>

<Note>
  **Scope-gated, org-scoped by your key**

  Billing operations take no cross-org ids, so there is no `403 forbidden` here —
  every read is automatically scoped to your organization by the key.
  `getBillingSummary` requires the `ADMIN` scope; the rest are `READ`. See
  [Authorization](/developer-api/authorization) for the model.
</Note>

## Example

Check the skip-trace balance before a batch enrichment:

```bash theme={null}
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](/developer-api/overview#discovering-operations).