Get native billing or setup readiness

GET

/v1/account/billing

const url = 'https://api.infiniteaudience.ai/v1/account/billing';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url https://api.infiniteaudience.ai/v1/account/billing \
  --header 'Authorization: Bearer <token>'

Returns the native contract, attributed financial projection and collection readiness, independently of connected Shopify stores. Without a native route, returns native_setup_required without creating an account or contract. Shopify usage stays in the separate store reporting surface. Recovery projections remain readable while frozen. A parent-billed native child never receives the agency’s pooled balance. Requires ‘account-read’ scope. First-party ‘account’ scope also suffices.

Authorizations

bearerAuth

Responses

200

Provider-neutral billing projection

application/json

One of:

object
object

object

billing

required

object

billing_account_id

required

string

owner_type

required

string

Allowed values: org agency

owner_id

required

string

source

required

string

consumer_org_id

required

string

billing_authority

required

string

Allowed values: self agency

agency_id

required

string | null

consumer_postpay_ceiling_cents

required

integer | null

consumer_money

required

object

current_period_spend_cents

required

integer

active_reserved_cents

required

integer

accepted_pending_cents

required

integer

projected_at

required

string | null format: date-time

billing_model

required

string

Allowed values: prepay postpay

collection_method

required

string

Allowed values: charge_automatically send_invoice

currency

required

string

Allowed value: usd

status

required

string

Allowed values: pending active payment_action_required past_due suspended canceled provisioning_failed

contract

required

object

tier

required

string | null

Allowed values: paygo pilot growth scale enterprise

cadence

required

string | null

Allowed values: monthly annual

commitment_term_months

required

integer

Allowed values: 0 12 24 36

commitment_amount_cents

required

integer

usage_discount_bps

required

Contract discount applied to usage rates only; commitment charges and minimums are unchanged.

integer

<= 10000

contract_start_at

required

string | null format: date-time

contract_end_at

required

string | null format: date-time

current_period_start_at

required

string | null format: date-time

current_period_end_at

required

string | null format: date-time

pending_change_at

required

string | null format: date-time

scheduled_change

required

One of:

object
null

object

kind

required

string

Allowed values: replacement renewal cancellation

request_id

required

string

status

required

string

Allowed values: provisioning scheduled failed

effective_at

required

string format: date-time

previous_contract_end_at

required

string | null format: date-time

successor_contract_id

required

string | null

terms

required

One of:

object
null

object

tier

required

string

Allowed values: paygo pilot growth scale enterprise

cadence

required

string

Allowed values: monthly annual

commitment_term_months

required

integer

Allowed values: 0 12 24 36

commitment_amount_cents

required

integer

usage_discount_bps

required

integer

<= 10000

usage_rates

required

object

match

required

object

microbatch

required

integer

file

required

integer

audience_delivery

required

object

filter

required

integer

matched

required

integer

similarity

required

integer

propensity

required

integer

destination

required

object

key

additional properties

integer

enrichment_field

required

object

key

additional properties

integer

error_code

required

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

usage_rates

required

One of:

object
null

object

match

required

object

microbatch

required

integer

file

required

integer

audience_delivery

required

object

filter

required

integer

matched

required

integer

similarity

required

integer

propensity

required

integer

destination

required

object

key

additional properties

integer

enrichment_field

required

object

key

additional properties

integer

money

required

object

available_balance_cents

required

integer | null

committed_balance_cents

required

integer | null

promotional_balance_cents

required

integer | null

current_period_spend_cents

required

integer

current_invoice_total_cents

required

integer | null

next_credit_expiry_at

required

string | null format: date-time

active_reserved_cents

required

integer

accepted_pending_cents

required

integer

effective_available_cents

required

integer | null

payment_method_ready

required

boolean

auto_recharge

required

object

configured

required

boolean

enabled

required

boolean

threshold_cents

required

integer | null

>= 500

recharge_to_cents

required

integer | null

>= 1500 <= 5000000

configuration_request_id

required

string | null

payment_status

required

string

Allowed values: none pending action_required paid failed

last_payment_attempt_id

required

string | null

stripe_invoice_id

required

string | null

stripe_payment_intent_id

required

string | null

last_error_code

required

string | null

updated_at

required

string | null format: date-time

pending_change

required

One of:

object
null

object

request_id

required

string

enabled

required

boolean

threshold_cents

required

integer

>= 500

recharge_to_cents

required

integer

>= 1500 <= 5000000

status

required

string

Allowed values: provisioning failed

last_error_code

required

string | null

created_at

required

string format: date-time

updated_at

required

string format: date-time

key

additional properties

any

latest_invoice

required

object

required

string | null

status

required

string | null

collection

required

object

status

required

string

Allowed values: current past_due uncollectible

stripe_invoice_id

required

string | null

failure_started_at

required

string | null format: date-time

grace_period_ends_at

required

string | null format: date-time

updated_at

required

string | null format: date-time

projection

required

object

projected_at

required

string | null format: date-time

provider_version

required

string | null

billing_mode

required

string

Allowed values: org_billed parent_billed

parent_org

required

One of:

object
null

object

required

string | null

name

required

string | null

billing_readiness

required

object

requires_card

required

boolean

has_default_card

required

boolean

collection_method_ok

required

boolean

payment_collection_ready

required

boolean

status

required

string

Allowed values: ok card_missing collection_method_mismatch not_applicable

operational

required

object

frozen

required

boolean

compute_usage_pct

required

number

projection

required

object

projected_at

required

string | null format: date-time

provider_version

required

string | null

stale

required

boolean

refresh_error_code

required

string | null

latest_payment

required

One of:

object
null

object

payment_attempt_id

required

string

kind

required

string

Allowed values: topup auto_recharge

request_id

required

string

status

required

string

Allowed values: pending action_required paid failed

amount_cents

required

integer

bonus_cents

required

integer

principal_credit_status

required

string

Allowed values: awaiting_payment updating available needs_attention not_applicable

bonus_credit_status

required

string

Allowed values: awaiting_payment updating available needs_attention not_applicable

paid_at

required

string | null format: date-time

updated_at

required

string format: date-time

last_error_code

required

string | null

credit_error_code

required

string | null

Example

{
  "billing": {
    "owner_type": "org",
    "billing_authority": "self",
    "billing_model": "prepay",
    "collection_method": "charge_automatically",
    "currency": "usd",
    "status": "pending",
    "contract": {
      "tier": "paygo",
      "cadence": "monthly",
      "commitment_term_months": 0,
      "scheduled_change": {
        "kind": "replacement",
        "status": "provisioning",
        "terms": {
          "tier": "paygo",
          "cadence": "monthly",
          "commitment_term_months": 0
        }
      }
    },
    "auto_recharge": {
      "payment_status": "none",
      "pending_change": {
        "status": "provisioning"
      }
    },
    "collection": {
      "status": "current"
    }
  },
  "billing_mode": "org_billed",
  "billing_readiness": {
    "status": "ok"
  },
  "latest_payment": {
    "kind": "topup",
    "status": "pending",
    "principal_credit_status": "awaiting_payment",
    "bonus_credit_status": "awaiting_payment"
  }
}

401

Missing or invalid Bearer token. Obtain one via POST /v1/auth/token. When a token was supplied but rejected, code distinguishes TOKEN_EXPIRED (the token’s lifetime has passed — request a new one via POST /v1/auth/token and retry) from TOKEN_INVALID (malformed or revoked — re-authenticate).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

{
  "error": "Unauthorized: Missing or invalid Authorization header"
}

{
  "error": "Unauthorized",
  "code": "TOKEN_EXPIRED",
  "message": "Your session has expired. Please sign in again."
}

403

Token is valid but lacks the required scope for this endpoint. Check the endpoint description for the required scope (discovery, purchase, or account).

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

missing_scope

{
  "error": "SCOPE_REQUIRED",
  "message": "This endpoint requires the creator scope."
}

404

Resource not found or not accessible to the calling org.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Examples

not_found

{
  "error": "Audience not found"
}

409

Resource state conflicts with the request. For upload analysis this includes FILE_NOT_YET_UPLOADED.

application/json

object

error

required

Stable machine-readable error code (e.g. INVALID_STATUS_TRANSITION, BILLING_INSUFFICIENT_BALANCE). Always present.

string

message

Human-readable explanation of the error.

string

code

Alternate machine-readable code — present on some endpoints as an alias for error for backward compatibility.

string

request_id

Opaque support/debug identifier when available.

string

next_step

Public action for correcting the request or retrying later.

string

issues

Array<object>

object

path

required

JSON path to the invalid filter field or value.

string

code

required

string

Allowed values: INVALID_FILTER_SHAPE UNKNOWN_FILTER_FIELD FIELD_NOT_FILTERABLE UNSUPPORTED_FILTER_OPERATOR UNSUPPORTED_TEXT_COMPARISON INVALID_FILTER_VALUE INVALID_ENUM_VALUE AMBIGUOUS_ENUM_VALUE

message

required

string

suggestions

Array<string>

key

additional properties

any

Example

{
  "issues": [
    {
      "code": "INVALID_FILTER_SHAPE"
    }
  ]
}