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

curl -X GET 'https://api.boldsign.com/v1-beta/plan/credits' \
-H 'accept: application/json' \
-H 'X-API-KEY: {your-api-key}'

ApiClient apiClient = new ApiClient("https://api.boldsign.com", "Your_API_Key");

PlanClient planClient = new PlanClient(apiClient);

var subscriptionCredits = planClient.GetSubscriptionCredits();

200 Success

{
  "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
    }
  ]
}

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.

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.

{
  "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)."
}

Each error response includes an errorType that identifies the error and an error message that describes it.

The request was made by a user who is not the account admin.

{
  "errorType": "AdminOnly",
  "error": "Only the account admin can view the subscription credits."
}

The request was made through an OAuth app that is billed to its creator.

{
  "errorType": "OAuthAppCreatorBilled",
  "error": "This OAuth app is billed to its creator. Use the app creator's own credentials to view the subscription credits."
}

The plan details of the subscription could not be resolved.

{
  "errorType": "PlanDetailsNotFound",
  "error": "Plan details could not be resolved for this subscription."
}