REST DocumentationInvoicesGET List invoices, optionally filtered and paginated

List invoices, optionally filtered and paginated

Returns invoice header data; with include=items every invoice also carries its positions, in the form of GET /invoices/{invoice}/items. Attachments are listed via GET /invoices/{invoice}/attachments.

Availability: Full version only — a Clock instance answers 404 for this endpoint.

Request

GET /api/v1/invoices
curl --request GET \
     --url 'https://www.zep-online.de/zepinstanz/next/api/v1/invoices' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer {token}'

Query parameters

  • Name
    perPage
    Type
    integer, nullable
    Description

    Ignored on this endpoint — send limit instead. Any value given here is replaced by limit, or by the default when limit is absent.

  • Name
    page
    Type
    integer, nullable
    Description

    The page of results to return, counting from 1.

  • Name
    orderBy
    Type
    string, nullable
    Description

    Name of the field to sort by.

  • Name
    order
    Type
    string, nullable
    Description

    Sort direction, ascending or descending.

    One of: "asc", "desc"

  • Name
    limit
    Type
    integer, nullable
    Description

    The number of records per page, 1 to 200. Defaults to 15.

  • Name
    modified_after
    Type
    string (date-time)
    Description

    Only return invoices modified after this timestamp (ISO 8601, or “Y-m-d H:i:s”). Changing a position does not necessarily change the invoice’s own modified timestamp.

  • Name
    modified_before
    Type
    string (date-time)
    Description

    Only return invoices modified before or at this timestamp (ISO 8601, or “Y-m-d H:i:s”).

  • Name
    invoice_number[]
    Type
    array of string, nullable
    Description
  • Name
    start_date
    Type
    string (date)
    Description

    Only return invoices dated on or after this day (Y-m-d).

  • Name
    end_date
    Type
    string (date)
    Description

    Only return invoices dated on or before this day (Y-m-d); not before start_date.

  • Name
    include
    Type
    string
    Description

    Comma-separated list of related data to embed in every invoice; only “items” is supported.

Response

{
  "data": [
    {
      "invoice_number": "20240001",
      "billing_kind": {
        "id": 1,
        "name": "Abrechnung"
      },
      "date": "2024-07-20T00:00:00.000000Z",
      "amount": 1.5,
      "net_amount": 965.84,
      "tax_amount": 168.45,
      "tax_breakdown": [
        {
          "rate": 19,
          "net_amount": 840.34,
          "tax_amount": 159.66
        },
        {
          "rate": 7,
          "net_amount": 125.5,
          "tax_amount": 8.79
        }
      ],
      "status": {
        "id": 1,
        "name": "Billed"
      },
      "currency": "EUR",
      "correction_date": "2026-10-20 17:01:39",
      "payment_terms_date": "2024-06-01",
      "payment_terms": 30,
      "address": "Musterstraße 123",
      "customer_address_id": 1,
      "contact_id": 1,
      "billing_address": {
        "id": 1,
        "name": "EU",
        "address": "Musterstraße 123",
        "zip_code": "10115",
        "city": "Berlin",
        "country": "Deutschland"
      },
      "debtor": "10042",
      "email_sent_at": "string",
      "email_recipient": "string",
      "customer_number": "K-12345",
      "title": "Dr.",
      "type": {
        "id": 1,
        "name": "Payment Request"
      },
      "note": "Familienurlaub",
      "creator_username": "max.mustermann",
      "created": "2024-07-20T11:30:00.000000Z",
      "modified": "2024-07-20T12:30:00.000000Z",
      "items": [
        {
          "id": 1,
          "project_id": 16,
          "customer_number": "K-12345",
          "quantity": 8,
          "unit_price": 95,
          "unit": "h",
          "currency": "EUR",
          "invoice_text": "Consulting"
        }
      ]
    }
  ],
  "links": {
    "first": "string",
    "last": "string",
    "prev": "string",
    "next": "string"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "links": [
      {
        "url": "string",
        "label": "string",
        "active": true
      }
    ],
    "path": "string",
    "per_page": 1,
    "to": 1,
    "total": 1
  }
}

Response fields

  • Name
    invoice_number
    Type
    string
    Description

    The invoice number, unique per invoice and formatted per tenant.

  • Name
    billing_kind
    Type
    object
    Description

    How the invoice groups its positions — by project, by activity, or a manual selection.

  • Name
    billing_kind.id
    Type
    integer
    Description

    The stored value. Compare against this, not against name.

  • Name
    billing_kind.name
    Type
    string
    Description

    The human-readable label, delivered in the tenant’s language. Do not parse it.

    One of: "Abrechnung", "Credit Memo"

  • Name
    date
    Type
    string
    Description

    The date the invoice was issued.

  • Name
    amount
    Type
    number
    Description

    The invoice total, including tax (the gross amount).

  • Name
    net_amount
    Type
    number, nullable
    Description

    The invoice total without tax, in the invoice’s currency; null when the split cannot be determined.

  • Name
    tax_amount
    Type
    number, nullable
    Description

    The tax contained in the invoice total, in the invoice’s currency; null when the split cannot be determined.

  • Name
    tax_breakdown
    Type
    array of object, nullable
    Description

    The net and tax amount per VAT rate, one entry for a single rate; null when the split cannot be determined.

  • Name
    tax_breakdown.rate
    Type
    number
    Description
  • Name
    tax_breakdown.net_amount
    Type
    number
    Description
  • Name
    tax_breakdown.tax_amount
    Type
    number
    Description
  • Name
    status
    Type
    object
    Description

    The invoice’s processing state — planned, approved, billed or cancelled.

  • Name
    status.id
    Type
    integer
    Description

    The stored value. Compare against this, not against name.

  • Name
    status.name
    Type
    string
    Description

    The human-readable label, delivered in the tenant’s language. Do not parse it.

    One of: "Billed", "Canceled", "In Correction"

  • Name
    currency
    Type
    string
    Description

    The three-letter currency code the invoice amount is stated in.

  • Name
    correction_date
    Type
    string, nullable
    Description

    The date a correcting credit note was issued, null until this invoice has been corrected. Raw value in German local time (Europe/Berlin) without a zone, format Y-m-d H:i:s; ISO 8601 follows in the next API version.

  • Name
    payment_terms_date
    Type
    string
    Description

    The date payment is due, calculated from payment_terms.

  • Name
    payment_terms
    Type
    integer
    Description

    The number of days after the invoice date within which payment is due.

  • Name
    address
    Type
    string
    Description

    The billing address printed on the invoice.

  • Name
    customer_address_id
    Type
    integer, nullable
    Description

    The customer address the invoice was written to; null when none is stored. address keeps the text as printed, which may have been edited by hand.

  • Name
    contact_id
    Type
    integer, nullable
    Description

    The customer contact the invoice is addressed to; null when none is stored.

  • Name
    billing_address
    Type
    object (CustomerAddress), nullable
    Description

    The customer address the invoice was written to, in its current state, in the form of the customer’s addresses; null when none is stored or it has been deleted.

  • Name
    billing_address.id
    Type
    integer
    Description

    The address’s unique identifier.

  • Name
    billing_address.name
    Type
    string
    Description

    The recipient name printed on this address.

  • Name
    billing_address.name_additional
    Type
    string, nullable
    Description

    An additional name line, printed below name.

  • Name
    billing_address.address
    Type
    string, nullable
    Description

    The first address line (street and house number).

  • Name
    billing_address.address_line_2
    Type
    string, nullable
    Description

    An optional second address line.

  • Name
    billing_address.address_line_3
    Type
    string, nullable
    Description

    An optional third address line.

  • Name
    billing_address.zip_code
    Type
    string, nullable
    Description

    The postal code.

  • Name
    billing_address.city
    Type
    string, nullable
    Description

    The city this address is located in.

  • Name
    billing_address.country
    Type
    string, nullable
    Description

    The country name.

  • Name
    billing_address.is_default
    Type
    boolean, nullable
    Description

    Whether this is the customer’s default address.

  • Name
    billing_address.is_billing_address
    Type
    boolean, nullable
    Description

    Whether invoices are sent to this address.

  • Name
    billing_address.is_shipping_address
    Type
    boolean, nullable
    Description

    Whether deliveries are sent to this address.

  • Name
    billing_address.email
    Type
    string, nullable
    Description

    The e-mail address documents for this address are sent to.

  • Name
    billing_address.email_cc
    Type
    string, nullable
    Description

    An additional e-mail address copied (CC) on documents sent to this address.

  • Name
    billing_address.email_bcc
    Type
    string, nullable
    Description

    An additional e-mail address blind-copied (BCC) on documents sent to this address.

  • Name
    billing_address.debtor
    Type
    string, nullable
    Description

    The debtor number of this address (licence module Inovex); null when empty.

  • Name
    billing_address.country_code
    Type
    string, nullable
    Description

    The ISO country code used for e-invoicing (ZUGFeRD/XRechnung).

  • Name
    billing_address.inactive
    Type
    boolean, nullable
    Description

    Whether this address is inactive and no longer used.

  • Name
    billing_address.machine_readable_invoice_version
    Type
    object, nullable
    Description

    The machine-readable e-invoice format (e.g. ZUGFeRD, XRechnung) this address supports, if any.

  • Name
    debtor
    Type
    string, nullable
    Description

    The debtor number of the invoice as stored when it was issued (licence module Inovex); null without one.

  • Name
    email_sent_at
    Type
    string, nullable
    Description

    The timestamp the invoice was emailed to the customer, present only once it has been sent.

  • Name
    email_recipient
    Type
    string, nullable
    Description

    The email address the invoice was sent to, present only once an email has gone out.

  • Name
    customer_number
    Type
    string
    Description

    The customer this invoice was billed to.

  • Name
    title
    Type
    string
    Description

    The invoice’s title line, printed above its positions.

  • Name
    type
    Type
    object, nullable
    Description

    The invoice type: ZA (payment request), SR (final invoice) or TSR (partial final invoice); null when the invoice has none.

  • Name
    type.id
    Type
    integer
    Description

    The stored value. Compare against this, not against name.

  • Name
    type.name
    Type
    string
    Description

    The human-readable label, delivered in the tenant’s language. Do not parse it.

    One of: "Payment Request", "Final Invoice", "Partial Final Invoice"

  • Name
    note
    Type
    string, nullable
    Description

    An internal note attached to the invoice, not printed on the document.

  • Name
    creator_username
    Type
    string, nullable
    Description

    The username of the employee who created the invoice document — after a correction, of the employee who corrected it; null when no invoice document is stored.

  • Name
    created
    Type
    string (date-time), nullable
    Description

    When the invoice record was first created.

  • Name
    modified
    Type
    string (date-time), nullable
    Description

    When the invoice record was last changed.

  • Name
    items
    Type
    array of InvoiceItem
    Description

    The invoice’s positions, in the form of GET /invoices/{invoice}/items; present only with include=items, an empty list when the invoice has none.

  • Name
    items.id
    Type
    integer
    Description

    Unique identifier of the invoice position.

  • Name
    items.project_id
    Type
    integer, nullable
    Description

    The project this position bills against.

  • Name
    items.customer_number
    Type
    string, nullable
    Description

    The customer the position’s project belongs to.

  • Name
    items.from
    Type
    string (date-time), nullable
    Description

    Start of the service period this position covers.

  • Name
    items.to
    Type
    string (date-time), nullable
    Description

    End of the service period this position covers.

  • Name
    items.repetition
    Type
    integer, nullable
    Description

    How many times this position recurs, for repeating positions.

  • Name
    items.quantity
    Type
    number, nullable
    Description

    The billed quantity, in the position’s unit.

  • Name
    items.unit_price
    Type
    number, nullable
    Description

    The price per unit, in the position’s currency.

  • Name
    items.unit
    Type
    string, nullable
    Description

    The unit the quantity and price are measured in.

  • Name
    items.currency
    Type
    string, nullable
    Description

    The three-letter currency code of unit_price and the derived amounts.

  • Name
    items.language
    Type
    string, nullable
    Description

    The language the invoice text is written in.

  • Name
    items.status
    Type
    object
    Description

    The position’s processing state — planned, approved, billed or cancelled.

  • Name
    items.kind
    Type
    object
    Description

    What this position bills for — working hours, receipts, a flat fee or a manual entry.

  • Name
    items.invoice_number
    Type
    string, nullable
    Description

    The invoice this position was billed on, once it has been billed.

  • Name
    items.cancellation_credit_invoice_number
    Type
    string, nullable
    Description

    The invoice number of the cancelled invoice this credit position refers to; null for every other position.

  • Name
    items.invoice_text
    Type
    string, nullable
    Description

    The text printed for this position on the invoice.

  • Name
    items.sorting
    Type
    integer, nullable
    Description

    The position’s order among the invoice’s other positions.

  • Name
    items.contains_working_hours
    Type
    boolean, nullable
    Description

    Whether this position bills recorded working hours.

  • Name
    items.contains_receipts
    Type
    boolean, nullable
    Description

    Whether this position bills recorded receipts.

  • Name
    items.contains_travel_expenses
    Type
    boolean, nullable
    Description

    Whether this position bills recorded travel expenses.

  • Name
    items.planned_amount
    Type
    number, nullable
    Description

    The forecast amount for this position while it is only planned or approved.

  • Name
    items.planned_date
    Type
    string (date-time)
    Description

    The planned invoice date this position is scheduled to be billed on; the list filters act on this field, not on from/to.

  • Name
    items.billed_amount
    Type
    number, nullable
    Description

    The billed amount, net of tax; 0 while the position is only planned or approved and not yet cancelled.

  • Name
    items.billed_date
    Type
    string, nullable
    Description

    The date of the invoice this position was actually billed on.

  • Name
    items.vat
    Type
    number, nullable
    Description

    The VAT percentage rate applied to this position.

  • Name
    items.project_task_id
    Type
    integer, nullable
    Description

    The project task this position bills against, if the project uses tasks.

  • Name
    items.ticket_id
    Type
    integer, nullable
    Description

    The ticket this position bills against, if it originates from a ticket.

  • Name
    items.article_id
    Type
    integer, nullable
    Description

    The article this position bills, if it was created from the article catalogue.

  • Name
    items.revenueAccounts
    Type
    array of object
    Description

    The bookkeeping accounts this position’s revenue is split across, present only where revenue accounts are kept.

  • Name
    items.sales_manager
    Type
    string
    Description

    The employee carrying revenue responsibility for this position. Only on instances with the MOD_HHPBERLIN extension. Not a generally available feature.

Generated from the OpenAPI specification — edit the source code, not this page.