TOtodoist
Billing

Usage Billing State

Changed on

Read the caller's usage-billing credit state for a product.

A user who has never topped up reads as an empty wallet: available_units and available_amount are 0, is_settled_low_balance is true, and usage_block_reason is insufficient_credit. There is no separate "no account" answer, because both states send the user to the same top-up screen.

get/api/v1/usage_billing/state

Request

  • Base URL
    https://api.todoist.com
  • URL
    https://api.todoist.com/api/v1/usage_billing/state
  • Auth
    none declared

Query parameters

productstring

Product whose credit state to read.

Example:automations

Response

Successful Response

available_unitsinteger required

Balance net of in-flight holds (available_cached - held). The ledger unit, kept for support and reconciliation; display available_amount instead. Not a permission to start a run: use usage_allowed for that.

available_amountinteger required

available_units in money, in microdollars (millionths of one currency unit), so 8372600 is $8.3726. The scale is exact for every amount this API reports; cents and hundredths of a cent both truncate a single chat message to zero. Converted by the server because the client cannot: the ratio is the account's pinned price and only the backend holds it.

settled_unitsinteger required

Balance after settled credits and debits, before in-flight holds (available_cached).

settled_amountinteger required

settled_units in money, in microdollars (millionths of one currency unit), using the account's pinned price.

currencystring required

ISO currency code every amount in this response is in. Fixed for the life of the account: the first top-up pins the price, and the price fixes the currency. A user who has not topped up yet reads the currency they will be charged in.

usage_allowedboolean required

Whether a new run may start right now.

low_balanceboolean required

Balance is at or below the low-balance threshold.

is_settled_low_balanceboolean required

Whether the settled balance before in-flight holds is at or below the low-balance threshold.

usage_block_reason'temporarily_unavailable' | 'insufficient_credit' | 'plan_required' | 'billing_paused' nullable required

Why a new run cannot start, or null when it can. temporarily_unavailable means existing holds are the only blocker; insufficient_credit means the settled balance is at or below the configured floor; plan_required means the user has no Pro, and the credit waits until they do; billing_paused means the compute subscription was cancelled, and the credit waits for the next top-up.

depletedboolean required

No credit is left for another run after in-flight holds. Equivalent to usage_allowed being false, except when usage_block_reason is plan_required or billing_paused: those block runs while credit is still there.

Example response

{
  "available_units": 4186300,
  "available_amount": 8372600,
  "settled_units": 4186300,
  "settled_amount": 8372600,
  "currency": "usd",
  "usage_allowed": true,
  "is_settled_low_balance": true
}

Changes

  • c8354019ae10Revision changes
    • warning

      added the new billing_paused enum value to the / response property for the response status

    • warning

      added the new plan_required enum value to the / response property for the response status

  • c720d271ad4dRevision changes
    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status

    • info

      added the required property to the response with the status