> ## Documentation Index > Fetch the complete documentation index at: https://docs.amlok.io/llms.txt > Use this file to discover all available pages before exploring further. # Retrieve billing account > Read the unified workspace billing policy, CAD 200 default automatic top-up trigger, and CAD 500 minimum customer-funded top-up. The client portal manages card or bank-account payment methods, automatic top-ups and cancellation; enterprise clients can also use their dedicated account manager. The public API provides reporting only. Cancellation is available at any time with no notice period. Processing, usage deductions, and upcoming top-ups stop immediately when cancellation is submitted or set by the account manager. Cancel unfinished work without another debit. Full closure is at the end of the request month, with an immediate refund of all unused credits, including promotional credits, to the saved portal bank account. Data is deleted after the month closes and necessary final information is generated. Used credits are non-refundable. Required scope: billing:read. The API key is bound to exactly one workspace, institution and environment. There is no workspace override; this binding applies to every read and export. **Required scope:** `billing:read` Read the unified workspace billing policy, CAD 200 default automatic top-up trigger, and CAD 500 minimum customer-funded top-up. The client portal manages card or bank-account payment methods, automatic top-ups and cancellation; enterprise clients can also use their dedicated account manager. The public API provides reporting only. Cancellation is available at any time with no notice period. Processing, usage deductions, and upcoming top-ups stop immediately when cancellation is submitted or set by the account manager. Cancel unfinished work without another debit. Full closure is at the end of the request month, with an immediate refund of all unused credits, including promotional credits, to the saved portal bank account. Data is deleted after the month closes and necessary final information is generated. Used credits are non-refundable. Required scope: billing:read. The API key is bound to exactly one workspace, institution and environment. There is no workspace override; this binding applies to every read and export. [Product scope](https://docs.amlok.io/api-reference/products-and-endpoints.md) · [Processing lifecycle](https://docs.amlok.io/api-reference/processing-lifecycle.md) · [Errors](https://docs.amlok.io/api-reference/errors.md) ## OpenAPI ````yaml openapi/amlok-v1.json GET /v1/billing/account openapi: 3.1.0 info: title: AMLOK API version: 1.4.2 description: >- API reference for AMLOK 1.4.2, with example requests and responses. Configure your institution-issued environment URL before making requests. x-source-workbook: >- https://docs.google.com/spreadsheets/d/14pU2PLv9JDda8gAa1367hipa2oJQB260fIJthevrp10/edit servers: - url: https://api.example.com description: Set the server URL to your institution-issued AMLOK environment URL. security: - BearerAuth: [] tags: - name: Platform description: Platform operations. - name: Identity description: Identity operations. - name: Banking description: Banking operations. - name: Payments description: Payments operations. - name: Commerce description: Commerce operations. - name: Accounting description: Accounting operations. - name: Inventory description: Inventory operations. - name: Lending description: Lending operations. - name: Liens description: Liens operations. - name: Risk description: Risk operations. - name: Operations description: Operations operations. - name: Webhooks description: Webhooks operations. - name: Reporting description: Reporting operations. paths: /v1/billing/account: get: tags: - Reporting summary: Retrieve billing account description: >- Read the unified workspace billing policy, CAD 200 default automatic top-up trigger, and CAD 500 minimum customer-funded top-up. The client portal manages card or bank-account payment methods, automatic top-ups and cancellation; enterprise clients can also use their dedicated account manager. The public API provides reporting only. Cancellation is available at any time with no notice period. Processing, usage deductions, and upcoming top-ups stop immediately when cancellation is submitted or set by the account manager. Cancel unfinished work without another debit. Full closure is at the end of the request month, with an immediate refund of all unused credits, including promotional credits, to the saved portal bank account. Data is deleted after the month closes and necessary final information is generated. Used credits are non-refundable. Required scope: billing:read. The API key is bound to exactly one workspace, institution and environment. There is no workspace override; this binding applies to every read and export. operationId: WA001 parameters: - name: snapshot_id in: query required: false description: >- Reuse an immutable snapshot from this workspace. Omit to use a current snapshot. Cursors bind this value; unknown snapshots return 404 and conflicting cursor parameters return 400. schema: type: string example: billing_snapshot_example responses: '200': description: Successful response. headers: X-Request-ID: schema: type: string ETag: schema: type: string example: '"1:billing_snapshot_example"' X-Billing-Snapshot-ID: description: >- Snapshot for this entire response and all pages. Reuse for cross-report reconciliation. schema: type: string minLength: 1 example: billing_snapshot_example content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/BillingAccount' meta: $ref: '#/components/schemas/ResponseMeta' required: - data - meta examples: synthetic: summary: Synthetic retrieve billing account value: data: id: billing_account_example object: billing_account record_version: 1 created_at: '2026-10-23T14:00:00Z' updated_at: '2026-10-23T14:00:00Z' workspace_id: wsp_example currency: CAD agreement_id: agr_example agreement_version: '3' minimum_monthly_commitment: '1000.00' payment_for_12_months: '12000.00' term_start: '2026-10-01T00:00:00Z' term_end: '2027-10-01T00:00:00Z' renewal_payment_at: '2027-10-01T00:00:00Z' credit_type: prepaid_service_credits outflow_policy: product_usage_or_final_cancellation_refund refund_policy: full_unused_balance_on_final_cancellation access: reporting_only portal_controls: - payment_methods - automatic_top_ups - account_cancellation funding_methods: - card - bank_account default_auto_top_up_threshold: '200.00' minimum_top_up_threshold: '200.00' payment_frequency: every_12_months cancellation_notice_days: 0 closure_timing: end_of_request_month processing_cutoff: immediate_on_cancellation status: active cancellation_requested_at: null scheduled_closure_at: null minimum_top_up_amount: '500.00' auto_top_up_enabled: true auto_top_up_threshold: '200.00' auto_top_up_amount: '500.00' auto_top_up_balance_basis: available_credits refund_destination: saved_portal_bank_account policy_version: unified-workspace-credits snapshot_id: billing_snapshot_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete '400': $ref: '#/components/responses/Error400' '401': $ref: '#/components/responses/Error401' '403': $ref: '#/components/responses/Error403' '404': $ref: '#/components/responses/Error404' '409': $ref: '#/components/responses/Error409' '412': $ref: '#/components/responses/Error412' '422': $ref: '#/components/responses/Error422' '429': $ref: '#/components/responses/Error429' '500': $ref: '#/components/responses/Error500' '503': $ref: '#/components/responses/Error503' security: - BearerAuth: [] x-codeSamples: - lang: Shell label: cURL source: |- curl --request GET --fail-with-body --max-time 30 \ "${AMLOK_API_BASE_URL}/v1/billing/account?snapshot_id=billing_snapshot_example" \ --header "Authorization: Bearer ${AMLOK_API_KEY}" \ --header "Accept: application/json" - lang: Python source: |- import os import requests base_url = os.environ["AMLOK_API_BASE_URL"].rstrip("/") headers = {'Accept': 'application/json'} headers["Authorization"] = "Bearer " + os.environ["AMLOK_API_KEY"] response = requests.request( "GET", base_url + "/v1/billing/account?snapshot_id=billing_snapshot_example", headers=headers, timeout=30, allow_redirects=False, ) response.raise_for_status() print(response.json()) - lang: JavaScript label: Node.js source: >- const baseUrl = process.env.AMLOK_API_BASE_URL; const apiKey = process.env.AMLOK_API_KEY; if (!baseUrl || !apiKey) throw new Error("Configure AMLOK_API_BASE_URL and AMLOK_API_KEY"); const headers = { "Accept": "application/json" }; headers.Authorization = `Bearer ${apiKey}`; const response = await fetch(baseUrl.replace(/\/$/, "") + "/v1/billing/account?snapshot_id=billing_snapshot_example", { method: "GET", headers, redirect: "error", signal: AbortSignal.timeout(30000), }); if (!response.ok) throw new Error(`AMLOK returned HTTP ${response.status}`); console.log(await response.json()); components: schemas: BillingAccount: type: object properties: id: type: string minLength: 1 object: type: string minLength: 1 record_version: type: integer minimum: 1 created_at: type: string format: date-time updated_at: type: string format: date-time workspace_id: type: string minLength: 1 description: Authorized workspace whose unified billing account owns this report. currency: type: string enum: - CAD agreement_id: type: string minLength: 1 agreement_version: type: string minLength: 1 minimum_monthly_commitment: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: Nonnegative CAD amount, exact decimal string in major units. payment_for_12_months: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: Nonnegative CAD amount, exact decimal string in major units. term_start: type: string format: date-time term_end: type: string format: date-time renewal_payment_at: type: string format: date-time credit_type: type: string enum: - prepaid_service_credits outflow_policy: type: string enum: - product_usage_or_final_cancellation_refund refund_policy: type: string enum: - full_unused_balance_on_final_cancellation access: type: string enum: - reporting_only portal_controls: type: array items: type: string enum: - payment_methods - automatic_top_ups - account_cancellation funding_methods: type: array items: type: string enum: - card - bank_account default_auto_top_up_threshold: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: Nonnegative CAD amount, exact decimal string in major units. const: '200.00' payment_frequency: type: string enum: - every_12_months cancellation_notice_days: type: integer const: 0 closure_timing: type: string enum: - end_of_request_month processing_cutoff: type: string enum: - immediate_on_cancellation status: type: string enum: - active - cancellation_pending cancellation_requested_at: anyOf: - type: string format: date-time - type: 'null' scheduled_closure_at: anyOf: - type: string format: date-time - type: 'null' minimum_top_up_threshold: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: Nonnegative CAD amount, exact decimal string in major units. const: '200.00' minimum_top_up_amount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: Nonnegative CAD amount, exact decimal string in major units. const: '500.00' auto_top_up_enabled: type: boolean auto_top_up_threshold: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: >- Actual configured threshold, at least CAD 200. Compare against available_credits. Only the portal can change it. auto_top_up_amount: type: string pattern: ^(0|[1-9][0-9]*)\.[0-9]{2}$ description: >- Actual configured amount, at least CAD 500. Only the portal can change it. auto_top_up_balance_basis: type: string enum: - available_credits refund_destination: type: string enum: - saved_portal_bank_account policy_version: type: string minLength: 1 snapshot_id: type: string minLength: 1 description: >- Immutable workspace billing snapshot used for this financial representation. required: - id - object - record_version - created_at - updated_at - workspace_id - currency - agreement_id - agreement_version - minimum_monthly_commitment - payment_for_12_months - term_start - term_end - renewal_payment_at - credit_type - outflow_policy - refund_policy - access - portal_controls - funding_methods - default_auto_top_up_threshold - payment_frequency - cancellation_notice_days - closure_timing - processing_cutoff - status - cancellation_requested_at - scheduled_closure_at - minimum_top_up_threshold - minimum_top_up_amount - auto_top_up_enabled - auto_top_up_threshold - auto_top_up_amount - auto_top_up_balance_basis - refund_destination - policy_version - snapshot_id additionalProperties: false ResponseMeta: type: object properties: request_id: type: string description: AMLOK request correlation ID. schema_version: type: string description: Serialization contract version. generated_at: type: string format: date-time description: Response generation time, not source data freshness. data_status: $ref: '#/components/schemas/Enum_data_status' description: Completeness of this response within its declared scope. coverage: anyOf: - $ref: '#/components/schemas/Coverage' - type: 'null' description: Requested and achieved source/time coverage. required: - request_id - schema_version - generated_at - data_status Enum_data_status: type: string enum: - complete - partial - unavailable - pending Coverage: type: object properties: requested_from: anyOf: - type: string format: date - type: 'null' description: Inclusive start requested. requested_to: anyOf: - type: string format: date - type: 'null' description: Exclusive end requested. available_from: anyOf: - type: string format: date - type: 'null' description: Earliest actual coverage. available_to: anyOf: - type: string format: date - type: 'null' description: Exclusive end of actual coverage. source_ids: type: array items: type: string description: Sources actually contributing. missing_intervals: type: array items: $ref: '#/components/schemas/Interval' description: Known gaps within requested scope. jurisdictions_completed: anyOf: - type: array items: type: string - type: 'null' description: Completed geographic search scope when applicable. required: - source_ids - missing_intervals ErrorEnvelope: type: object properties: error: $ref: '#/components/schemas/Error' meta: $ref: '#/components/schemas/ResponseMeta' required: - error - meta Interval: type: object properties: from: type: string format: date description: Inclusive interval start. to: type: string format: date description: Exclusive interval end. required: - from - to Error: type: object properties: code: type: string description: Stable machine-readable error code. message: type: string description: Safe caller-facing explanation. field: anyOf: - type: string - type: 'null' description: Invalid request field when relevant. retryable: type: boolean description: Whether retry may succeed without changing the request. request_id: type: string description: Correlation identifier for support. required: - code - message - retryable - request_id responses: Error400: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_request: summary: invalid_request value: error: code: invalid_request message: Malformed input, unknown parameter or incompatible filters. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete unsupported_parameter: summary: unsupported_parameter value: error: code: unsupported_parameter message: Historical query or filter not implemented on this resource. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete validation_error: summary: validation_error value: error: code: validation_error message: >- A field, projection, or request value is invalid. Inspect error.field. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error401: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: unauthenticated: summary: unauthenticated value: error: code: unauthenticated message: Missing, expired or invalid credential. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error403: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: forbidden: summary: forbidden value: error: code: forbidden message: Tenant scope or field/product entitlement missing. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error404: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: not_found: summary: not_found value: error: code: not_found message: Record does not exist or is not visible in this tenant. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error409: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: idempotency_conflict: summary: idempotency_conflict value: error: code: idempotency_conflict message: Same key was reused with different intended input. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete invalid_state: summary: invalid_state value: error: code: invalid_state message: >- The operation is unavailable in the current resource or account state. Operational commands are unavailable after cancellation is submitted. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error412: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: version_conflict: summary: version_conflict value: error: code: version_conflict message: If-Match or approved action version is stale. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error422: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid_search_scope: summary: invalid_search_scope value: error: code: invalid_search_scope message: Missing or unsupported jurisdiction/search mode. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete invalid_money: summary: invalid_money value: error: code: invalid_money message: >- Invalid decimal, missing required currency or incompatible currency pair. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete insufficient_evidence: summary: insufficient_evidence value: error: code: insufficient_evidence message: Required decision or metric prerequisites are missing. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete workload_limit_exceeded: summary: workload_limit_exceeded value: error: code: workload_limit_exceeded message: >- The agreed workload limit cannot cover this work. No automatic tier upgrade or surcharge occurs. Contact AMLOK to agree expanded scope. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error429: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example Retry-After: description: >- Delay in seconds or an HTTP-date. The example is illustrative, not a contractual quota. schema: type: string example: '30' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate_limited: summary: rate_limited value: error: code: rate_limited message: AMLOK tenant quota or upstream throttle. retryable: true request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error500: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: internal_error: summary: internal_error value: error: code: internal_error message: Unexpected AMLOK processing error. retryable: false request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete Error503: description: Request failed. Inspect error.code and error.retryable. headers: X-Request-ID: description: AMLOK response correlation identifier. schema: type: string example: req_example content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: source_unavailable: summary: source_unavailable value: error: code: source_unavailable message: Required source temporarily unavailable. retryable: true request_id: req_example meta: request_id: req_example schema_version: 1.4.2 generated_at: '2026-10-23T14:00:00Z' data_status: complete securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: API key description: >- Server-to-server API key bound to exactly one workspace, institution tenant and environment. No caller-supplied workspace override is accepted. Do not use in public browser code. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.