Querying Documents | Moloni ON API
Moloni ONGuidesAPI ReferenceExplorer
Guides

Querying Documents

The API offers two approaches for retrieving documents:

Type-specific queries

Use these when you know the document type upfront. They return the full type (e.g. InvoiceRead) with all fields directly accessible, with no inline fragments needed.

Getting a single invoice

query {
  invoice(companyId: 1, documentId: 1234) {
    data {
      documentId
      number
      date
      expirationDate
      totalValue
      grossValue
      taxesValue
      status
      customer {
        customerId
        name
        vat
      }
      products {
        productId
        name
        qty
        price
        discount
      }
    }
  }
}

Listing invoices

query {
  invoices(companyId: 1, options: {
    pagination: { page: 1, qty: 20 }
    order: { field: date, sort: DESC }
  }) {
    data {
      documentId
      number
      date
      totalValue
      status
      entityName
    }
    options {
      pagination {
        page
        qty
        count
      }
    }
  }
}

The same pattern applies to all document types; replace invoice/invoices with the relevant query name.

Available type-specific queries

Document typeSingleList
Invoiceinvoiceinvoices
Receiptreceiptreceipts
Credit NotecreditNotecreditNotes
Debit NotedebitNotedebitNotes
Estimateestimateestimates
Simplified InvoicesimplifiedInvoicesimplifiedInvoices
Pro Forma InvoiceproFormaInvoiceproFormaInvoices
Invoice ReceiptinvoiceReceiptinvoiceReceipts
Delivery NotedeliveryNotedeliveryNotes
Purchase OrderpurchaseOrderpurchaseOrders

See the queries reference for the complete list, including supplier and migrated document types.

Generic queries

The generic document and documents queries work across all document types. They return the DocumentRead interface, which includes fields common to every document.

Getting any document by ID

query {
  document(companyId: 1, documentId: 1234) {
    data {
      documentId
      documentTypeId
      number
      date
      totalValue
      status
      entityName
      entityVat
    }
  }
}

This works regardless of whether the document is an invoice, receipt, credit note, or any other type.

Listing all documents

query {
  documents(companyId: 1, options: {
    pagination: { page: 1, qty: 20 }
    order: { field: date, sort: DESC }
  }) {
    data {
      documentId
      documentTypeId
      number
      date
      totalValue
      status
      entityName
    }
    options {
      pagination {
        page
        qty
        count
      }
    }
  }
}

Common fields on all documents

The DocumentRead interface provides these fields on every document type:

FieldDescription
documentIdUnique document identifier
documentTypeIdType of document (invoice, receipt, etc.)
numberSequential number within the document set
dateDocument date
totalValueTotal document value
status0 = draft, 1 = finalized
entityNameCustomer/supplier name
entityVatCustomer/supplier VAT number
documentSetIdID of the document set used
documentSetNameName of the document set
yourReferenceCustomer's reference
ourReferenceInternal reference
deletableWhether the document can be deleted
pdfExportURL to download the PDF

See DocumentRead for the full list.

Using inline fragments for type-specific fields

When using generic queries, some fields are only available on specific document types. Access them with inline fragments:

query {
  document(companyId: 1, documentId: 1234) {
    data {
      # Common fields - available on all documents
      documentId
      number
      date
      totalValue
      entityName

      # Invoice-specific fields
      ... on InvoiceRead {
        expirationDate
        grossValue
        taxesValue
        globalDiscount
        products {
          productId
          name
          qty
          price
        }
        customer {
          customerId
          name
        }
      }

      # Receipt-specific fields
      ... on ReceiptRead {
        payments {
          paymentMethodId
          value
        }
        relatedWith {
          relatedDocumentId
          value
        }
      }
    }
  }
}

The API returns only the fragment matching the actual document type. If the document is an invoice, you get the InvoiceRead fields; if it's a receipt, you get the ReceiptRead fields. Fragments for other types are silently ignored.

Next steps