Invoices

Invoices are the bills Zeitstrom issues to your organization for its subscription and add-ons. The API is read-only: you can list issued invoices, download each one as a ZUGFeRD e-invoice PDF, and preview the upcoming invoice before it is issued. A typical integration fetches new invoice PDFs once a month and files them automatically into an accounting workflow such as DATEV.

If your API token is restricted to specific permissions, it needs the invoices:view scope for the list, upcoming-invoice preview, PDF, and HTML endpoints. Requests without the required permission return 403 Forbidden.

The Invoice Object

All fields are read-only. Monetary amounts are in EUR.

Name
id
Type
string (UUID)
Description
Unique identifier for the invoice.
Name
created_at
Type
string (ISO 8601, local time)
Description
When the invoice record was created.
Name
number
Type
string
Description
The invoice number as printed on the document, e.g. ZEIT-10428260601. Unique across all invoices.
Name
date
Type
string (YYYY-MM-DD)
Description
The issue date of the invoice.
Name
total_net
Type
number
Description
Net total in EUR — the sum of all line item amounts.
Name
tax
Type
number
Description
VAT amount in EUR, rounded to two decimal places. 0 for reverse-charge invoices issued to customers with a non-German VAT ID.
Name
total_gross
Type
number
Description
Gross total in EUR (total_net plus tax).
Name
daterange
Type
object
Description
The billing period covered by the invoice, as an object with start and end dates (YYYY-MM-DD). Derived from the invoice's line items; for subscription line items the end of the paid subscription period is used. If the invoice has no line items, both values fall back to the invoice date.
Name
pdf
Type
string (URL)
Description
A pre-signed download link for the archived PDF that was stored when the invoice was issued. The link expires after two hours, so fetch a fresh invoice object whenever you need to download the file. To retrieve the document as a ZUGFeRD e-invoice, use the PDF endpoint instead.

GET/api/v2/billing/invoices/

List all Invoices

Retrieve a paginated list of your organization's invoices, ordered by issue date with the newest invoice first.

Query Parameters

Name
ids
Type
string
Description
Restrict the result set to specific invoices by passing a pipe-separated list of invoice IDs (UUIDs). Invalid UUIDs are ignored.
Name
limit
Type
integer
Description
Number of results per page. Defaults to 100, maximum 1000.
Name
offset
Type
integer
Description
Number of results to skip for pagination. Defaults to 0.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/billing/invoices/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "7c9e2b14-53af-4c14-9f0b-2e8a41c76d90",
      "created_at": "2026-06-01T04:02:11",
      "number": "ZEIT-10428260601",
      "date": "2026-06-01",
      "total_net": 49.9,
      "tax": 9.48,
      "total_gross": 59.38,
      "daterange": {
        "start": "2026-06-01",
        "end": "2026-06-30"
      },
      "pdf": "https://s3.eu-central-1.amazonaws.com/…/ZEIT-10428260601.pdf?…"
    },
    {
      "id": "3fa1c6d8-9b72-4e05-8c34-6d1f5a20b7e4",
      "created_at": "2026-05-01T04:01:37",
      "number": "ZEIT-10428260501",
      "date": "2026-05-01",
      "total_net": 44.91,
      "tax": 8.53,
      "total_gross": 53.44,
      "daterange": {
        "start": "2026-05-01",
        "end": "2026-05-31"
      },
      "pdf": "https://s3.eu-central-1.amazonaws.com/…/ZEIT-10428260501.pdf?…"
    }
  ]
}

GET/api/v2/billing/invoices/:id/

Retrieve an Invoice

Get a single invoice by its ID.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/billing/invoices/7c9e2b14-53af-4c14-9f0b-2e8a41c76d90/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"

Response

{
  "id": "7c9e2b14-53af-4c14-9f0b-2e8a41c76d90",
  "created_at": "2026-06-01T04:02:11",
  "number": "ZEIT-10428260601",
  "date": "2026-06-01",
  "total_net": 49.9,
  "tax": 9.48,
  "total_gross": 59.38,
  "daterange": {
    "start": "2026-06-01",
    "end": "2026-06-30"
  },
  "pdf": "https://s3.eu-central-1.amazonaws.com/…/ZEIT-10428260601.pdf?…"
}

GET/api/v2/billing/invoices/next/pdf/

Preview the Upcoming Invoice

Render a draft PDF of your organization's upcoming invoice, built from all billing line items that are still pending. The document carries an "Entwurf" (draft) watermark and a preview invoice number — it is not an issued invoice and does not appear in the invoice list. Use it to check the expected amount of the next charge before it is billed.

The response is a binary PDF (Content-Type: application/pdf).

Request

curl -X GET "https://api.zeitstrom.com/api/v2/billing/invoices/next/pdf/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o upcoming-invoice.pdf

GET/api/v2/billing/invoices/:id/pdf/

Download an Invoice PDF

Download an issued invoice as a ZUGFeRD e-invoice: a PDF with an embedded machine-readable Factur-X XML (EN 16931 profile), suitable for automated processing in German accounting systems such as DATEV. Prefer this endpoint over the pdf link on the invoice object when your workflow relies on the embedded e-invoice data.

The response is a binary PDF (Content-Type: application/pdf) served with a Content-Disposition filename of <number>.pdf.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/billing/invoices/7c9e2b14-53af-4c14-9f0b-2e8a41c76d90/pdf/" \
  -H "Authorization: Token <YOUR_API_TOKEN>" \
  -o ZEIT-10428260601.pdf

GET/api/v2/billing/invoices/:id/html/

Retrieve an Invoice as HTML

Render an issued invoice as an HTML document (Content-Type: text/html), e.g. to display it inside your own billing portal.

Request

curl -X GET "https://api.zeitstrom.com/api/v2/billing/invoices/7c9e2b14-53af-4c14-9f0b-2e8a41c76d90/html/" \
  -H "Authorization: Token <YOUR_API_TOKEN>"