Update billing preferences

PUT

/v1/settings/billing-preferences

curl --request PUT \
  --url https://dev-api.infiniteaudience.ai/v1/settings/billing-preferences \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "low_balance_threshold": 1, "budget_ceiling": 1 }'

• Development API Server

Updates whichever platform-owned safeguard applies to your org’s own billing_model. Low-balance thresholds are prepay-only; budget ceilings are postpay-only. Requires ‘account’ scope.

Authorizations

• bearerAuth

Request Body^required

Media typeapplication/json

object

low_balance_threshold

Prepay only.

number | null

budget_ceiling

Postpay only. Optional hard spend ceiling per billing cycle; null removes the ceiling (unlimited).

number | null

Example^generated

{
  "low_balance_threshold": 1,
  "budget_ceiling": 1
}

Responses

200

Billing preferences updated.

Media typeapplication/json

object

ok

required

boolean

Example

{
  "ok": true
}

400

Invalid request, or the requested field doesn’t apply to this org’s billing model — code PREFERENCE_NOT_APPLICABLE_POSTPAY (low_balance_threshold on a postpay org) or BUDGET_CEILING_NOT_APPLICABLE_PREPAY (budget_ceiling on a prepay org).

Media typeapplication/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

key

additional properties

any

Examples

{
  "error": "Not applicable",
  "code": "PREFERENCE_NOT_APPLICABLE_POSTPAY",
  "message": "Low-balance alerts are prepay-only. Use budget_ceiling for postpay billing."
}

{
  "error": "Not applicable",
  "code": "BUDGET_CEILING_NOT_APPLICABLE_PREPAY",
  "message": "Budget ceiling is a postpay-only setting."
}

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).

Media typeapplication/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

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).

Media typeapplication/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

key

additional properties

any

Examples

Examplemissing_scope

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