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).
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).
5. Monitor your balance, your spending and your invoices in your dashboard, with the calls below, or let notifications 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.

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.

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) 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). Storage is not paid in credits either. See 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:

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:

curl -sS -H "Authorization: Bearer $WIDGETIC_PARTNER_KEY" \
  "https://api.widgetic.com/v1/credits/user/$WIDGETIC_ACCOUNT_ID/balance"

{
  "success": true,
  "data": {
    "id": "<uuid>",
    "userId": "<your administering account id>",
    "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.

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 shows an expiration entry for it. Credits that are left over are not carried into the next period. Extra 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 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.

# 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).
• 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.

In the TypeScript SDK (@widgetic/api-sdk-ts) the call is PartnersApi.createPartnerExtraCreditsInvoice, with partnerId, idempotencyKey and requestExtraCredits: { usd }.

In 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.

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:

{
  "id": "<uuid>",
  "transactionType": "debit",
  "amount": 1,
  "balanceAfter": 1499,
  "description": "Widget generation",
  "referenceId": "<id of the event>",
  "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). 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:

{
  "success": true,
  "data": {
    "partner": { "id": "<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: balance, reservedBalance and availableBalance (balance minus reservedBalance, never below 0), and the 10 newest entries of your 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).

​

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 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. 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 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 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).

​

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.

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 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. What each customer keeps is in the storage report.

​

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.

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.

​

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 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.

​

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)
403	PARTNER_SUSPENDED	Your account is paused. Billing, invoices and credits stay open to you; most other calls are refused (see Account Status)
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

Watch Your Balance

Check the balance once a day, or before a large batch of AI work, and alert your team early:

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');
}

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:

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');
}

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. Nothing else is affected: compositions and embeds keep working.

Let Widgetic Tell You About Invoices

Set an address for notifications 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.

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

Partner Overview

Back to partner documentation

Notifications

Be told about invoices, payments and low credits

Account Status

Activation, stops, pauses and how to get going again

API Reference

Find entitlement endpoints and access levels