# Get subscription credits {% get /%} {% path text="/v1-beta/plan/credits" /%} Returns the complete credit position of your subscription across all features and credit sources. Each feature and source pair appears at most once in the response, which includes the credit limit, the number of credits used, and the period over which the usage is counted, where applicable. Use this API to determine whether you have enough credits remaining for documents sent through the API, SMS, identity verification, KBA, or other billable features. {% note %} **Note:** Credit balances are refreshed every 2 minutes, so the most recent usage may not appear yet. {% /note %} ## Code snippet {% codetab %} cURL ```shell curl -X GET 'https://api.boldsign.com/v1-beta/plan/credits' \ -H 'accept: application/json' \ -H 'X-API-KEY: {your-api-key}' ``` C# ```csharp ApiClient apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key"); PlanClient planClient = new PlanClient(apiClient); var subscriptionCredits = planClient.GetSubscriptionCredits(); ``` {% /codetab %} ## Example response ***200 Success*** ```json { "environment": "Live", "credits": [ { "feature": "WebApp", "source": "Plan", "isUnlimited": false, "limit": 100, "used": 42, "period": { "start": 1788220800, "end": 1790812799 } }, { "feature": "WebApp", "source": "Prepaid", "isUnlimited": false, "limit": 500, "used": 120 }, { "feature": "API", "source": "Plan", "isUnlimited": false, "limit": 500, "used": 87, "period": { "start": 1788220800, "end": 1790812799 } }, { "feature": "BulkDocument", "source": "OneTime", "isUnlimited": false, "limit": 50, "used": 5 }, { "feature": "SMS", "source": "PayAsYouGo", "isUnlimited": true, "used": 10, "period": { "start": 1788220800, "end": 1790812799 } }, { "feature": "Template", "source": "Plan", "isUnlimited": false, "limit": 25, "used": 12 } ] } ``` ## Response parameters {% nestedtable %} - {% arguments name="environment" /%}{% batch datatype="string" /%}{% required /%} - The environment of the API key used for the request. Possible values are `Live` and `Test`. The credits are the same in both environments. --- - {% arguments name="credits" /%}{% batch datatype="array of objects" /%}{% required /%} - The credit balances for all applicable features. Each feature and source pair appears at most once. {% /nestedtable %} ### credits object {% nestedtable %} - {% arguments name="feature" /%}{% batch datatype="string" /%}{% required /%} - The feature the credits are for. The possible values are listed under Features below. More values may be added in the future, so ignore any value you do not recognize. --- - {% arguments name="source" /%}{% batch datatype="string" /%}{% required /%} - Where the credits come from. The possible values are listed under Credit sources below. More values may be added in the future, so ignore any value you do not recognize. --- - {% arguments name="isUnlimited" /%}{% batch datatype="boolean" /%}{% required /%} - Indicates whether the credits are unlimited. When true, the `limit` property is omitted from the response. For `PayAsYouGo` credits, true means no usage limit has been set, and each use is still billed. --- - {% arguments name="limit" /%}{% batch datatype="integer" /%} - The total number of credits available for the feature and source. This property is omitted when the credits are unlimited. --- - {% arguments name="used" /%}{% batch datatype="integer" /%}{% required /%} - The number of credits already used. This value is counted over the `period` when there is one, and it can exceed `limit`. --- - {% arguments name="period" /%}{% batch datatype="object" /%} - The window over which the `used` value is counted. The credits reset after `end`, which is inclusive. This property is omitted when the credits do not reset and remain valid until they are used (prepaid and one-time credits), and for template allowances that do not renew each billing period. --- - {% arguments name="period.start" /%}{% batch datatype="integer" /%} - The period start, in Unix epoch seconds (UTC). --- - {% arguments name="period.end" /%}{% batch datatype="integer" /%} - The period end, in Unix epoch seconds (UTC). This value is inclusive, meaning usage at this instant still counts toward the period. {% /nestedtable %} ### Features | Value | Description | |---|---| | `WebApp` | Documents sent from the BoldSign web or mobile app, counted per document. Also includes documents sent through the Salesforce and HubSpot integrations, self-sign documents when the plan has no separate self-sign allowance, and bulk documents when the plan has no separate bulk document allowance. | | `API` | Documents sent through the API, counted per document. | | `BulkDocument` | Documents created by bulk send or bulk link, counted per document. | | `SMS` | SMS messages sent to signers, such as signing notifications and verification codes, counted per message. | | `IdVerification` | Identity verification, counted per verification attempt, whether it succeeds or fails. | | `KBA` | Knowledge-based authentication, counted per authentication attempt. | | `QES` | Qualified electronic signature, counted per verification attempt. | | `WhatsApp` | WhatsApp messages sent to signers, counted per message. | | `Template` | Templates, counted per template. If the allowance renews each billing period, only templates created in the current period count. Otherwise, all saved templates count. | | `SelfSign` | Self-sign documents, counted per document. Returned only when the plan has a separate self-sign allowance; otherwise, self-sign documents count as `WebApp`. | ### Credit sources | Value | Description | |---|---| | `Plan` | The allowance included in your plan for the current billing period. | | `Prepaid` | Credits purchased in advance, available for `WebApp` and `API`. They do not expire with the billing period. | | `OneTime` | Credits granted once. They do not renew. | | `PayAsYouGo` | Usage billed per use, beyond or instead of the plan allowance. | ## Spending order The order in which credits are returned in the API response does not represent the order in which they are consumed. Credits are spent according to the following priority: 1. One-time credits. 2. Plan credits. 3. Prepaid credits. 4. Pay-as-you-go credits. One-time credits are currently issued only for bulk documents, so the response does not include one-time `WebApp` or `API` credits. ## Rate limiting This API has its own rate limit in addition to the account-wide rate limit. You can make up to 10 requests per minute for each subscription. The live and test environments are counted separately, so requests made in the test environment never use up the live environment's count. The limit is counted in fixed one-minute windows aligned to the clock, and the count resets at the start of each window. When you exceed the limit, the API returns a `429 Too Many Requests` response. The response includes a `Retry-After` header with the number of seconds remaining until the current window ends and the count resets. ```json { "message": "You have reached the maximum number of requests allowed for this endpoint.", "details": "Maximum allowed: 10 requests per 1m. Please try again in 32 second(s)." } ``` ## Authorization {% note %} **Note:** Only the account admin can read the subscription credits. If an OAuth app is billed to its creator, calls made through the app on behalf of other organizations cannot read the credits. {% /note %} ## Error responses Each error response includes an `errorType` that identifies the error and an `error` message that describes it. ### 403 Forbidden - Not an account admin The request was made by a user who is not the account admin. ```json { "errorType": "AdminOnly", "error": "Only the account admin can view the subscription credits." } ``` ### 403 Forbidden - OAuth app billed to its creator The request was made through an OAuth app that is billed to its creator. ```json { "errorType": "OAuthAppCreatorBilled", "error": "This OAuth app is billed to its creator. Use the app creator's own credentials to view the subscription credits." } ``` ### 404 Not Found - Plan details unavailable The plan details of the subscription could not be resolved. ```json { "errorType": "PlanDetailsNotFound", "error": "Plan details could not be resolved for this subscription." } ```