Billing accounts

Billing settings and credit, shared by the organizations that belong to the billing account

Endpoints
GET/billing_accountsPATCH/billing_accounts

The billing account object

Attributes

idread-onlyuuid

Unique identifier

paddle_subscription_idread-onlytext | null

Identifier of the subscription in Paddle

created_atread-onlytimestamp with time zone

Creation timestamp

updated_attimestamp with time zone

Last modification timestamp

allow_pre_paidread-onlyboolean

Whether the billing account can buy credits up front, for a pre-paid subscription

creditread-onlyinteger

Number of credits currently available

currencyCurrencyCode

Currency in which the billing account is billed

maximum_usageread-onlyinteger

Number of credits a subscription can use beyond its credit. credit goes down to minus this number

minimum_guaranteeread-onlyinteger

Minimum number of credits billed per month

overage_billed_forread-onlytimestamp with time zone | null

Renewal date, read from Paddle, of the last period whose overage was billed, so overage is charged once per period

prev_usageread-onlyinteger

Number of credits used in the 7 days before the last 7 days

price_per_creditread-onlyinteger

Agreed price per credit

price_per_userread-onlyinteger

Agreed price per user license

pricing_versionread-onlyPricingVersion

Pricing version of the billing account

recent_usageread-onlyinteger

Number of credits used in the last 7 days

subscription_typeread-onlySubscriptionType

Type of the active subscription

trial_expires_atread-onlytimestamp with time zone | null

Trial expiration timestamp

user_licensesread-onlyinteger | null

Maximum number of users with the edit_candidates permission in the billing account. Only limits subscriptions; null means no limit

Related resources

Embed related resources in the response with the select parameter, for example select=*,credit_mutations(*). See selecting data. Resources related through more than one column need the column as a hint, like table!column(*).

credit_mutations(*)array
credit_mutations.billing_account_id

The credit mutations referencing this billing account through credit_mutations.billing_account_id.

organizations!billing_account_id(*)array
organizations.billing_account_id

The organizations referencing this billing account through organizations.billing_account_id.

The billing account object
JSON
{
  "id": "00000000-0000-0000-0000-000000000000",
  "paddle_subscription_id": "sub_01h8bx3z9k7mq2w4e6r8t0y2u4",
  "created_at": "2026-01-01T12:00:00+00:00",
  "updated_at": "2026-01-01T12:00:00+00:00",
  "allow_pre_paid": false,
  "credit": 0,
  "currency": "USD",
  "maximum_usage": 0,
  "minimum_guarantee": 0,
  "overage_billed_for": "",
  "prev_usage": 0,
  "price_per_credit": 0,
  "price_per_user": 0,
  "pricing_version": "v3",
  "recent_usage": 0,
  "subscription_type": "subscription",
  "trial_expires_at": null,
  "user_licenses": 0
}
Including related resources
curl "https://api.cv-transformer.com/v1/billing_accounts?limit=10&select=*,credit_mutations(*),organizations!billing_account_id(*)" \
  -H "Authorization: Bearer YOUR_API_KEY"

List billing accounts

Requiresorganization:read

Filters

idFilter<uuid>

Unique identifier

paddle_subscription_idFilter<text | null>

Identifier of the subscription in Paddle

created_atFilter<timestamp with time zone>

Creation timestamp

updated_atFilter<timestamp with time zone>

Last modification timestamp

allow_pre_paidFilter<boolean>

Whether the billing account can buy credits up front, for a pre-paid subscription

creditFilter<integer>

Number of credits currently available

currencyFilter<CurrencyCode>

Currency in which the billing account is billed

maximum_usageFilter<integer>

Number of credits a subscription can use beyond its credit. credit goes down to minus this number

minimum_guaranteeFilter<integer>

Minimum number of credits billed per month

overage_billed_forFilter<timestamp with time zone | null>

Renewal date, read from Paddle, of the last period whose overage was billed, so overage is charged once per period

prev_usageFilter<integer>

Number of credits used in the 7 days before the last 7 days

price_per_creditFilter<integer>

Agreed price per credit

price_per_userFilter<integer>

Agreed price per user license

pricing_versionFilter<PricingVersion>

Pricing version of the billing account

recent_usageFilter<integer>

Number of credits used in the last 7 days

subscription_typeFilter<SubscriptionType>

Type of the active subscription

trial_expires_atFilter<timestamp with time zone | null>

Trial expiration timestamp

user_licensesFilter<integer | null>

Maximum number of users with the edit_candidates permission in the billing account. Only limits subscriptions; null means no limit

Responses

200

A list of billing accounts with the selected columns. The Content-Range header holds the range returned and the total count, like 0-9/42.

206

Partial Content

400

The request is malformed, for example an unknown column or an invalid filter.

401

The API key is missing or invalid.

403

The API key doesn't have the scope this request needs.

429

The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the Retry-After header.

Errors have a JSON body with a message, details and hint, and for database errors a code. See errors.
GET/billing_accounts
curl "https://api.cv-transformer.com/v1/billing_accounts?limit=10&select=*" \
  -H "Authorization: Bearer YOUR_API_KEY"
Example response
JSON
[
  {
    "id": "00000000-0000-0000-0000-000000000000",
    "paddle_subscription_id": "sub_01h8bx3z9k7mq2w4e6r8t0y2u4",
    "created_at": "2026-01-01T12:00:00+00:00",
    "updated_at": "2026-01-01T12:00:00+00:00",
    "allow_pre_paid": false,
    "credit": 0,
    "currency": "USD",
    "maximum_usage": 0,
    "minimum_guarantee": 0,
    "overage_billed_for": "",
    "prev_usage": 0,
    "price_per_credit": 0,
    "price_per_user": 0,
    "pricing_version": "v3",
    "recent_usage": 0,
    "subscription_type": "subscription",
    "trial_expires_at": null,
    "user_licenses": 0
  }
]

Update billing accounts

Requiresorganization:write

Filters

Without filters, this request updates all billing accounts the API key has access to. Always filter on at least one column, like id=eq.{id}.

idFilter<uuid>

Unique identifier

paddle_subscription_idFilter<text | null>

Identifier of the subscription in Paddle

created_atFilter<timestamp with time zone>

Creation timestamp

updated_atFilter<timestamp with time zone>

Last modification timestamp

allow_pre_paidFilter<boolean>

Whether the billing account can buy credits up front, for a pre-paid subscription

creditFilter<integer>

Number of credits currently available

currencyFilter<CurrencyCode>

Currency in which the billing account is billed

maximum_usageFilter<integer>

Number of credits a subscription can use beyond its credit. credit goes down to minus this number

minimum_guaranteeFilter<integer>

Minimum number of credits billed per month

overage_billed_forFilter<timestamp with time zone | null>

Renewal date, read from Paddle, of the last period whose overage was billed, so overage is charged once per period

prev_usageFilter<integer>

Number of credits used in the 7 days before the last 7 days

price_per_creditFilter<integer>

Agreed price per credit

price_per_userFilter<integer>

Agreed price per user license

pricing_versionFilter<PricingVersion>

Pricing version of the billing account

recent_usageFilter<integer>

Number of credits used in the last 7 days

subscription_typeFilter<SubscriptionType>

Type of the active subscription

trial_expires_atFilter<timestamp with time zone | null>

Trial expiration timestamp

user_licensesFilter<integer | null>

Maximum number of users with the edit_candidates permission in the billing account. Only limits subscriptions; null means no limit

Body

Partial<BillingAccount>

The attributes are listed under the billing account object. Read-only attributes are set by CV-Transformer and can't be written.

Responses

204

Updated. With the header Prefer: return=representation, the response is a 200 whose body holds the updated billing accounts with the selected columns.

400

The request is malformed, for example an unknown column, an invalid filter or an invalid body.

401

The API key is missing or invalid.

403

The API key doesn't have the scope this request needs, or no permission for this change, for example when writing rows of another organization.

409

The change conflicts with existing data, for example a duplicate key or a reference to a row that does not exist.

429

The API key made more requests per minute than its rate limit allows. Retry after the number of seconds in the Retry-After header.

Errors have a JSON body with a message, details and hint, and for database errors a code. See errors.
PATCH/billing_accounts
curl -X PATCH "https://api.cv-transformer.com/v1/billing_accounts?id=eq.00000000-0000-0000-0000-000000000000" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "currency": "USD" }'
Example response
JSON
(no content)