API reference

Billing and usage

The church's plan, allowances and usage this cycle.

GET/v1/billing

Read the plan and usage#

Returns the church's standing, plan, what the plan allows (entitlements) and how much has been used this billing cycle (usage). Use it to show remaining allowance in your own screens, or to find out why a call answered quota_exceeded. Partner keys read a customer church by sending X-Folio-Church.

Auth. A church API key. Needs the billing:read scope, or a wildcard that includes it (machine:read, machine:*, * on a partner key). A partner key can call it for a customer church by sending X-Folio-Church.

Limits. Responses carry RateLimit-Limit and RateLimit-Remaining; a 429 carries Retry-After.

Auth: Church API key
Scope: billing:read
Operation id: machineGetBilling

Parameters

Parameters
Name	In	Description
`X-Folio-Church`	header	Partner keys only: run this call as one of your customer churches (its org_ id or slug). The church must be one of yours, the key must be allowed to act for it, and plan checks run against that church. (string, e.g. org_0192f7a8-3b1c-7d2e-9a40-5c6d7e8f9012)

Responses

Response data fields
Field	Type	Description
`cycle` required	`object`
`end` required	`string (date-time)`	When the billing cycle ends.
`start` required	`string (date-time)`	When the billing cycle starts.
`entitlements` required	`object[]`	What the plan allows.
`object` required	`string`	The object type.
`plan` required	`object`
`key` required	`string`	The key.
`name` required	`string`	The name.
`version` required	`integer (int32)`	The version.
`standing` required	`object`
`converts` required	`boolean`	True when a trial will start a paid plan on its end date because a card is on file.
`days_left` required	`integer (int64)`	Whole days left, rounded up. Zero once it has ended.
`ends_at` required	`string (date-time)`	When the trial or pilot ends, or ended.
`expired_reason`	`string`	Why access ended: payment_failed after unpaid invoices ran out of grace, trial_ended for a trial or pilot, gift_ended for a gift. Empty unless the state is expired.
`grace_ends_at`	`string (date-time)`	When a past-due church becomes read-only, or when it did. Set while past_due and after a payment_failed expiry.
`has_card` required	`boolean`	Whether a card is on file.
`kind` required	`string`	Whether the access that is running, or ended, was a trial or a pilot. Empty on a paid plan.
`plan_name` required	`string`	The plan whose allowances apply, or were applying when the trial ended.
`read_only` required	`boolean`	True when new recordings, drafting, Ask and email sends are paused.
`state` required	`enum: trial \| pilot \| paid \| past_due \| expired \| none`	Where the church stands: a trial, pilot access, a paid plan, a payment to fix, an ended trial that is read-only, or nothing yet.
`usage` required	`object[]`	Token usage. Always zero.

200 Success. Read the plan and usage.

200 example

{
  "status": true,
  "message": "billing",
  "data": {
    "object": "billing",
    "standing": {
      "state": "active",
      "reason": ""
    },
    "plan": null,
    "entitlements": [],
    "usage": [],
    "cycle": {
      "start": "2026-11-01T00:00:00Z",
      "end": "2026-12-01T00:00:00Z"
    }
  }
}

400 The request could not be read.

400 example

{
  "status": false,
  "message": "the page cursor is not valid",
  "error": {
    "code": "invalid_argument",
    "status": 400,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

401 The key or session is missing, invalid or expired.

401 example

{
  "status": false,
  "message": "That API key is not valid or has expired.",
  "error": {
    "code": "unauthenticated",
    "status": 401,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

403 The credential lacks the scope, the church is suspended, the feature is not in the plan, or the address is not allowed.

403 example

{
  "status": false,
  "message": "That API key does not have the required scope.",
  "error": {
    "code": "permission_denied",
    "status": 403,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

404 The resource is not in this church.

404 example

{
  "status": false,
  "message": "That item is not in this church.",
  "error": {
    "code": "not_found",
    "status": 404,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

409 Conflict, including a duplicate Idempotency-Key still being processed.

409 example

{
  "status": false,
  "message": "A request with this Idempotency-Key is still running.",
  "error": {
    "code": "conflict",
    "status": 409,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

422 A field failed validation, or an Idempotency-Key was reused with a different body.

422 example

{
  "status": false,
  "message": "A field is not valid.",
  "error": {
    "code": "validation",
    "status": 422,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

429 Rate limited. Wait Retry-After seconds.

429 example

{
  "status": false,
  "message": "Too many requests. Wait before trying again.",
  "error": {
    "code": "rate_limited",
    "status": 429,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

500 Something went wrong. Quote error.request_id.

500 example

{
  "status": false,
  "message": "Something went wrong. Quote the request id to support.",
  "error": {
    "code": "internal",
    "status": 500,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d"
  }
}

Code samples

curl -X GET "$FOLIO_API_URL/v1/billing" \
  -H "Authorization: Bearer $FOLIO_API_KEY"

GET/v1/billing/plans

List plans#

Lists the plans the church can choose, with prices per interval and currency and the allowances each plan carries. Prices change; read them from here or from GET /v1/public/plans instead of copying them.