> ## Documentation Index > Fetch the complete documentation index at: https://docs.hyperline.co/llms.txt > Use this file to discover all available pages before exploring further. # Configure default billing policy > Replace customer billing settings while preserving omitted plan_id and rate_card_id references; null detaches them, and a shared policy enables automatic telemetry billing. ## OpenAPI ````yaml put /v1/ai/billing/customers/{id}/policies/default openapi: 3.1.0 info: title: Hyperline API version: 0.0.0 servers: - url: https://api.hyperline.co - url: https://sandbox.api.hyperline.co security: [] paths: /v1/ai/billing/customers/{id}/policies/default: put: tags: - AI > Billing summary: Configure default billing policy description: >- Replace customer billing settings while preserving omitted plan_id and rate_card_id references; null detaches them, and a shared policy enables automatic telemetry billing. operationId: upsertDefaultCustomerBillingPolicy parameters: - schema: type: string required: true name: id in: path requestBody: description: Upsert billing policy payload content: application/json: schema: type: object properties: mode: type: string enum: - wallet - credits - windows description: |- Billing mode. - wallet: Charges a monetary wallet. - credits: Consumes a credit balance. - windows: Meters weighted units against rolling allowances. example: wallet wallet_id: type: - string - 'null' minLength: 1 description: >- Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet. example: wal_example credit_product_id: type: - string - 'null' minLength: 1 description: >- Public credit product identifier whose balance this policy consumes. example: prd_credits markup_percent: type: - string - 'null' maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value. example: '20' overage_mode: type: - string - 'null' enum: - refuse - metered description: >- 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. example: metered overage_markup_percent: type: - string - 'null' maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id. example: '10' overage_rate_card_id: type: - string - 'null' minLength: 1 description: >- Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup. example: airc_overage overage_wallet_id: type: - string - 'null' minLength: 1 description: Wallet charged for overage. Null bills overage in arrears. example: wal_example floor: type: - string - 'null' maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Minimum available balance a spend check requires, in the policy's denomination. example: '0' settlement_interval_minutes: type: - integer - 'null' minimum: 60 maximum: 44640 description: >- Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule. example: 60 settlement_schedule: type: - string - 'null' enum: - calendar_month description: >- Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes. - calendar_month: Settles at the end of each UTC calendar month. example: calendar_month windows: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 32 pattern: ^[a-z0-9][a-z0-9_-]*$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens duration_minutes: type: integer minimum: 1 maximum: 527040 description: >- Rolling allowance duration in whole minutes, from 1 through 527040. example: 1440 included_units: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' required: - key - duration_minutes - included_units minItems: 1 maxItems: 8 description: >- Rolling allowances. Required for windows plans; each window meters every call. A plan replacement replaces the entire array. example: - key: daily duration_minutes: 1440 included_units: '10000' rate_card_id: type: - string - 'null' minLength: 1 description: >- Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it. example: airc_example plan_id: type: - string - 'null' minLength: 1 description: >- Billing plan reference. On policy writes, omission preserves the current plan and null detaches it. example: aiplan_example blocked: type: boolean description: Whether spending is disabled for this billing scope. example: false required: - mode - blocked responses: '200': description: '' content: application/json: schema: type: object properties: id: type: string description: Unique Hyperline identifier for this resource. example: d18603dd-7285-4bf5-a45e-88d7de8f37c9 customer_id: type: string description: Hyperline customer identifier. example: cus_example agent_slug: type: - string - 'null' description: >- Agent scope identifier. Null is the customer's shared pool. example: support is_default: type: boolean description: Whether this is the default plan or shared customer scope. example: false mode: type: string enum: - wallet - credits - windows description: >- Billing mode. - wallet: Charges a monetary wallet. - credits: Consumes a credit balance. - windows: Meters weighted units against rolling allowances. example: wallet wallet_id: type: - string - 'null' description: >- Customer wallet identifier. Omit on wallet policy writes to provision or reuse the customer's wallet. example: wal_example credit_product_id: type: - string - 'null' description: >- Public credit product identifier whose balance this policy consumes. example: prd_credits markup_percent: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value. example: '20' overage_mode: type: string enum: - refuse - metered description: >- 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. example: metered overage_markup_percent: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id. example: '10' overage_rate_card_id: type: - string - 'null' description: >- Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup. example: airc_overage overage_rate_card_source: type: - string - 'null' enum: - policy - plan description: >- 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. example: plan overage_wallet_id: type: - string - 'null' description: Wallet charged for overage. Null bills overage in arrears. example: wal_example floor: type: string pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Minimum available balance a spend check requires, in the policy's denomination. example: '0' windows: type: array items: type: object properties: key: type: string minLength: 1 maxLength: 32 pattern: ^[a-z0-9][a-z0-9_-]*$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens duration_minutes: type: integer minimum: 1 maximum: 527040 description: >- Rolling allowance duration in whole minutes, from 1 through 527040. example: 1440 included_units: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' required: - key - duration_minutes - included_units description: >- Rolling allowances. Required for windows plans; each window meters every call. A plan replacement replaces the entire array. example: - key: daily duration_minutes: 1440 included_units: '10000' rate_card_id: type: - string - 'null' description: >- 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: type: - string - 'null' enum: - policy - plan description: >- 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. example: policy plan_id: type: - string - 'null' description: >- Billing plan reference. On policy writes, omission preserves the current plan and null detaches it. example: aiplan_example settlement_interval_minutes: type: - number - 'null' description: >- Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule. example: 60 settlement_schedule: type: - string - 'null' enum: - calendar_month description: >- Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes. - calendar_month: Settles at the end of each UTC calendar month. example: calendar_month resolved_rate_card: type: - object - 'null' properties: fallback_per_usd: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Credits, allowance units, or major currency units per USD of provider cost. Null leaves unmatched usage unpriced. example: '1' layer_count: type: number description: >- Number of pricing sources contributing to the effective card. example: 1 llm_rows: type: number description: Number of LLM pricing rows. example: 1 item_rows: type: number description: Number of item rows. example: 0 has_default_llm_row: type: boolean description: >- Whether a wildcard LLM row supplies rates for otherwise unmatched models. example: true required: - fallback_per_usd - layer_count - llm_rows - item_rows - has_default_llm_row description: >- Summary of the effective pricing after applying rate-card inheritance. Null when no card resolves. example: fallback_per_usd: '1000' layer_count: 1 llm_rows: 1 item_rows: 0 has_default_llm_row: true overrides: type: object properties: rate_card_id: type: - string - 'null' description: >- Rate card reference. On policy writes, omission preserves the current reference and null detaches it; on plan replacement omission clears it. example: null markup_percent: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to resolved cost. Null on writes means no override; an attached plan may supply the value. example: null overage_markup_percent: type: - string - 'null' pattern: ^-?\d+(\.\d+)?(e[+-]?\d+)?$/i description: >- Percentage added to provider cost for overage. Mutually exclusive with overage_rate_card_id. example: null overage_rate_card_id: type: - string - 'null' description: >- Currency rate card used to price overage directly. Null means provider cost plus the resolved overage markup. example: null settlement_interval_minutes: type: - number - 'null' description: >- Settlement interval in minutes. Null means no interval override. Mutually exclusive with settlement_schedule. example: null settlement_schedule: type: - string - 'null' enum: - calendar_month description: >- Calendar settlement schedule. Null clears the override; mutually exclusive with settlement_interval_minutes. - calendar_month: Settles at the end of each UTC calendar month. example: null windows: type: - array - 'null' items: type: object properties: key: type: string minLength: 1 maxLength: 32 pattern: ^[a-z0-9][a-z0-9_-]*$ description: >- Dimension or allowance identifier used by usage payloads and meter results. example: cached_input_tokens duration_minutes: type: integer minimum: 1 maximum: 527040 description: >- Rolling allowance duration in whole minutes, from 1 through 527040. example: 1440 included_units: type: string maxLength: 40 pattern: ^\d+(\.\d+)?$ description: >- Weighted units included in one allowance window, as an exact decimal string. example: '10000' required: - key - duration_minutes - included_units description: >- Rolling allowances. Required for windows plans; each window meters every call. A plan replacement replaces the entire array. example: null required: - rate_card_id - markup_percent - overage_markup_percent - overage_rate_card_id - settlement_interval_minutes - settlement_schedule - windows description: >- Pricing, window and settlement overrides before plan inheritance; null means no override. Use these values when editing configuration. example: rate_card_id: null markup_percent: null overage_markup_percent: null overage_rate_card_id: null settlement_interval_minutes: null settlement_schedule: null windows: null effective_settlement_interval_minutes: type: - number - 'null' description: Settlement interval after plan inheritance. example: 60 effective_settlement_schedule: type: - string - 'null' enum: - calendar_month description: Settlement schedule after plan inheritance. example: null blocked: type: boolean description: Whether spending is disabled for this billing scope. example: false created_at: type: string format: date-time description: Creation time as a UTC ISO 8601 timestamp. example: '2026-09-01T00:00:00Z' updated_at: type: string format: date-time description: Last update time as a UTC ISO 8601 timestamp. example: '2026-09-02T12:00:00Z' required: - id - customer_id - agent_slug - is_default - mode - wallet_id - credit_product_id - markup_percent - overage_mode - overage_markup_percent - overage_rate_card_id - overage_rate_card_source - overage_wallet_id - floor - windows - rate_card_id - rate_card_source - plan_id - settlement_interval_minutes - settlement_schedule - resolved_rate_card - overrides - effective_settlement_interval_minutes - effective_settlement_schedule - blocked - created_at - updated_at '400': description: Invalid request. content: application/json: schema: type: object properties: message: type: string required: - message '404': description: Customer not found content: application/json: schema: type: object properties: message: type: string required: - message '409': description: The request conflicts with the current configuration. content: application/json: schema: type: object properties: message: type: string required: - message security: - bearer: [] components: securitySchemes: bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.