---
title: Billing (tenant)
path: reference/api/billing
status: published
---

# Billing (tenant)

**17 endpoints** in this group. All paths are prefixed with `/api/v1`.

## Endpoints in this group

- [`GET /api/v1/billing/billing-profile`](#get-api-v1-billing-billing-profile) — Get Billing Profile
- [`PUT /api/v1/billing/billing-profile`](#put-api-v1-billing-billing-profile) — Upsert Billing Profile
- [`GET /api/v1/billing/invoices`](#get-api-v1-billing-invoices) — List Invoices
- [`GET /api/v1/billing/invoices/{invoice_id}`](#get-api-v1-billing-invoices-invoice-id) — Get Invoice
- [`GET /api/v1/billing/invoices/{invoice_id}/download`](#get-api-v1-billing-invoices-invoice-id-download) — Download Invoice Einvoice
- [`GET /api/v1/billing/invoices/{invoice_id}/pdf`](#get-api-v1-billing-invoices-invoice-id-pdf) — Download Invoice Pdf
- [`POST /api/v1/billing/invoices/{invoice_id}/send`](#post-api-v1-billing-invoices-invoice-id-send) — Send Invoice Email
- [`GET /api/v1/billing/overview`](#get-api-v1-billing-overview) — Get Billing Overview
- [`GET /api/v1/billing/payment-methods`](#get-api-v1-billing-payment-methods) — List Payment Methods
- [`POST /api/v1/billing/payment-methods`](#post-api-v1-billing-payment-methods) — Add Payment Method
- [`DELETE /api/v1/billing/payment-methods/{method_id}`](#delete-api-v1-billing-payment-methods-method-id) — Delete Payment Method
- [`POST /api/v1/billing/payment-methods/{method_id}/default`](#post-api-v1-billing-payment-methods-method-id-default) — Set Default Payment Method
- [`GET /api/v1/billing/payment-providers`](#get-api-v1-billing-payment-providers) — List Payment Providers
- [`GET /api/v1/billing/payment-providers/{slug}/config`](#get-api-v1-billing-payment-providers-slug-config) — Get Provider Config
- [`POST /api/v1/billing/payment-providers/{slug}/confirm`](#post-api-v1-billing-payment-providers-slug-confirm) — Confirm Provider Payment Method
- [`POST /api/v1/billing/payment-providers/{slug}/setup`](#post-api-v1-billing-payment-providers-slug-setup) — Setup Provider Payment Method
- [`GET /api/v1/billing/upcoming`](#get-api-v1-billing-upcoming) — Get Upcoming Invoice

---

### GET `/api/v1/billing/billing-profile` — Get Billing Profile {#get-api-v1-billing-billing-profile}

Get the billing profile for the authenticated tenant.

**Parameters**:

- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_Union_BillingProfileResponse__NoneType__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### PUT `/api/v1/billing/billing-profile` — Upsert Billing Profile {#put-api-v1-billing-billing-profile}

Create or update the billing profile for the authenticated tenant.

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `BillingProfileCreateUpdate` — {`company_name`, `address_line1`, `address_line2`, `postal_code` + 16 more}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_BillingProfileResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/invoices` — List Invoices {#get-api-v1-billing-invoices}

List invoices for the authenticated tenant.

**Parameters**:

- `page` (query, integer, optional)
- `page_size` (query, integer, optional)
- `status` (query, string, optional)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `PaginatedResponse_InvoiceResponse_` — {`data`, `pagination`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/invoices/{invoice_id}` — Get Invoice {#get-api-v1-billing-invoices-invoice-id}

Get invoice detail with line items.

**Parameters**:

- `invoice_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_InvoiceResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/invoices/{invoice_id}/download` — Download Invoice Einvoice {#get-api-v1-billing-invoices-invoice-id-download}

Download invoice in a specific e-invoicing format.

Supported formats:
- pdf: Standard PDF
- ubl: UBL 2.1 XML (Peppol BIS 3.0)
- xrechnung: UBL 2.1 XML (XRechnung / German CIUS)
- cii: UN/CEFACT CII XML
- zugferd / facturx: PDF/A-3 with embedded CII XML

**Parameters**:

- `invoice_id` (path, string, required)
- `format` (query, string, optional) — Format: pdf, ubl, xrechnung, cii, zugferd, facturx
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: —
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/invoices/{invoice_id}/pdf` — Download Invoice Pdf {#get-api-v1-billing-invoices-invoice-id-pdf}

Download invoice as PDF.

Generates a PDF on the fly from the invoice data and line items.
If a pre-generated pdf_url exists, redirects to it instead.

**Parameters**:

- `invoice_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: —
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/billing/invoices/{invoice_id}/send` — Send Invoice Email {#post-api-v1-billing-invoices-invoice-id-send}

Send an invoice by email to the billing contact.

Attaches the PDF and optional structured e-invoice (based on billing profile
preference). Transitions status from 'finalized' to 'sent'.

**Parameters**:

- `invoice_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_dict_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/overview` — Get Billing Overview {#get-api-v1-billing-overview}

Billing summary for the authenticated tenant.

**Parameters**:

- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_BillingOverviewResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/payment-methods` — List Payment Methods {#get-api-v1-billing-payment-methods}

List payment methods for the authenticated tenant.

**Parameters**:

- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_PaymentMethodResponse__` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/billing/payment-methods` — Add Payment Method {#post-api-v1-billing-payment-methods}

Add a new payment method (for direct provider_ref based flows).

**Parameters**:

- `authorization` (header, string, optional)


**Body**: `PaymentMethodCreateRequest` — {`provider_slug`, `method_type`, `return_url`}


**Responses**:

- `201` — Successful Response. Returns: `ApiResponse_PaymentMethodResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### DELETE `/api/v1/billing/payment-methods/{method_id}` — Delete Payment Method {#delete-api-v1-billing-payment-methods-method-id}

Deactivate a payment method.

**Parameters**:

- `method_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_dict_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/billing/payment-methods/{method_id}/default` — Set Default Payment Method {#post-api-v1-billing-payment-methods-method-id-default}

Set a payment method as the default.

**Parameters**:

- `method_id` (path, string, required)
- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_PaymentMethodResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/payment-providers` — List Payment Providers {#get-api-v1-billing-payment-providers}

List available payment providers and their supported methods.

**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_list_PaymentProviderResponse__` — {`data`, `meta`}


### GET `/api/v1/billing/payment-providers/{slug}/config` — Get Provider Config {#get-api-v1-billing-payment-providers-slug-config}

Get frontend SDK configuration for a payment provider.

**Parameters**:

- `slug` (path, string, required)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_dict_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/billing/payment-providers/{slug}/confirm` — Confirm Provider Payment Method {#post-api-v1-billing-payment-providers-slug-confirm}

Confirm a payment method after redirect or client-side setup.

Called after the user completes the setup flow (e.g., Stripe.js
confirmation or Mollie redirect return).

**Parameters**:

- `slug` (path, string, required)
- `authorization` (header, string, optional)


**Body**: `PaymentProviderConfirmRequest` — {`confirmation_data`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_PaymentMethodResponse_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### POST `/api/v1/billing/payment-providers/{slug}/setup` — Setup Provider Payment Method {#post-api-v1-billing-payment-providers-slug-setup}

Initiate payment method setup with a specific provider.

For card/SEPA via Stripe: returns a client_secret for Stripe.js.
For redirect-based providers (Mollie, Crypto): returns a redirect_url.

**Parameters**:

- `slug` (path, string, required)
- `authorization` (header, string, optional)


**Body**: `PaymentProviderSetupRequest` — {`method_type`, `return_url`}


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_dict_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}


### GET `/api/v1/billing/upcoming` — Get Upcoming Invoice {#get-api-v1-billing-upcoming}

Estimate the next invoice for the authenticated tenant.

Calculates based on current subscription prices and month-to-date usage.

**Parameters**:

- `authorization` (header, string, optional)


**Responses**:

- `200` — Successful Response. Returns: `ApiResponse_dict_` — {`data`, `meta`}
- `422` — Validation Error. Returns: `HTTPValidationError` — {`detail`}