> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackshift.cloud/llms.txt
> Use this file to discover all available pages before exploring further.
# Shared AI credits
> Understand your monthly AI allowance, purchase additional credits, choose your funding source, and track Assets and agent usage.
**Live.** This area is documented as current, user-reliable behavior.
## Goal
Use Assets, agents, and enabled AI workflows from one account balance with clear payment and usage history.
## Prerequisites
* Sign in to the account that pays for your resources.
* For team resources, usage is charged to the resource owner rather than each collaborator.
## Workflow
Open Billing and choose AI Credits.
Review your monthly balance, purchased balance, and credits currently in use.
Run an AI action in Assets or start an agent task.
Return to Usage history to inspect completed work and released credits.
Add credits through checkout or resume a paused task after the next monthly renewal.
## One balance across products
Assets analysis, transcription, image generation, image editing, agent inference, and AI workflows share the billing owner’s AI credit pool. Creating another space or inviting a collaborator does not create another allowance for that resource. Activity records the initiating user, project, Assets space, product, and action so you can identify where credits were used.
An agent can call an Assets AI tool. Its reasoning request and the separate image or analysis operation are distinct billable operations, grouped under the same parent task. The Assets operation is charged once. Ordinary resizing, image transformations, storage, video encoding, and product rendering continue to use their product allowances. Mandatory platform safety checks and internal platform operations do not consume customer AI credits.
## Monthly allowance and paid subscriptions
Every billing account receives 200 included credits each UTC calendar month, including paid accounts. One credit funds US$0.001 of provider usage, so the baseline represents US$0.20 of provider budget. Included credits expire at the end of that calendar month. The AI Credits page shows the next reset in your local time; allocation uses midnight UTC.
Eligible platform and Assets subscription payments add credits funded by 5% of settled subscription revenue, excluding tax. Contributions from multiple products add to the same pool. Infrastructure usage charges, wallet deposits, and AI top-ups do not generate extra included credits.
A subscription’s contribution is distributed over its purchased service period. A period that spans multiple calendar months contributes a proportion to each month based on covered time. Annual payments receive monthly portions rather than the entire annual contribution immediately. Upgrades contribute the incremental paid entitlement. Exchange rates and allocation policy are recorded with the entitlement, so later changes do not reprice existing grants.
## Read your balance
Available is what can fund new work. Monthly credits are the unspent included allowance available now. Purchased credits are the unspent credits you bought. In use shows reservations for admitted operations that have not finished settling. Credits are reserved before a provider request, so the available balance can decrease while a task is running.
The system uses expiring included credits before purchased credits. A reservation admitted before month-end remains valid after the reset. Any unused included credits released after their expiry stay expired; they do not become a new monthly allowance. Storage balances, S2 wallet funds, and cloud-money credits are separate from AI credits.
## Purchase additional credits
In Billing → AI Credits, enter the credit quantity, choose USD or NGN and your payment provider, then select Get checkout price. Review the amount and continue with Pay. At launch, 1,000 credits cost US\$2 equivalent. The NGN quote uses the billing exchange rate recorded when the quote is created. The displayed quote expires after 15 minutes; request a new quote if it expires.
Purchases are manual. Running out of credits never buys more automatically. Purchased credits remain available until consumed. Returning from checkout does not itself grant credits: Stackshift verifies the payment with the payment provider. Use Verify payment on the return page to refresh your balance. Repeated verification or duplicate payment notifications do not grant the purchase twice.
If checkout or verification fails, retry the current checkout or verification before paying again. A refund or chargeback removes the affected unspent credits. If some reversed credits were already used, the shortfall is covered by future purchased credits, and new platform-funded AI work pauses until it is resolved.
## Use your own provider key
Funding preferences let you select Shared AI credits or My provider key separately for Assets, agents, and workflows. Save your OpenAI key in the billing funding settings, then explicitly select the products that should use it. Adding a key does not switch funding mode. Stackshift never silently falls back between your key and platform-funded credits.
Your provider bills requests made with your key directly. Those requests are recorded separately and do not consume platform inference credits. Applicable storage and media-processing charges still apply. Remove or replace a key from the same settings. A product using My provider key requires a key that supports its requested capability; a text-only provider route cannot enable image generation.
## Assets actions and agent tasks
Open an Assets image in Image Studio or the AI-Powered Playground, choose a ready source image for an edit, enter your instruction, and run the action. You do not need to confirm a cost dialog for every action. The compact balance links to AI Credits. A temporary feature outage is distinct from an exhausted balance or a source that is not ready.
Agent tasks reserve credits before each bounded inference operation. If the next operation cannot be funded, the task pauses with its checkpoint intact. Add credits or wait for the monthly renewal, then select Resume task. You do not need to recreate the task or repeat the original instructions. The task’s usage summary shows actual credits used when settlement is available.
## Failures, cancellations, and returned credits
Failures before provider submission release the reservation. Successful usable output settles its recorded usage and releases the unused reservation. If you cancel after execution begins, completed billable work is charged and the remainder is released. A platform or provider failure without usable output does not consume customer credits; supplier costs are tracked separately.
If a provider times out after submission and its outcome is uncertain, the reservation remains in use while Stackshift reconciles the request. Do not create repeated copies to work around that state. An unresolved reservation is released after 24 hours, and a later supplier charge is absorbed by Stackshift rather than unexpectedly debited from your balance. Internal retries and fallback overhead do not multiply the customer charge.
## Find usage and reconcile totals
Usage history can be filtered by Assets, agents, or workflows, as well as initiating user ID, project ID, space ID, and date. Select Apply filters, then Load more for older activity. Each entry identifies the action, time, parent task when present, credits used or still in use, and returned credits. BYOK entries identify your provider key as the funding source.
Amounts in the API use integer microcredits: divide by 1,000,000 to display credits. Do not round each token or intermediate agent step to a whole credit. Reserved amounts represent work in progress, not an additional completed charge. Provider identity, supplier costs, unknown usage, and reconciliation diagnostics are available in administrative views.
## API and SDK access
GET /api/v1/billing/ai-credits returns available, monthly, purchased, reserved, and shortfall microcredits, the next reset, and grant details. GET /api/v1/billing/ai-credits/usage accepts product, user, project, space, from, until, limit, before\_time, and before\_id. Use the final item’s created\_at and id as the next page cursor. Timestamps use RFC 3339 and limits range from 1 to 100.
POST /api/v1/billing/ai-credits/top-ups/quote accepts credits and currency. POST /api/v1/billing/ai-credits/top-ups/checkout accepts quote\_id, a UUID idempotency\_key, and provider. Reuse the same idempotency key when retrying the same purchase. Server-side verification occurs through the existing billing payment verification and webhook infrastructure.
The JavaScript SDK exposes client.aiCredits.balance(), usage(filters), quote(credits, currency), checkout(input), funding(), and setFunding(product, mode). Python uses client.ai\_credits with balance(), usage(), quote(), checkout(), funding(), and set\_funding(). Go exposes client.AICredits with the corresponding context-aware methods. The PHP AssetsClient exposes aiCreditBalance(), aiCreditUsage(), quoteAICredits(), checkoutAICredits(), aiFundingModes(), and setAIFundingMode().
## Administration
Administrators open AI Credits in the admin application to publish future allocation policies and provider price revisions, inspect price history, grant auditable adjustments, and review unresolved provider attempts. A price records its model, capability, unit, rate, unit quantity, and effective date. Unknown supplier usage is displayed as Unknown, never as zero.
Existing grants retain their allocation policy and provider attempts retain their price snapshot. Stop new admissions through the account admission control when needed while allowing already submitted operations to complete settlement. Customer balance and payment interfaces do not expose provider configuration or reconciliation diagnostics.
## Expected result
The resource owner has one shared balance, and each completed provider operation appears once in usage history.