> Portal Navigation: > > - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version. > - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages). > - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`). > - Top-level index of all portals: https://dev.wix.com/docs/llms.txt > - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt # GetBalance # Package: aiCredits # Namespace: CreditTransactionsService # Method link: https://dev.wix.com/docs/api-reference/account-level/ai-credits/get-balance.md ## Introduction Retrieves an account's current AI credit balance. The balance includes recurring (periodic) credits, one-time top-up credits, and a per-source breakdown of the same credits. Use it to check an account's available credits before running an AI action, or to display the balance to an account. The data returned depends on the caller's access. With account-level access, the response covers all of the account's credits. With site-level access, the response is scoped to the credits and subscription of the site in context. When the caller has both, the account-level balance is returned. --- ## REST API ### Schema ``` Method: getBalance Description: Retrieves an account's current AI credit balance. The balance includes recurring (periodic) credits, one-time top-up credits, and a per-source breakdown of the same credits. Use it to check an account's available credits before running an AI action, or to display the balance to an account. The data returned depends on the caller's access. With account-level access, the response covers all of the account's credits. With site-level access, the response is scoped to the credits and subscription of the site in context. When the caller has both, the account-level balance is returned. URL: https://www.wixapis.com/appmarket/credittransactions/v1/credit-transactions/balance Method: POST Return type: GetBalanceResponse - name: periodicCredits | type: Periodic | description: An account's recurring (periodic) credits, aggregated across all sources. Recurring credits replenish each period, such as monthly. Returned only when the account has recurring credits. - name: balance | type: integer | description: Remaining recurring credits currently available. Decreases as credits are consumed and replenishes each period. | validation: minimum 0 - name: cap | type: integer | description: Maximum recurring credits available per period. | validation: minimum 0 - name: topUpCredits | type: TopUp | description: An account's one-time top-up credits, aggregated across all purchases. Top-up credits supplement recurring credits and don't reset. Returned only when the account has top-up credits. - name: balance | type: integer | description: Remaining one-time top-up credits currently available. | validation: minimum 0 - name: cap | type: integer | description: Maximum one-time top-up credits available. | validation: minimum 0 - name: creditBalanceBreakdown | type: array | description: A per-source breakdown of the account's credit balances. Each entry covers a distinct credit allocation and its usage rules, so you can track credits from different sources separately. This is a detailed view of the same credits aggregated in `periodicCredits` and `topUpCredits`, not additional credits. | validation: maxItems 1000 - name: subscriptionId | type: string | description: GUID of the subscription this credit allocation belongs to. Empty for credits that aren't tied to a subscription. | validation: format GUID - name: usageRules | type: array | description: Rules that define how the credits in this allocation can be consumed. Multiple rules can apply together, such as a daily limit within a monthly allocation. | validation: maxItems 10 - name: period | type: FeaturePeriod | description: How often the credits under this rule replenish, such as daily or monthly. Some credits have no period, meaning they're one-time and don't reset. - enum: NO_PERIOD, MILLISECOND, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR - name: balance | type: integer | description: Remaining credits available under this rule. - name: cap | type: integer | description: Maximum credits allowed under this rule per period. - name: resetDate | type: string | description: Date and time when this rule's balance resets to `cap`. | validation: format date-time ``` ### Examples ### Retrieve an account's AI credit balance Retrieves the calling account's current AI credit balance, including recurring credits, top-up credits, and a per-source breakdown. ```curl curl -X POST \ 'https://www.wixapis.com/appmarket/credittransactions/v1/credit-transactions/balance' \ -H 'Authorization: ' \ -H 'Content-Type: application/json' \ -d '{}' ``` --- ## JavaScript SDK ### Schema ``` Method: wixClientAdmin.aiCredits.CreditTransactionsService.getBalance() Description: Retrieves an account's current AI credit balance. The balance includes recurring (periodic) credits, one-time top-up credits, and a per-source breakdown of the same credits. Use it to check an account's available credits before running an AI action, or to display the balance to an account. The data returned depends on the caller's access. With account-level access, the response covers all of the account's credits. With site-level access, the response is scoped to the credits and subscription of the site in context. When the caller has both, the account-level balance is returned. Return type: PROMISE - name: periodicCredits | type: Periodic | description: An account's recurring (periodic) credits, aggregated across all sources. Recurring credits replenish each period, such as monthly. Returned only when the account has recurring credits. - name: balance | type: integer | description: Remaining recurring credits currently available. Decreases as credits are consumed and replenishes each period. | validation: minimum 0 - name: cap | type: integer | description: Maximum recurring credits available per period. | validation: minimum 0 - name: topUpCredits | type: TopUp | description: An account's one-time top-up credits, aggregated across all purchases. Top-up credits supplement recurring credits and don't reset. Returned only when the account has top-up credits. - name: balance | type: integer | description: Remaining one-time top-up credits currently available. | validation: minimum 0 - name: cap | type: integer | description: Maximum one-time top-up credits available. | validation: minimum 0 - name: creditBalanceBreakdown | type: array | description: A per-source breakdown of the account's credit balances. Each entry covers a distinct credit allocation and its usage rules, so you can track credits from different sources separately. This is a detailed view of the same credits aggregated in `periodicCredits` and `topUpCredits`, not additional credits. | validation: maxItems 1000 - name: subscriptionId | type: string | description: GUID of the subscription this credit allocation belongs to. Empty for credits that aren't tied to a subscription. | validation: format GUID - name: usageRules | type: array | description: Rules that define how the credits in this allocation can be consumed. Multiple rules can apply together, such as a daily limit within a monthly allocation. | validation: maxItems 10 - name: period | type: FeaturePeriod | description: How often the credits under this rule replenish, such as daily or monthly. Some credits have no period, meaning they're one-time and don't reset. - enum: NO_PERIOD, MILLISECOND, SECOND, MINUTE, HOUR, DAY, WEEK, MONTH, YEAR - name: balance | type: integer | description: Remaining credits available under this rule. - name: cap | type: integer | description: Maximum credits allowed under this rule per period. - name: resetDate | type: Date | description: Date and time when this rule's balance resets to `cap`. ``` ### Examples ### Retrieve an account's AI credit balance ```javascript import { aiCredits } from "@wix/ai-credits"; async function getBalance() { const response = await aiCredits.getBalance(); return response; } /* Promise resolves to: * { * "periodicCredits": { * "balance": 850, * "cap": 1000 * }, * "topUpCredits": { * "balance": 200, * "cap": 200 * }, * "creditBalanceBreakdown": [ * { * "subscriptionId": "d7a341c4-196b-46e7-813c-2b0fc1847ec6", * "usageRules": [ * { * "period": "MONTH", * "balance": 850, * "cap": 1000, * "resetDate": "2026-07-01T00:00:00.000Z" * } * ] * }, * { * "usageRules": [ * { * "period": "NO_PERIOD", * "balance": 200, * "cap": 200 * } * ] * } * ] * } */ ``` ### getBalance (self-hosted) Self-hosted SDK calls require you to [create a client](https://dev.wix.com/docs/sdk/articles/work-with-the-sdk/about-the-wix-client.md). ```javascript import { createClient } from '@wix/sdk'; import { aiCredits } from '@wix/ai-credits'; // Import the auth strategy for the relevant access type // Import the relevant host module if needed const myWixClient = createClient ({ modules: { aiCredits }, // Include the auth strategy and host as relevant }); async function getBalance() { const response = await myWixClient.aiCredits.getBalance(); }; ``` ---