API

Plan and billing

What the plan allows, the credit balance and its history, usage, invoices and saved cards.

plan.get lists every plan feature: switches that are on or off, limits the workspace uses up (seats, publishedDocuments, storageBytes) and allowances. A route needing a switch that is off, or a request that would pass a limit, answers 402 plan_required, its details naming the feature and the least plan that has it. Any member or key may call plan.get and plan.list; the rest need billing.read, which Owners and Accounts members have.

Credits pay for metered work: text recognition, heavier exports, batches of QR codes, exports through the API, and views over the monthly allowance. The plan grants credits each calendar month, which expire when it ends; packs bought last 12 months. A debit is never refused: the balance can go below zero, but once it is overdrawn by more than a month of the plan's credits the workspace is throttled, and new metered work answers 402 credits_required.

Subscriptions, checkout and card changes go through Stripe in the workspace; the API only reads them. Invoices and payment methods are read from Stripe on each call. Money amounts are in the currency's smallest unit (cents).

The plan and subscription

GET /billing billing.get

The plan in force, the Stripe subscription behind it, any subscription payment Stripe could not collect, the free trial's state, and publications a trial's end took down. It is read fresh on every call. The plan is bought and changed through Stripe Checkout and the customer portal in the admin app, not through the public API.

Scopes
billing.read

Response

200 OK. A JSON object:

Response fields (36)
NameTypeDescription
plan string The id of the plan in force now, such as free or pro, a running trial's plan included. Matches ^[a-z][a-z0-9]{1,32}$.
subscription object The Stripe subscription that gives the plan; null when there is none, as on the free plan, during a trial, or on a plan Flipbird gave. Can be null.
subscription.plan string The plan the subscription is for. Matches ^[a-z][a-z0-9]{1,32}$.
subscription.interval string How often it is billed: month or year. One of month, year.
subscription.seats number Seats in all: those the plan includes plus extraSeats.
subscription.extraSeats number Seats bought beyond those the plan includes.
subscription.status string Stripe's status for the subscription: active, trialing, or past_due while Stripe retries a payment that failed.
subscription.currentPeriodEnd number When the current billing period ends, in epoch milliseconds; null when Stripe has not said. Can be null.
subscription.cancelAtPeriodEnd boolean Whether the subscription ends at currentPeriodEnd instead of renewing.
hasBillingAccount boolean Whether the workspace has a Stripe customer yet. Until it has, invoices and payment methods are empty.
paymentIssue object A subscription payment Stripe could not collect; null when there is none. Can be null.
paymentIssue.status string past_due: Stripe is retrying the payment, and the plan stays meanwhile. unpaid: Stripe has stopped retrying, and the plan's paid features are off until the invoice is paid. One of past_due, unpaid.
paymentIssue.plan string The plan of the subscription that could not be paid for. Matches ^[a-z][a-z0-9]{1,32}$.
paymentIssue.amountDue number The unpaid invoice's amount due, in the currency's smallest unit (cents); null when no failed payment is on record. Can be null.
paymentIssue.currency string The invoice's currency, as Stripe's lower-case code such as usd; null when no failed payment is on record. Can be null.
paymentIssue.failedAt number When the latest attempt to pay failed, in epoch milliseconds; null when no failed payment is on record. Can be null.
paymentIssue.nextAttemptAt number When Stripe will try again, in epoch milliseconds; null when it has no retry scheduled or none is known. Can be null.
paymentIssue.attempts number Attempts to pay so far; null when no failed payment is on record. Can be null.
trial object The free trial, by status: running (active), on offer (available), had (used) or not on offer (unavailable). One of 4 shapes, chosen by status.
trial.status string active: the trial is running. One of active, available, used, unavailable.
trial.plan string The plan the trial gives. Only when status is active. Matches ^[a-z][a-z0-9]{1,32}$.
trial.endsAt number When the trial ends, in epoch milliseconds. Only when status is active.
trial.daysLeft number Whole days left, rounded up. Only when status is active.
trial.plan string The plan a trial would give. Only when status is available. Matches ^[a-z][a-z0-9]{1,32}$.
trial.days number How many days a trial would last. Only when status is available.
trial.plan string The plan the trial gave. Only when status is used. Matches ^[a-z][a-z0-9]{1,32}$.
trial.endedAt number When the trial ended, in epoch milliseconds. Only when status is used.
trial.reason string Why it ended: expired (it ran its course), converted (a subscription began) or staff (Flipbird staff ended it). Only when status is used. One of expired, converted, staff.
trial.plan string The plan a trial gives. Only when status is unavailable. Matches ^[a-z][a-z0-9]{1,32}$.
paused object Publications a free trial's end took down in the last 90 days and not yet put back; null when none are waiting. Can be null.
paused.total number How many publications are waiting to be put back.
paused.pausedAt number When the latest of them was taken down, in epoch milliseconds.
paused.until number When the first of them stops being offered for republishing, in epoch milliseconds: 90 days after it was taken down.
paused.visible array of objects Those the caller may see, at most 200.
paused.visible[].documentId string The document's id.
paused.visible[].title string The document's title.

Example request

curl https://api.flipbird.io/api/v1/billing \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "plan": "string",
  "subscription": {
    "plan": "string",
    "interval": "month",
    "seats": 1,
    "extraSeats": 1,
    "status": "string",
    "currentPeriodEnd": 1,
    "cancelAtPeriodEnd": true
  },
  "hasBillingAccount": true,
  "paymentIssue": {
    "status": "past_due",
    "plan": "string",
    "amountDue": 1,
    "currency": "string",
    "failedAt": 1767225600000,
    "nextAttemptAt": 1767225600000,
    "attempts": 1
  },
  "trial": {
    "status": "active",
    "plan": "string",
    "endsAt": 1767225600000,
    "daysLeft": 1
  },
  "paused": {
    "total": 1,
    "pausedAt": 1767225600000,
    "until": 1,
    "visible": [
      {
        "documentId": "…",
        "title": "Spring catalogue"
      }
    ]
  }
}

Auto top-up settings

GET /billing/credits/auto-top-up billing.autoTopUp.get

While auto top-up is on, a debit that leaves the credit balance below threshold buys pack again, charging the default card (else the card saved most recently), at most monthlyCap times a calendar month. A card decline that retrying cannot fix switches it off and sets disabledReason. Settings never saved read as off, with no pack and zeros. They are changed in the admin app.

Scopes
billing.read

Response

200 OK. A JSON object:

Response fields (6)
NameTypeDescription
enabled boolean Whether auto top-up is on.
pack string The credit pack a top-up buys: small, medium or large; null when none is chosen. One of small, medium, large. Can be null.
threshold integer A top-up starts when a debit leaves the credit balance below this many credits. 0 to 10,000,000.
monthlyCap integer The most top-ups in one calendar month (UTC). 0 to 31.
updatedAt number When the settings were last saved, in epoch milliseconds; null if they never have been. Can be null.
disabledReason string Why a card decline switched auto top-up off, as Stripe's decline or error code; null otherwise. Saving the settings clears it. Can be null.

Example request

curl https://api.flipbird.io/api/v1/billing/credits/auto-top-up \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "enabled": true,
  "pack": "small",
  "threshold": 1,
  "monthlyCap": 1,
  "updatedAt": 1767225600000,
  "disabledReason": "string"
}

What this workspace's plan allows

GET /plan plan.get

Every plan feature with its state: switches with the least plan that turns them on, limits with what is used and the next plan with more, and allowances. The figures are those in force for this workspace: a running trial's plan, seats bought, and any arrangement with Flipbird included.

A route that needs a switch that is off answers 402 plan_required, its details naming the feature and the requiredPlan; a request that would pass a limit answers 402 plan_required too. Also gives the credit standing (never the balance, which billing.credits.get gives) and the feature flags that are on. Any member or key may call it.

Scopes
None: any credential may call it
MCP tool
plan_get

Response

200 OK. A JSON object:

Response fields (6)
NameTypeDescription
plan string The id of the plan in force, such as free or pro, a running trial's plan included. Matches ^[a-z][a-z0-9]{1,32}$.
features map of objects Every plan feature, by name. Switches (kind switch): saml, SAML single sign-on may be set up and used; clientSideEditing, the editor may run in the browser against a local PDF file; customDomain, a publication may be served on a hostname the workspace owns; customSubdomain, the workspace may choose its own address on flipbird.io; analytics, opens, page turns and link hits in publications are recorded and readable (the document and workspace analytics routes need it); pdfSigning, the editor may sign a PDF with a certificate; eSignatures, members may sign documents and send signing requests to people outside the workspace (signatures.sign and signatures.requests.create need it); apiAccess, API keys may be made and used (without it every request with an API key answers 402 plan_required); mcpAccess, the MCP endpoint may be used; qrTracking, QR code scans and short-link clicks are recorded and readable while the workspace also leaves tracking on (analytics.qr and analytics.links need it); removeBranding, the hosted viewer shows no Flipbird name or art, and its password, error and other pages around a publication take the workspace's look and logo; leadCapture, a publication may ask readers for their details (leads.formSet needs it); whiteLabel, on top of removeBranding, nothing a reader sees names Flipbird: page titles and link previews carry the workspace's name, and its verified hostname is the canonical address; auditExport, the audit log may be exported (audit.export and audit.range need it); collections, bookshelves may be made, changed and shown (collections.create, collections.update, collections.setItems and collections.publish need it); enrichment, hotspots, buttons, videos and galleries over a publication's pages may be saved and are shown (enrichment.set needs it). Limits (kind limit): seats, active members plus pending invites, deactivated members not counted (an invite past it is refused); publishedDocuments, publications live at once (publishing past it is refused); storageBytes, bytes stored, counting document versions, the trash, uploads in progress, fonts and images (an upload past it is refused; nothing stored is removed). Allowances (kind allowance): monthlyViews, publication views included each calendar month, after which views are charged in credits (the viewer is never refused); monthlyCredits, credits granted each calendar month, which expire when the month ends; trashRetentionDays, days a trashed document or version can still be restored before it is deleted for good.
credits object The credit standing.
credits.standing string How the credit balance stands: ok; low, below a fifth of the plan's monthly credits; empty, at or below zero and running into overdraft; or throttled, overdrawn by more than a month of the plan's credits (at least 100), when metered work is refused. One of ok, low, empty, throttled.
credits.throttled array of strings The metered work refused with 402 credits_required while throttled: ocr (text recognition), heavy_render (heavier exports: large or long documents, high resolutions and some export types), qr_batch (batches of QR codes) and api_export (exports through the API). Empty unless standing is throttled. Viewing, publishing and editing are never refused for credits.
flags map of booleans Feature flags Flipbird has turned on for this workspace or its plan, by name, each true. A flag that is off is not listed.

Example request

curl https://api.flipbird.io/api/v1/plan \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "plan": "string",
  "features": {},
  "credits": {
    "standing": "ok",
    "throttled": [
      "ocr"
    ]
  },
  "flags": {}
}

Every plan and what it includes

GET /plans plan.list

Every plan on sale, in the order the pricing page shows them, and the workspace's own plan even when it is no longer offered (its archived is then true), with each plan's features, how Checkout sells it and its prices. The features are the plan's own, without seats bought or any arrangement this workspace has; plan.get gives those. Any member or key may call it.

Scopes
None: any credential may call it

Response

200 OK. A JSON object:

Response fields (15)
NameTypeDescription
plans array of objects The plans, in the order the pricing page shows them.
plans[].id string The plan's id, such as pro. Matches ^[a-z][a-z0-9]{1,32}$.
plans[].name string The plan's name.
plans[].features map of numbers or booleans The plan's features by name, as plan.get explains them: a switch is true or false; a limit or allowance is a number.
plans[].selfServe boolean Whether it is sold through Checkout; when false it is arranged with Flipbird's sales team.
plans[].archived boolean True only for this workspace's own plan when that plan is no longer offered.
plans[].intervals array of strings The billing intervals, month and year, Checkout can sell it for; empty when it is not self-serve.
plans[].price object Its list prices; null for a plan arranged with sales. Can be null.
plans[].price.currency string Stripe's lower-case currency code, such as usd.
plans[].price.month number The plan for a month, billed monthly, in cents; null when it is not sold monthly. Can be null.
plans[].price.year number The plan for a year, billed yearly, in cents; null when it is not sold yearly. Can be null.
plans[].price.seatMonth number One seat beyond those included, for a month, in cents; null when extra seats are not sold monthly. Can be null.
plans[].price.seatYear number One seat beyond those included, for a year, in cents; null when extra seats are not sold yearly. Can be null.
plans[].seatIntervals array of strings The billing intervals for which extra seats can be bought.
plans[].sunsetAt number When the plan stops being sold, in epoch milliseconds, if Flipbird has scheduled that; null otherwise. A workspace already on it keeps it. Can be null.

Example request

curl https://api.flipbird.io/api/v1/plans \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "plans": [
    {
      "id": "string",
      "name": "Spring catalogue",
      "features": {},
      "selfServe": true,
      "archived": true,
      "intervals": [
        "month"
      ],
      "price": {
        "currency": "string",
        "month": 1,
        "year": 1,
        "seatMonth": 1,
        "seatYear": 1
      },
      "seatIntervals": [
        "month"
      ],
      "sunsetAt": 1767225600000
    }
  ]
}

The credit balance and the lots it is made of

GET /billing/credits billing.credits.get

Credits pay for metered work: OCR, heavier exports, batches of QR codes, exports through the API, and views over the plan's monthly allowance. They come in lots, such as the plan's monthly credits, which expire when the month ends, and packs bought, which last twelve months. A debit draws on the lots soonest-expiring first, the order they are listed in.

A debit is never refused for want of credits: past zero it is overdraft, which the next credits added pay off first. Overdrawn by more than a month of the plan's credits, the workspace is throttled and new metered work answers 402 credits_required.

Scopes
billing.read
MCP tool
billing_credits_get

Response

200 OK. A JSON object:

Response fields (6)
NameTypeDescription
balance number Credits available now. Negative while overdrawn.
overdraft number Credits drawn past zero and not yet paid off; 0 when there is none.
standing string How the balance stands: ok; low, below a fifth of the plan's monthly credits; empty, at or below zero; or throttled, overdrawn by more than a month of the plan's credits (at least 100), when metered work is refused. One of ok, low, empty, throttled.
lots array of objects The lots with credits left, soonest-expiring first: the order debits draw on them.
lots[].remaining number Credits left in the lot.
lots[].expiresAt number When what is left of the lot expires, in epoch milliseconds.

Example request

curl https://api.flipbird.io/api/v1/billing/credits \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "balance": 1,
  "overdraft": 1,
  "standing": "ok",
  "lots": [
    {
      "remaining": 1,
      "expiresAt": 1767225600000
    }
  ]
}

Credit grants, purchases, debits and expiries, newest first

GET /billing/credits/history billing.credits.history

One entry per change to the credit balance, newest first. For the next page, pass nextCursor as cursor.

Scopes
billing.read

Query parameters

NameTypeDescription
cursor string nextCursor from the previous page, to read the next one. Matches ^\d{1,16}(\.[A-Za-z0-9_-]{1,64}){1,2}$.
before integer The older way to page: only entries made before this time, in epoch milliseconds. It skips entries that share the last one's createdAt; use cursor. Ignored when cursor is given. More than 0.
limit integer Most entries to return. Default 50. 1 to 200.

Response

200 OK. A JSON object:

Response fields (7)
NameTypeDescription
entries array of objects The entries, newest first.
entries[].kind string What the entry is: grant (the monthly allowance, a trial's credits, or credits Flipbird gave), purchase (credits bought), debit (credits used or taken back) or expiry (credits that ran out unused). One of grant, purchase, debit, expiry, settle.
entries[].amount number The change to the balance, in credits: positive for a grant or purchase, negative for a debit or expiry.
entries[].reason string What it was for, as a short lowercase word, such as allowance, trial, job (OCR or an export rendered as a job, named in jobId), qr_batch, views (views over the monthly allowance), api_export, refund or expiry.
entries[].jobId string The job a job debit paid for; null otherwise. Can be null.
entries[].createdAt number When it happened, in epoch milliseconds.
nextCursor string Pass as cursor to read the next page. Null when this page is not full; a full page may be followed by an empty one. Can be null.

Example request

curl https://api.flipbird.io/api/v1/billing/credits/history \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "entries": [
    {
      "kind": "grant",
      "amount": 1,
      "reason": "string",
      "jobId": "…",
      "createdAt": 1767225600000
    }
  ],
  "nextCursor": "string"
}

Invoices, newest first, read from Stripe

GET /billing/invoices billing.invoices

The workspace's Stripe invoices, newest first, 20 at a time, read from Stripe on each call. While hasMore is true, pass the last invoice's id as after for the next page. A workspace with no Stripe customer yet gets an empty list. When Stripe refuses the request the call answers 502 billing_unavailable; where billing is not set up, 503 billing_not_configured.

Scopes
billing.read

Query parameters

NameTypeDescription
after string The id of the last invoice on the previous page, to list the ones after it. Omit it for the first page. Matches ^in_[A-Za-z0-9]+$.

Response

200 OK. A JSON object:

Response fields (13)
NameTypeDescription
invoices array of objects Up to 20 invoices, newest first.
invoices[].id string Stripe's invoice id, in_ and more.
invoices[].number string The invoice number; null until Stripe finalises the invoice. Can be null.
invoices[].status string Stripe's status for the invoice, such as open, paid or void; null when it gives none. Can be null.
invoices[].total number The invoice's total, in the currency's smallest unit (cents).
invoices[].amountPaid number How much of it has been paid, in the currency's smallest unit (cents).
invoices[].currency string Stripe's lower-case currency code, such as usd.
invoices[].createdAt number When Stripe made the invoice, in epoch milliseconds.
invoices[].periodStart number The start of the period the invoice covers, in epoch milliseconds; null when Stripe gives none. Can be null.
invoices[].periodEnd number The end of the period the invoice covers, in epoch milliseconds; null when Stripe gives none. Can be null.
invoices[].hostedUrl string Stripe's page for the invoice, where it can be viewed and paid; null when there is none. Can be null.
invoices[].pdfUrl string A link to download the invoice as a PDF; null when there is none. Can be null.
hasMore boolean Whether older invoices follow: pass the last id as after to read them.

Example request

curl https://api.flipbird.io/api/v1/billing/invoices \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "invoices": [
    {
      "id": "string",
      "number": "string",
      "status": "string",
      "total": 1,
      "amountPaid": 1,
      "currency": "string",
      "createdAt": 1767225600000,
      "periodStart": 1,
      "periodEnd": 1,
      "hostedUrl": "https://example.com/privacy",
      "pdfUrl": "https://example.com/privacy"
    }
  ],
  "hasMore": true
}

Saved cards, read from Stripe

GET /billing/payment-methods billing.paymentMethods

Up to 20 payment methods saved with Stripe for the workspace, read from Stripe on each call. Cards are added, removed and made the default in the customer portal. A workspace with no Stripe customer yet gets an empty list. When Stripe refuses the request the call answers 502 billing_unavailable; where billing is not set up, 503 billing_not_configured.

Scopes
billing.read

Response

200 OK. A JSON object:

Response fields (7)
NameTypeDescription
paymentMethods array of objects The saved payment methods.
paymentMethods[].id string Stripe's payment method id, pm_ and more.
paymentMethods[].brand string The card's brand, as Stripe names it, such as visa; null when it is not a card. Can be null.
paymentMethods[].last4 string The last four digits of the card number; null when it is not a card. Can be null.
paymentMethods[].expMonth number The month the card expires, 1 to 12; null when it is not a card. Can be null.
paymentMethods[].expYear number The year the card expires, four digits; null when it is not a card. Can be null.
paymentMethods[].isDefault boolean Whether it is the default payment method chosen in the customer portal.

Example request

curl https://api.flipbird.io/api/v1/billing/payment-methods \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "paymentMethods": [
    {
      "id": "string",
      "brand": "string",
      "last4": "string",
      "expMonth": 1,
      "expYear": 1,
      "isDefault": true
    }
  ]
}

A month's usage: seats, published documents and credits

GET /billing/usage billing.usage

The credits a calendar month (UTC) granted, bought, lost and used, and the seats and published documents in use against the plan's limits. Seats and published documents are as of now, whichever month is asked for.

Scopes
billing.read
MCP tool
billing_usage

Query parameters

NameTypeDescription
month string The calendar month, as YYYY-MM in UTC. Default this month. Matches ^\d{4}-(0[1-9]|1[0-2])$.

Response

200 OK. A JSON object:

Response fields (14)
NameTypeDescription
month string The month reported, as YYYY-MM.
plan string The id of the plan in force now. Matches ^[a-z][a-z0-9]{1,32}$.
seats object Seats taken now (active members and pending invites), and the plan's seats, those bought included.
seats.used number How many are in use now.
seats.limit number How many the workspace may have now.
publishedDocuments object Publications live now, and how many the plan allows at once.
publishedDocuments.used number How many are in use now.
publishedDocuments.limit number How many the workspace may have now.
credits object The month's credit movements, in credits.
credits.granted number Credits granted in the month: the monthly allowance, a trial's credits, or credits Flipbird gave.
credits.purchased number Credits bought in the month.
credits.expired number Credits that expired unused in the month.
credits.refunded number Credits taken back because their purchase was refunded, less any put back when such a refund failed. It can be negative in a month that only put back an earlier month's.
credits.debited map of numbers Credits used in the month, by reason, such as job (OCR and exports rendered as jobs), qr_batch, views (views over the monthly allowance) and api_export.

Example request

curl https://api.flipbird.io/api/v1/billing/usage \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "month": "string",
  "plan": "string",
  "seats": {
    "used": 1,
    "limit": 1
  },
  "publishedDocuments": {
    "used": 1,
    "limit": 1
  },
  "credits": {
    "granted": 1,
    "purchased": 1,
    "expired": 1,
    "refunded": 1,
    "debited": {}
  }
}

What the workspace stores, by kind, against its plan's storage

GET /storage storage.get

Plaintext bytes from what the database records. Categories with no recorded size (derived files such as thumbnails, tiles and exports, and editing drafts) are listed with bytes null and are not counted. Over the limit, uploads are refused (402) and nothing stored is removed.

Scopes
None: any credential may call it
MCP tool
storage_get

Response

200 OK. A JSON object:

Response fields (11)
NameTypeDescription
plan string The id of the workspace's plan. Matches ^[a-z][a-z0-9]{1,32}$.
limitBytes number The plan's storage limit in bytes, with any override the workspace has.
usedBytes number The bytes counted against the limit: the sum of the categories with counted true.
nextPlan string The least plan with more storage, for an upgrade prompt, or null when there is none. One of free, starter, pro, business, enterprise. Can be null.
categories array of objects What the workspace stores, by category, in a fixed order.
categories[].id string The category: documents, trash, uploadsInProgress, originals, svgOriginals, images, videos, assetPreviews, fonts, derived or drafts.
categories[].label string The category's name, for display.
categories[].bytes number The bytes it holds, or null when it is not measured. Can be null.
categories[].count number How many files or objects it holds, or null when it is not measured. Can be null.
categories[].counted boolean Whether it counts toward the plan's storage limit.
categories[].description string What the category holds, for display.

Example request

curl https://api.flipbird.io/api/v1/storage \
  -H "Authorization: Bearer $FLIPBIRD_API_KEY"
Example response
{
  "plan": "string",
  "limitBytes": 1,
  "usedBytes": 1,
  "nextPlan": "free",
  "categories": [
    {
      "id": "string",
      "label": "Spring campaign",
      "bytes": 1,
      "count": 1,
      "counted": true,
      "description": "Our spring range."
    }
  ]
}

Errors

Besides the errors any endpoint can answer, these endpoints answer:

StatusCodeWhen
400bad_cursorThe cursor was not given by this list.
502billing_unavailableStripe refused the call.
503billing_not_configuredBilling is not set up here yet.