#Billing

Retrieve tenant billing overviews, invoices, invoice recipients, invoice PDFs, and Stripe billing portal sessions for authorised portal users.

• Production API: https://api.aidial.ai
• Version prefix: /v1

This page omits environment-specific host names, internal topology, and deployment details.

Billing authentication: Customer billing endpoints on this page require Authorization: Bearer <jwt> for a portal user with client_manager, client_admin, or partner_admin scope for the requested client_id. Billing routes use the shared authentication dependency, where X-API-Key is evaluated before Authorization: Bearer; do not send both headers on billing requests, because the API key will be used and bearer-only billing routes will fail closed.

Bearer JWT validation requires the API runtime to have all of these settings configured, with no fallback defaults:

• ZITADEL_ISSUER
• ZITADEL_AUDIENCE
• ZITADEL_JWKS_URL

Billing errors: Billing service and validation errors use a domain-specific error format ({code, message}) instead of the general error shape. Authentication failures raised before the billing route runs use the general error shape. See Error Responses for details.

#Implemented Route Map

This table is the customer/Portal-facing inventory for published Billing surfaces. The detailed contracts below remain the source for field-level examples.

#GET /v1/billing/overview

Returns a billing overview for your tenant.

Authentication: Bearer required (client_manager, client_admin, or partner_admin; internal aidial_admin and aidial_operator reads require an explicit client_id)

#Parameters

#Response

Usage values are derived from the resolved tenant and data environment. Included-minute usage is queried from the routed tenant data store for the resolved (client_id, data_env). If that routed usage lookup is unavailable, the overview still returns billing plan and invoice data with usage_status: "unavailable" and usage amount fields set to null. Metered usage lines come from the API host's local API metadata store aggregation records.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/billing/overview?client_id=client_example_001" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT"

Response (200 OK):

{
  "billing": {
    "client_id": "client_example_001",
    "billing_period_start": "2026-03-01T00:00:00Z",
    "billing_period_end": "2026-04-01T00:00:00Z",
    "plan_name": "Professional",
    "currency": "AUD",
    "monthly_fee_amount": 299.0,
    "usage_status": "available",
    "included_minutes": 500.0,
    "used_minutes": 473.3,
    "remaining_minutes": 26.7,
    "estimated_overage_amount": 0.0,
    "invoice_status": "current",
    "next_invoice_date": "2026-04-01T00:00:00Z",
    "last_invoice_total": 299.0,
    "metered_usage_lines": [],
    "metered_usage": null,
    "active_discounts": [],
    "discounted_monthly_fee_amount": null,
    "discount_calculation_available": true,
    "active_adjustments": [],
    "adjusted_monthly_fee_cents": null,
    "adjustment_calculation_available": true
  }
}

#GET /v1/billing/invoices

Returns a paginated list of invoices.

Authentication: Bearer required (client_manager, client_admin, or partner_admin; internal aidial_admin and aidial_operator reads require an explicit client_id)

#Parameters

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/billing/invoices?client_id=client_example_001&page_size=2" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT"

Response (200 OK):

{
  "invoices": {
    "items": [
      {
        "invoice_id": "in_example_001",
        "invoice_month": "2026-02",
        "invoice_number": "INV-2026-0042",
        "currency": "AUD",
        "subtotal_amount": 299.0,
        "tax_amount": 29.9,
        "total_amount": 328.9,
        "amount_paid": 328.9,
        "amount_due": 0.0,
        "status": "paid",
        "due_at": "2026-03-15T00:00:00Z",
        "paid_at": "2026-03-10T01:00:00Z",
        "issued_at": "2026-03-01T00:00:00Z",
        "pdf_available": true,
        "metered_line_items": null,
        "discount_line_items": null,
        "adjustment_line_items": null
      }
    ],
    "page_size": 2,
    "has_more": false,
    "next_page_token": null
  }
}

#GET /v1/billing/invoice-recipients

Returns masked billing invoice recipient email rows for the resolved tenant.

Authentication: Bearer required (client_manager, client_admin, or partner_admin)

#Parameters

#Response

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/billing/invoice-recipients?client_id=client_example_001" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT"

Response (200 OK):

{
  "recipients": [
    {
      "category": "invoices_and_receipts",
      "emails_masked": ["f******@e******.com"],
      "count": 1
    },
    {
      "category": "plan_billing_changes",
      "emails_masked": ["a******@e******.com"],
      "count": 1
    }
  ],
  "partial": false
}

#POST /v1/billing/invoice-recipients/unmask

Returns raw billing invoice recipient email rows for the resolved tenant and emits a server-side audit event.

Authentication: Bearer required (client_admin only)

#Request Body

#Response

Unmask audit metadata includes only a privacy-safe recipient-count bucket, never raw email addresses.

#Example

Request:

curl -X POST "https://api.aidial.ai/v1/billing/invoice-recipients/unmask" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "client_example_001"}'

Response (200 OK):

{
  "recipients": [
    {
      "category": "invoices_and_receipts",
      "emails": ["finance@example.com"],
      "count": 1
    },
    {
      "category": "plan_billing_changes",
      "emails": ["ap@example.com"],
      "count": 1
    }
  ],
  "partial": false
}

#GET /v1/billing/invoices/{invoice_id}/pdf

Downloads an invoice as a PDF file.

Authentication: Bearer required (client_manager, client_admin, or partner_admin)

#Parameters

#Response

Returns a PDF file (Content-Type: application/pdf) with Cache-Control: no-store, X-Content-Type-Options: nosniff, X-Frame-Options: DENY, a restrictive Content-Security-Policy, and an attachment filename based on the invoice identifier. Content-Length is included when available.

#Example

Request:

curl -X GET "https://api.aidial.ai/v1/billing/invoices/in_example_001/pdf?client_id=client_example_001" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT" \
  -o invoice.pdf

#POST /v1/billing/portal-session

Creates a Stripe billing portal session. The response contains a URL for redirecting the user's browser.

Authentication: Bearer required (client_manager, client_admin, or partner_admin)

Redirect pattern: Your server receives the session URL and redirects the user's browser. The return_to URL is where the user is redirected after they finish in the billing portal. The returned expires_at value is a short server-side UX hint for the portal redirect flow.

#Request Body

#Response

#Example

Request:

curl -X POST "https://api.aidial.ai/v1/billing/portal-session" \
  -H "Authorization: Bearer YOUR_PORTAL_JWT" \
  -H "Content-Type: application/json" \
  -d '{"client_id": "client_example_001", "return_to": "https://portal.example.com/billing"}'

Response (200 OK):

{
  "session_url": "https://billing.stripe.com/p/session/example_session_id",
  "expires_at": "2026-03-16T01:00:00Z"
}

#Data Scoping

Billing responses are scoped to the authenticated portal assignment:

• client_manager and client_admin can access their own client_id.
• partner_admin must request a client_id assigned to the bearer subject for the authenticated data_env.
• client_admin is required to unmask billing invoice recipient emails.
• aidial_admin and aidial_operator access is limited to explicitly documented internal read surfaces.
• Discount audit history is visible only to internal read roles and same-client client_admin/client_manager; client_staff, partners, API-key callers, and cross-client customer requests receive 404.
• Out-of-scope billing resources return 404 Not Found to avoid tenant enumeration.

The billing Stripe customer mapping is stored in the local API metadata store and decrypted through server-side decryption before provider calls. Raw encrypted fields, ciphertext, wrapped keys, and Stripe customer mapping secrets are not response fields.

Usage values in the billing overview are tenant-scoped. Included-minute usage is calculated from the routed tenant data store path for the authenticated (client_id, data_env). Metered billing summary and invoice line item metadata come from billing tables in the API metadata store and Stripe invoice data.

#Project Billing Helpers

The project router still exposes legacy billing helper endpoints used by cost-calculation and reporting paths:

These routes follow the project router's auth, ownership, and error semantics rather than the /v1/billing/* route envelope.

#Related Pages

• Authentication - API key and bearer authentication
• Projects - project billing configuration
• Error Responses - error format details
• Rate Limiting - handling 429 responses