> ## Documentation Index > Fetch the complete documentation index at: https://widgetic.com/llms.txt > Use this file to discover all available pages before exploring further. # Credits & Billing > How invoices, AI credits and storage work for a partner account You pay Widgetic **by invoice**, and you spend **credits** on Widgetic's AI. Your credits live in **one account**: the account of the person who administers your partner record, which is the account behind your API key. There is nothing else to create or to fund: no second account, and no separate balance for the partner. Creating compositions, changing their content or design, uploading files and showing a widget to visitors never spend credits. ## Overview 1. **Agree your terms** with Widgetic. Your contract sets the billing cycle, the credits you get in each billing period, your price for a credit and the dates. Read it with `GET /partners/{partnerId}/contract`. 2. **Pay the invoices.** For each billing period Widgetic issues an invoice by itself, for the credits of that period at your price for a credit, with the tax that applies to you. Stripe emails it to your billing contact, and you pay it on the invoice page within the number of days printed on it (7 unless you agreed another number). Nothing is charged automatically. You pay from the first day: a partner has no trial. 3. **Get your credits.** Paying an invoice adds its credits to your account, once. Each generation by Widgetic's AI uses 1 credit. When the credits of a period are used up, you can buy extra credits yourself with one API call (see [Getting More Credits](#getting-more-credits)). 4. **Pay on time.** An invoice of your contract that is still unpaid after its due date stops your partner account until it is paid (see [When an Invoice Is Not Paid](#when-an-invoice-is-not-paid)). 5. **Monitor** your balance, your spending and your invoices in your [dashboard](https://widgetic.com/docs/partners/dashboard.md), with the calls below, or let [notifications](https://widgetic.com/docs/partners/notifications.md) tell you when an invoice is issued, due, overdue or paid, and when your credits run low. The examples on this page are for your server. Keep the key in an environment variable, such as `WIDGETIC_PARTNER_KEY`, and never put it in a browser. ## What a Credit Costs One AI generation uses **1 credit**. Credits are whole numbers. The list price of a credit is **\$0.10**, and that is what you pay for [extra credits](#getting-more-credits). Your contract can set a price of its own for the credits of its billing periods. In the contract, `creditPriceUsd` is that price and `effectiveCreditPriceUsd` is what one credit costs you in the end: the agreed price, or the list price when none was agreed. > [!NOTE] > > The list price is today's, and the price in your contract can differ from it. Ask Widgetic for the figures that apply to you. ## What Spends Credits * Creating or revising a widget with Widgetic's AI, in the dashboard or with Widgetic's MCP tools: **1 credit per generation**. Each time the AI writes or rewrites a widget counts as one generation. Building the finished widget costs nothing extra. * A call to Widgetic's AI proxy made with your key: **1 credit**. **What does not spend credits:** creating, changing, duplicating or deleting compositions; reading or writing content, design and embed settings; making, publishing or pausing workflows (see [Limits and cost](https://widgetic.com/docs/partners/workflows.md#limits-and-cost)) and showing them to visitors; managed users; uploads; and showing a widget to visitors, however often. There is no charge per API call: a partner key has a rate limit instead (see [Usage Limits](https://widgetic.com/api-reference/usage-limits.md)). Storage is not paid in credits either. See [Storage](#storage). ## Checking Your Balance Credits are counted per account. Your key's account is the one that administers your partner record, and its id is `userId` in the answer to the key check: ```bash theme={null} curl -sS -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \ "https://api.widgetic.com/v1/tokens/validate" ``` Keep `data.userId` as `WIDGETIC_ACCOUNT_ID`, then read the balance: ```bash theme={null} curl -sS -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \ "https://api.widgetic.com/v1/credits/user/$WIDGETIC_ACCOUNT_ID/balance" ``` ```json theme={null} { "success": true, "data": { "id": "", "userId": "", "balance": 1500, "reservedBalance": 0, "lastUpdated": "2026-10-01T09:00:00.000Z" } } ``` The values above are an illustration, not real figures. Credits reserved for an operation that is still running cannot be spent, so what a new operation can use is `balance - reservedBalance`. An account that has never held credits reads a balance of 0. > [!NOTE] > > `GET /partners/{partnerId}/credits/balance` and `GET /partners/{partnerId}/credits/transactions` read this same account and answer with the same figures, so use whichever is handier. In the TypeScript SDK (`@widgetic/api-sdk-ts`) the two account credit calls are `CreditsApi.getUserCreditBalance` and `CreditsApi.getUserCreditTransactions`. ## Credits on Your Account The credits your contract includes arrive when you **pay the invoice** of each billing period, and they **end with that period**: what is left of them is taken off your account on the day the period ends, and your [spending history](#spending-history) shows an `expiration` entry for it. Credits that are left over are not carried into the next period. [Extra credits](#getting-more-credits) are never taken back. An invoice that is paid on or after the day its period ends adds no credits, because they could not be used. If that happens to you, contact Widgetic and a person will settle it. When credits run out, an AI action is refused with `402` and the code `BILLING_INSUFFICIENT_CREDITS`. Nothing else stops because of it. You are warned before that happens. When what you can spend falls below 500 credits, you get a `credits.low` [notification](https://widgetic.com/docs/partners/notifications.md) with `band` set to `low`, and another with `band` set to `empty` when nothing is left. A balance that stays low reminds you once a week, not more. The warning level is the same for every partner, and the notification says what it was (`threshold`). ## Getting More Credits When the credits of a period are used up, buy extra credits yourself with `POST /partners/{partnerId}/credits/extra-invoice`. The body has one number, `usd`: the dollars you want to spend, from 10 to 100,000 in one request, to the cent. You are invoiced for the most whole credits that money buys at the **list price** of a credit (\$0.10), whatever price your contract has, so the invoice is never for more than you asked: 12.34 dollars buys 123 credits and the invoice says 12.30. For more than 100,000 dollars in one go, ask Widgetic for an invoice. ```bash theme={null} # One key for each purchase you mean to make. Send the same key again to retry it. PURCHASE_KEY="$(uuidgen)" curl -sS -X POST \ -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $PURCHASE_KEY" \ -d '{"usd":250}' \ "https://api.widgetic.com/v1/partners/$WIDGETIC_PARTNER_ID/credits/extra-invoice" ``` In the answer, `data` is the invoice: `invoiceId`, `number`, `hostedInvoiceUrl` (the page where you pay it), `pdfUrl`, `credits`, `creditPriceUsd`, `amountUsd` (before tax), `taxUsd`, `totalUsd` (what you pay), `currency`, `dueDate` and `dueDays`. It is an ordinary invoice: Stripe emails it, you pay it on the invoice page as described below, and the credits are added to your account balance **once, when the invoice is paid**. Nothing is added while it is open. * **Extra credits never expire**, unlike the credits of a billing period. * **An unpaid invoice for extra credits never stops your account.** Only an unpaid invoice of your contract does. * **Available to partners with an active paid contract in good payment standing:** you can buy extra credits whenever your contract is in force and you do not owe an overdue contract invoice (`422` with `NO_PAID_CONTRACT` when no paid contract is in force, or `CONTRACT_INVOICE_OVERDUE` when a contract invoice is past its due date). * **Send one `Idempotency-Key` for each purchase you mean to make**, and send the same key again to retry that purchase after a timeout: the same key with the same body returns the invoice already issued and never makes a second one. The same key with a different body is refused with `422`, and a duplicate that arrives while the first is still running with `409`. A new purchase needs a new key. * **Limits:** at most 10 requests an hour (`429` after that). A `400` with `param` set to `usd` means the amount is under 10, over 100,000 or not a number of dollars and cents. * **Who may ask:** the key of the person who administers your partner account. A key limited to scopes needs `billing:write` (see [Limit what a key can do](https://widgetic.com/docs/authentication.md#limit-what-a-key-can-do)). * **When it fails:** `503` means Stripe could not issue the invoice and nothing was sent, so send the same request again with the same key. A `422` with `NO_PAID_CONTRACT`, `CONTRACT_INVOICE_OVERDUE`, `NO_BILLING_EMAIL`, `TAX_ID_INVALID` or `NO_PARTNER_ADMINISTRATOR` names what must be settled or put right in your contract or billing profile before an invoice for extra credits can be issued. > [!NOTE] > > In the TypeScript SDK (`@widgetic/api-sdk-ts`) the call is `PartnersApi.createPartnerExtraCreditsInvoice`, with `partnerId`, `idempotencyKey` and `requestExtraCredits: { usd }`. In your [invoices](#read-your-invoices) the purchase reads like “5,000 Widgetic credits (extra credits, they do not expire)”. When it is paid, your spending history gets an entry whose `description` reads “Credits on partner invoice ABCD-0002 (5,000 credits)”, with the number of that invoice, so you can match the two. ## Spending History `GET /credits/user/{userId}/transactions` lists the account's credit ledger, newest first. Add `transaction_type=debit` to see only the credits spent. `limit` defaults to 100 and is at most 500, and `offset` pages through the list. ```bash theme={null} curl -sS -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \ "https://api.widgetic.com/v1/credits/user/$WIDGETIC_ACCOUNT_ID/transactions?transaction_type=debit&limit=20" ``` `data` is a list. Each entry looks like this, and `amount` is always positive, because `transactionType` says whether credits were added or taken: ```json theme={null} { "id": "", "transactionType": "debit", "amount": 1, "balanceAfter": 1499, "description": "Widget generation", "referenceId": "", "createdAt": "2026-10-01T09:30:00.000Z" } ``` The types are `debit`, `credit`, `subscription`, `refund`, `reserve`, `release`, `adjustment`, `expiration`, `transfer_out` and `transfer_in`. The list can grow, so ignore a type you do not know. Add up the `amount` of the `debit` entries over a period to get the credits used in it. ## Contract and Billing Overview `GET /partners/{partnerId}/contract` returns your contract terms. The fields are camelCase and prices are in US dollars: * `customPrice`: the agreed price for one billing cycle. `null` means the standard price applies. The invoice of a billing period is worked out from `customCredits` and the price of a credit (below), not from this field. * `billingCycle`: `monthly`, `quarterly` or `annual`. * `minimumCommitmentMonths`: how long you committed for. * `customCredits`: the AI credits included in each billing period. The invoice of a period is for these credits, and they end with the period. `null` means the standard allowance, and then nothing is invoiced by itself. * `creditPriceUsd`: the agreed price of one credit, in dollars (up to four decimal places). `null` means the list price. * `effectiveCreditPriceUsd`: what one credit costs you, in dollars: the agreed price, or the list price when none was agreed. * `periodTotalUsd`: what one billing period costs before tax, in dollars: `customCredits` times `effectiveCreditPriceUsd`, to the cent. `null` while no credits are agreed. * `additionalFeatures` and `supportSla`: the features and the support level your contract adds. * `contractStartDate` and `contractEndDate`: the dates the contract runs between. An end date of `null` means it runs until it is ended. * `isActiveContract`: `true` while the contract is in force. Your contract includes no storage: your files go to your own bucket (see [Storage](#storage)). You can read these terms but not change them: Widgetic changes them. `GET /partners/{partnerId}/billing-overview` is a quick "am I in good standing?" check of the contract: ```json theme={null} { "success": true, "data": { "partner": { "id": "", "name": "Your Company", "isActive": true, "tier": "partner" }, "partnerCustomization": { "...": "your contract, as returned by the contract call" }, "billingIntegration": { "hasPartnerPlan": true, "usesCustomPricing": true, "billingCycle": "monthly", "contractActive": true }, "operationalCredits": { "balance": 1500, "reservedBalance": 0, "availableBalance": 1500, "recentTransactions": [{ "...": "the 10 newest entries of your spending history, in the shape shown under Spending History" }] } } } ``` `operationalCredits` is your account's credits, the same figures as in [Checking Your Balance](#checking-your-balance): `balance`, `reservedBalance` and `availableBalance` (`balance` minus `reservedBalance`, never below 0), and the 10 newest entries of your [spending history](#spending-history). The figures here are an illustration, not real ones. `tier` is `partner` when you have a contract and `standard` when you do not. The overview does not show a stop for an unpaid invoice: read `standing` in the answer of `GET /partners/mine` for that (see [Account Status](https://widgetic.com/docs/partners/account-status.md)). ## How and When You Pay 1. **Widgetic issues the invoice, by itself.** It is for the credits of one billing period at your price for a credit, in US dollars, with one line such as `Widgetic credits for 2026-10-01 to 2026-12-31: 10,000 credits at $0.10 each. The credits expire when the period ends.` The first invoice is issued on the day your contract starts, and each later one seven days before the period it is for begins. The periods are counted from the start date, one billing cycle at a time. One invoice is made for a period, however often the check runs. Nothing is invoiced for a period that has already ended, nor while an invoice of your contract is overdue. Nothing is charged automatically, and there is no trial: you pay from the first day. 2. **You are told at once.** Stripe emails the invoice to the billing email of your billing profile, and Widgetic sends an `invoice.issued` [notification](https://widgetic.com/docs/partners/notifications.md) to your chosen recipients, your dashboard and your webhook. 3. **You pay on the invoice page** (`hostedInvoiceUrl`), using the payment methods that page offers. The same link is in the Billing page of your [dashboard](https://widgetic.com/docs/partners/dashboard.md). A PDF is at `pdfUrl`. If you need a way of paying that the page does not offer, such as a bank transfer, ask Widgetic: when the money arrives, Widgetic records the payment against the invoice. 4. **The due date** is the number of days printed on the invoice after it is issued. It follows the payment terms of your billing profile, which are 7 days unless you agreed another number from 1 to 120. It is in `dueDate`. With the default, the invoice of the next period falls due the day that period starts. 5. **When the payment is confirmed,** by Stripe, or recorded by Widgetic for a payment that arrived outside it, the invoice's `status` becomes `paid`, and `paidDate` and `amountPaid` are filled in. You get an `invoice.paid` notification, and Widgetic's own team is told that the payment arrived. **You do not need to tell Widgetic that you paid.** 6. **If a card payment fails,** the invoice stays payable: its `status` becomes `failed`, `failureReason` says why in the card holder's words, and you get an `invoice.failed` notification. Pay it again from `hostedInvoiceUrl`. ### Tax An invoice shows the price (`subtotal`), the tax on it (`taxAmount`) and what you pay (`total`). Stripe works the tax out from the legal name, the address and the tax ID of your billing profile, so it follows the place your business is in. Where no tax is due, for example under the EU reverse charge, `taxAmount` is `0`. Widgetic keeps your billing profile: your legal name, up to five billing emails, your address, your tax ID (an EU VAT number or a US EIN, for example) and your payment terms. You cannot change it through the API, so give these details to Widgetic before your contract starts, because the first invoice is issued on that day, and tell Widgetic when one of them changes. An invoice that cannot be issued, for example because there is no billing email or Stripe does not accept the tax ID, is tried again every day. If its period ends first, nothing is invoiced for that period, so tell Widgetic as soon as these details change. ### When an Invoice Is Not Paid An invoice of your contract that is still unpaid after its due date **stops your partner account by itself**: from the day after the due date (UTC), until the invoice is paid. Paying on the due date, at any hour, is on time. Nobody has to press anything, and nobody has to switch your account on again. A stop deletes nothing: your compositions, uploads and customer records stay as they are. An unpaid invoice for [extra credits](#getting-more-credits) stops nothing. You are reminded before and after, and Widgetic's team is told: | When | What you receive | | - | - | | The invoice is issued | `invoice.issued` | | 3 days before the due date, and on the due date | `invoice.due_soon` | | 3, 7 and 14 days after the due date | `invoice.overdue` | Each reminder goes out once, in the morning (08:00 UTC), by email, in your dashboard and to your webhook, and paying the invoice stops them. If several steps were missed, you receive one catch-up reminder for the latest step, and a step within a day of the invoice being issued is skipped. The reminders for an invoice of your contract say that your account is stopped, or will be if the invoice is still unpaid after its due date. The ones for an invoice for extra credits say that nothing is stopped and that the credits are added once it is paid. Each of these notifications says in `purpose` what the invoice is for: `contract` or `extra_credits`. **While you are stopped,** your customers cannot use your widgets or editors, and your embeds are not served (their public address answers `404`). A call that changes something is refused with `403` and the code `PARTNER_PAYMENT_ARREARS`, except the ones you need to put it right: billing, invoices, buying credits, your storage settings, your notification settings and your API keys. Reads keep working. `GET /partners/mine` shows `standing` as `payment_arrears`, and `overdueSince`, the due date of the oldest unpaid invoice. Widgetic tells you with a `partner.paused` notification, whose `data.status` is `payment_arrears`, and `partner.resumed` when you are served again. **To end the stop, pay the overdue invoice** on its invoice page. Service comes back by itself as soon as the payment is confirmed. See [Account Status](https://widgetic.com/docs/partners/account-status.md) for what a stop keeps and stops. Widgetic can also pause an account by hand. That is a person's decision, and it is a different thing from an unpaid invoice (see [Account Status](https://widgetic.com/docs/partners/account-status.md)). ### Read Your Invoices `GET /invoices/partner/{partnerId}` lists the invoices issued to your partner account, newest first. Optional query parameters are `status`, `limit` (default 50, at most 100) and `offset`. ```bash theme={null} curl -sS -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \ "https://api.widgetic.com/v1/invoices/partner/$WIDGETIC_PARTNER_ID?status=open&limit=10" ``` `data` is a list. The fields you need are `number`, `description`, `subtotal`, `taxAmount`, `total` (`amount` is the same figure), `amountDue`, `amountPaid`, `currency`, `status`, `failureReason`, `invoiceDate`, `dueDate`, `paidDate`, `hostedInvoiceUrl` and `pdfUrl`. Money is in dollars, not cents. * `status` is one of `draft`, `open`, `pending`, `paid`, `failed`, `void`, `uncollectible`, `refunded` or `canceled`. A contract invoice starts as `open`. `open` waits for payment, and `failed` waits for payment after an attempt was refused (`failureReason` says why, and you can pay again from `hostedInvoiceUrl`). `paid` is settled, and a payment received outside Stripe counts. `void` was cancelled and owes nothing, and `uncollectible` was written off. * The list follows the invoice by itself. When Widgetic voids an invoice or writes it off in Stripe, or when you pay it, the `status` changes within moments, and nobody updates it by hand. * A request for a partner you do not administer answers 403, whether or not that partner exists. ## Storage Your contract includes no storage. Every file goes to your own bucket, which is required: your customers' uploads and the files of your own widgets, whether they come from the API, from the [editors](https://widgetic.com/docs/partners/editor-sessions.md#every-session-needs-your-own-storage) in your page or from Widgetic's MCP tools. Widgetic counts none of them against an allowance, so an upload of yours is never refused for a full one, and Widgetic does not sell storage to a partner account (`403` with the code `PARTNER_STORAGE_NOT_SOLD`). Set your bucket up in [Storage](https://widgetic.com/docs/partners/storage.md). What each customer keeps is in the [storage report](https://widgetic.com/docs/partners/storage.md#what-each-customer-keeps). ## One Account, Nothing Else to Create Your credits are in one place: the account of the person who administers your partner record, which is the account behind your API key. You do not create, fund or manage any other account or balance to get started. What you build with the key is charged to that account, an invoice you pay adds its credits to it, and every figure that shows your credits reads it: the account calls, the two partner credit calls and `operationalCredits` in the billing overview. An earlier version of Widgetic also kept a separate balance on the partner record, and `operationalCredits` used to show it. That balance is gone, and `operationalCredits` now shows your account's credits. If a script or a screen of yours still reads or tops up a "partner balance", point it at the account balance in [Checking Your Balance](#checking-your-balance). > [!WARNING] > > `POST /partners/{partnerId}/credits/add` and `PUT /partners/{partnerId}/credits/auto-reload` no longer exist, so do not call them: they answer `404`. To get more credits, buy [extra credits](#getting-more-credits). ## Not Available Yet * Paying an invoice through the API, or with a card on file. Extra credits are an invoice that you ask for through the API and pay on its page. * Credits paid for by card on the spot, or added before the invoice is paid. * Changing your contract, your billing profile (name, address, tax ID, billing emails, payment terms) or your payment method yourself. Tell Widgetic. * Usage per customer for the credits you spend with your own key. They are counted for your account as a whole, so your product has to record which of your customers caused what. The credits that a customer's [editor sessions](https://widgetic.com/docs/partners/editor-sessions.md#what-each-customer-spent) spend are the exception: you can read them for each customer, and hold one session to a number of them. What each customer keeps in storage is in the [storage report](https://widgetic.com/docs/partners/storage.md#what-each-customer-keeps). ## Error Handling | Status | Code | Description | | - | - | - | | 402 | `BILLING_INSUFFICIENT_CREDITS` | Your account does not have enough credits for this AI action | | 403 | | The balance, ledger, contract or invoices belong to another account | | 403 | `PARTNER_PAYMENT_ARREARS` | An invoice of your contract is unpaid after its due date. Billing, invoices, buying credits, storage settings, notification settings and API keys stay open to you; most other calls are refused until you pay (see [Account Status](https://widgetic.com/docs/partners/account-status.md)) | | 403 | `PARTNER_SUSPENDED` | Your account is paused. Billing, invoices and credits stay open to you; most other calls are refused (see [Account Status](https://widgetic.com/docs/partners/account-status.md)) | | 403 | `PARTNER_INACTIVE` | Your account has not been activated yet | | 403 | `PARTNER_STORAGE_NOT_SOLD` | Storage is not sold to a partner account: your files go to your own bucket | ## Best Practices > [accordion] Watch Your Balance > > Check the balance once a day, or before a large batch of AI work, and alert your team early: > > ```typescript theme={null} > const response = await fetch( > `https://api.widgetic.com/v1/credits/user/${accountId}/balance`, > { headers: { Authorization: `Bearer ${process.env.WIDGETIC_PARTNER_KEY}` } } > ); > const { data } = await response.json(); > > // Credits reserved for a running operation cannot be spent > const creditsAvailable = data.balance - data.reservedBalance; > > if (creditsAvailable < 100) { // under 100 credits ($10) > alertOps('Widgetic credits are running low: buy extra credits'); > } > ``` > [accordion] Monitor Usage > > Add up the credits spent today and alert on unusual spikes. The list holds at most 500 entries per call, so page with `offset` if you expect more than that in a day: > > ```typescript theme={null} > const startOfTodayUtc = new Date(); > startOfTodayUtc.setUTCHours(0, 0, 0, 0); > > const response = await fetch( > `https://api.widgetic.com/v1/credits/user/${accountId}/transactions?transaction_type=debit&limit=500`, > { headers: { Authorization: `Bearer ${process.env.WIDGETIC_PARTNER_KEY}` } } > ); > const { data: debits } = await response.json(); > > const creditsSpentToday = debits > .filter((entry: { createdAt: string }) => new Date(entry.createdAt) >= startOfTodayUtc) > .reduce((sum: number, entry: { amount: number }) => sum + entry.amount, 0); > > if (creditsSpentToday > DAILY_THRESHOLD) { > alertOps('Unusual credit usage detected'); > } > ``` > [accordion] Handle Running Out of Credits > > An AI action that cannot be paid for answers `402` with the code `BILLING_INSUFFICIENT_CREDITS`. Branch on the code, tell your user that generation is paused, and [buy extra credits](#getting-more-credits). Nothing else is affected: compositions and embeds keep working. > [accordion] Let Widgetic Tell You About Invoices > > Set an address for [notifications](https://widgetic.com/docs/partners/notifications.md) and your own system hears about every invoice when it is issued, when it is due, when it is overdue, when a payment fails and when it is paid, with the figures in `data`. Add the emails of your finance team to `emailRecipients`, so that nobody depends on one mailbox. Listing the invoices with `status=open` once a day is a good second check. > [accordion] Pay Before the Due Date > > An unpaid invoice of your contract stops your account, and your customers' widgets, from the day after its due date. Pay on or before the due date on the invoice page, keep the billing emails of your billing profile current, and subscribe to the invoice and `partner.paused` events so that more than one person hears about a late payment. ## Next Steps > [card] [Partner Overview](https://widgetic.com/docs/partners/overview.md) > > Back to partner documentation > [card] [Notifications](https://widgetic.com/docs/partners/notifications.md) > > Be told about invoices, payments and low credits > [card] [Account Status](https://widgetic.com/docs/partners/account-status.md) > > Activation, stops, pauses and how to get going again > [card] [API Reference](https://widgetic.com/api-reference/introduction.md) > > Find entitlement endpoints and access levels This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.