Skip to main content
PUT
Configure a customer's agent billing policy

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

customer_id
string
required

Query Parameters

agent
string

Agent scope identifier. Null on scoped results denotes the customer's shared pool.

Required string length: 1 - 128
Example:

"support"

Body

application/json

Upsert billing policy payload

mode
enum<string>
required

Billing mode.

  • wallet: Charges a monetary wallet.
  • credits: Consumes a credit balance.
  • windows: Meters weighted units against rolling allowances.
Available options:
wallet,
credits,
windows
Example:

"wallet"

blocked
boolean
required

Whether spending is disabled for this billing scope.

Example:

false

wallet_id
string | null

Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet.

Minimum string length: 1
Example:

"wal_example"

credit_product_id
string | null

Public credit product identifier whose balance this policy consumes.

Minimum string length: 1
Example:

"prd_credits"

markup_percent
string | null

Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value.

Maximum string length: 40
Pattern: ^\d+(\.\d+)?$
Example:

"20"

overage_mode
enum<string> | null

Behavior when credits or an allowance are exhausted. Policy values may inherit the attached plan.

  • refuse: Rejects the call that crosses the boundary without deducting usage.
  • metered: Prices the whole call as monetary overage, using the overage card or USD provider cost plus markup.
Available options:
refuse,
metered
Example:

"metered"

overage_markup_percent
string | null

Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id.

Maximum string length: 40
Pattern: ^\d+(\.\d+)?$
Example:

"10"

overage_rate_card_id
string | null

Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup.

Minimum string length: 1
Example:

"airc_overage"

overage_wallet_id
string | null

Wallet charged for overage. Null bills overage in arrears.

Minimum string length: 1
Example:

"wal_example"

floor
string | null

Minimum available balance a spend check requires, in the policy's denomination.

Maximum string length: 40
Pattern: ^\d+(\.\d+)?$
Example:

"0"

settlement_interval_minutes
integer | null

Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule.

Required range: 60 <= x <= 44640
Example:

60

settlement_schedule
enum<string> | null

Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes.

  • calendar_month: Settles at the end of each UTC calendar month.
Available options:
calendar_month
Example:

"calendar_month"

credit_rates
object | null

Inline credit pricing. Mutually exclusive with rate_card_id. Omitted rates may be supplied by a plan or product default.

Example:
window_rates
object | null

Window definitions and optional inline unit rates. An attached plan may supply omitted definitions; rate_card_id may supply unit rates.

Example:
rate_card_id
string | null

Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it.

Minimum string length: 1
Example:

"airc_example"

plan_id
string | null

Billing plan reference. On policy writes, omission preserves the current plan and null detaches it.

Minimum string length: 1
Example:

"aiplan_example"

Response

id
string
required

Unique Hyperline identifier for this resource.

Example:

"d18603dd-7285-4bf5-a45e-88d7de8f37c9"

customer_id
string
required

Hyperline customer identifier.

Example:

"cus_example"

agent_slug
string | null
required

Agent scope identifier. Null is the customer's shared pool.

Example:

"support"

is_default
boolean
required

Whether this is the default plan or shared customer scope.

Example:

false

mode
enum<string>
required

Billing mode.

  • wallet: Charges a monetary wallet.
  • credits: Consumes a credit balance.
  • windows: Meters weighted units against rolling allowances.
Available options:
wallet,
credits,
windows
Example:

"wallet"

wallet_id
string | null
required

Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet.

Example:

"wal_example"

credit_product_id
string | null
required

Public credit product identifier whose balance this policy consumes.

Example:

"prd_credits"

markup_percent
string
required

Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value.

Pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i
Example:

"20"

overage_mode
enum<string>
required

Behavior when credits or an allowance are exhausted. Policy values may inherit the attached plan.

  • refuse: Rejects the call that crosses the boundary without deducting usage.
  • metered: Prices the whole call as monetary overage, using the overage card or USD provider cost plus markup.
Available options:
refuse,
metered
Example:

"metered"

overage_markup_percent
string
required

Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id.

Pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i
Example:

"10"

overage_rate_card_id
string | null
required

Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup.

Example:

"airc_overage"

overage_rate_card_source
enum<string> | null
required

Source of the effective overage rate card. Null when no card is configured.

  • policy: Selected directly on the customer policy.
  • plan: Inherited from the attached plan.
Available options:
policy,
plan
Example:

"plan"

overage_wallet_id
string | null
required

Wallet charged for overage. Null bills overage in arrears.

Example:

"wal_example"

floor
string
required

Minimum available balance a spend check requires, in the policy's denomination.

Pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i
Example:

"0"

credit_rates
object | null
required

Inline credit pricing. Mutually exclusive with rate_card_id. Omitted rates may be supplied by a plan or product default.

Example:
window_rates
object | null
required

Window definitions and optional inline unit rates. An attached plan may supply omitted definitions; rate_card_id may supply unit rates.

Example:
rate_card_id
string | null
required

Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it.

Example:

"airc_example"

rate_card_source
enum<string> | null
required

Source of the effective rate card. Null when no card is configured.

  • policy: Selected directly on the customer policy.
  • plan: Inherited from the attached plan.
Available options:
policy,
plan
Example:

"policy"

plan
object | null
required

Attached plan summary, or null.

Example:
settlement_interval_minutes
number | null
required

Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule.

Example:

60

settlement_schedule
enum<string> | null
required

Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes.

  • calendar_month: Settles at the end of each UTC calendar month.
Available options:
calendar_month
Example:

"calendar_month"

resolved_rate_card
object | null
required

Summary of the effective pricing after applying rate-card inheritance. Null when no card resolves.

Example:
blocked
boolean
required

Whether spending is disabled for this billing scope.

Example:

false

created_at
string<date-time>
required

Creation time as a UTC ISO 8601 timestamp.

Example:

"2026-09-01T00:00:00Z"

updated_at
string<date-time>
required

Last update time as a UTC ISO 8601 timestamp.

Example:

"2026-09-02T12:00:00Z"