Skip to content
Log inDashboard

The organisation's billing state.

GET
/v1/account/billing
curl --request GET \
--url https://api.opdns.io/v1/account/billing \
--cookie __Host-opdns_session=<__Host-opdns_session>

Token scope: billing:read. The organisation owner only (403 owner_required for another member, with a session or a token). Solutions Opero Inc sells the plans and Stripe takes the payments: enabled is false until the deployment has its Stripe secret key and webhook signing secret, and every billing write then answers 503 billing_unavailable. offers are the plans and intervals POST /v1/account/billing/checkout sells. subscription is the organisation’s one subscription as the last webhook left it (null before the first checkout); past_due is set while a payment has failed: the plan stays until grace_ends_at (7 days after the first failure, two emails to the owners), then the organisation moves to free, keeping everything it holds, until a payment goes through. customer says whether Stripe’s customer portal opens (card, plan change, cancellation, invoices). Read from the control plane’s database, not from Stripe.

The billing state.

Media typeapplication/json
object
enabled
required

The deployment takes payments (its Stripe secret key and webhook signing secret are set).

boolean
test_mode
required

Stripe’s test mode; test cards only, nothing is charged.

boolean
offers
required

The plans and intervals Checkout sells, in upgrade order.

Array<object>
object
plan
required
string
Allowed values: free personal family business
interval
required
string
Allowed values: monthly yearly
customer
required

The organisation is a Stripe customer, so the portal (card, plan, invoices) opens.

boolean
subscription
required
One of:
object
status
required

Stripe’s subscription status.

string
Allowed values: incomplete incomplete_expired trialing active past_due canceled unpaid paused
plan
required

The plan the subscription’s product sells (empty if unknown).

string
interval
required

Monthly or yearly (empty if unknown).

string
current_period_end
required
string | null format: date-time
renews_at
required

The next charge; null when the subscription ends at the period’s end or has ended.

string | null format: date-time
cancel_at_period_end
required
boolean
past_due
required
One of:
object
since
required

The first failed payment.

string format: date-time
grace_ends_at
required

When the organisation moves to free unless a payment goes through.

string format: date-time
downgraded
required

The grace ended; the organisation is on free until a payment restores the plan.

boolean
Example
{
"enabled": true,
"test_mode": true,
"offers": [
{
"plan": "personal",
"interval": "monthly"
},
{
"plan": "personal",
"interval": "yearly"
}
],
"customer": true,
"subscription": {
"status": "active",
"plan": "personal",
"interval": "yearly",
"current_period_end": "2027-10-03T12:00:00Z",
"renews_at": "2027-10-03T12:00:00Z",
"cancel_at_period_end": false
},
"past_due": null
}

Not authenticated.

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
Example
{
"type": "https://opdns.io/problems/unauthenticated",
"title": "Unauthorized",
"status": 401,
"code": "unauthenticated",
"detail": "You're not signed in, or your sign-in has ended. Please sign in again to continue.",
"request_id": "5f2c9a0e7b1d4c38"
}

Authenticated but not allowed: insufficient_scope, session_required, csrf_rejected, reauth_required (sign in again within five minutes), account_pending_deletion (the account is in its deletion cooling-off), email_unverified (creating a profile before the email address is verified).

Media typeapplication/problem+json
object
type
required
string format: uri
title
required
string
status
required
integer
code
required

Stable machine code.

string
Allowed values: bad_request body_too_large bad_if_match unauthenticated signup_closed invite_required waitlist_unavailable mail_unavailable invalid_token token_expired token_used email_unverified session_required insufficient_scope csrf_rejected not_found version_mismatch ip_conflict managed_by_opwan no_opdns_account service_unavailable unknown_list too_many_rules validation_failed rate_limited internal node_revoked node_offline node_busy node_timeout node_error result_too_large shape_unsupported node_token_superseded relay_unavailable not_implemented query_timeout query_too_expensive range_too_large too_many_queries mfa_required reauth_required account_pending_deletion deletion_pending no_deletion_pending deletion_started organisation_has_members export_in_progress export_not_ready block_exists profile_not_empty no_adoption_pending invalid_cursor bad_idempotency_key idempotency_key_reused idempotency_in_progress too_many_streams too_many_reports profile_suspended plan_limit owner_required billing_unavailable billing_provider_error subscription_exists no_billing_account block_page_ca_exists oidc_unavailable feedback_status_conflict reply_not_wanted reply_unavailable
detail
string
errors
Array<object>
object
field
required
string
message
required
string
request_id
string
retry_after

Seconds, repeating the Retry-After header (rate limits, offline nodes).

integer
limit

The plan limit a plan_limit problem hit.

object
name
required
string
Allowed values: profiles linked_ips nodes queries_per_month log_retention_days api_tokens api_requests_per_minute
max
required

The plan’s value of the limit.

integer format: int64
plan
required
string
Allowed values: free personal family business
upgrade_url
required

Where to move to a larger plan.

string format: uri
required_scope

The scope the API token lacked (insufficient_scope).

string
Allowed values: profiles:read profiles:write nodes:write account:read billing:read logs:read analytics:read
Example
{
"type": "https://opdns.io/problems/insufficient_scope",
"title": "Forbidden",
"status": 403,
"code": "insufficient_scope",
"detail": "This API token isn't allowed to do this: it needs the profiles:write scope. Create a token that includes it, then try again.",
"required_scope": "profiles:write",
"request_id": "5f2c9a0e7b1d4c38"
}