Billing and credits
API version 2026-10-virile-dragon
Two ways to pay
A client is billed in one of two ways, and its mode is fixed when it is created. An allowance client spends its owner's plan allowance, the same allowance as your apps, and never charges a card. A metered client spends no allowance: each of its calls costs credits, charged to the card on your usage-billing subscription. A call an app makes for another user, with a token from an authorization code, always spends that user's allowance, whatever the client's mode.
Credits per call
A metered client's call costs the credits its scope is worth, listed in the table below; a scope worth 0 credits costs nothing. The units that GET /v1/usage reports convert to credits at these weights. A call is billed at the weights in force on the day it is made, whatever version the client is pinned to: the table in an older version's reference records the weights when that version was published, not what a call costs today.
vocab:generate | Generate vocabulary lists. | Generate a vocabulary list |
lesson_plans:read | Read your lesson plans and reconnect to their progress. | Get a lesson planReconnect to a lesson plan |
lesson_plans:write | Create lesson plans. | Create a lesson plan |
tutor:converse | Hold tutor conversations. Requires a paid plan. | Send a tutor turn |
usage:read | See your remaining allowance, or a `metered` client's usage this month. | Get your remaining allowance |
events:read | Read events about your account, and register endpoints that receive them. | List eventsStream events |
events:write | Send events from your game or integration to Lingara. | Send an event |
embed:mint | Mint short-lived tokens for your game's or site's players, and delete players. Metered clients only. | Mint a token for a playerDelete a playerUnlink a player from their Lingara account |
embed:play | Act for a player: send their practice results and hold NPC conversations with them. | Link a player to their Lingara accountSend a line to an NPC |
The price
One credit costs US$0.004. Usage is billed monthly, for each calendar month starting on the 1st (UTC), to the card on your usage-billing subscription.
Spending limits
Your account has a monthly limit in credits, and each metered client can have a lower limit of its own; set both on the Integrations page. Once the client or your account reaches its limit, the client's calls are refused with 402 and the code spend_cap_reached until the next month begins or the limit is raised.
When usage billing is not active
A metered client's calls are refused with 402 and the code metered_billing_inactive while usage billing is not active: before it is set up, while a payment is overdue, and after it is cancelled. Set up, manage or cancel usage billing on the Integrations page, at app.getlingara.com/admin. Managing it opens Stripe's billing portal, where you can change your card and read your invoices.