Paying an Invoice with a Receipt | Moloni ON API
Moloni ONGuidesAPI ReferenceExplorer
Guides

Paying an Invoice with a Receipt

Once you've created an invoice, you record the customer's payment by issuing a receipt with the receiptCreate mutation. A receipt settles one or more invoices and records how the payment was made.

Prerequisites

To create a receipt you need:

  1. The invoice's documentId: returned when you created the invoice
  2. A document set ID: the numbering series for receipts (separate from the invoice series)
  3. A payment method ID: how the customer paid (cash, bank transfer, etc.)

Fetching payment methods

query {
  paymentMethods(companyId: 1) {
    data {
      paymentMethodId
      name
    }
  }
}

Common results might be: Cash (1), Bank Transfer (2), Credit Card (3), etc. The IDs depend on your company configuration.

Fetching receipt document sets

Use documentSetsForDocument to get the sets configured for receipts. A document set can be associated with multiple document types, so the same set may serve both invoices and receipts.

query {
  documentSetsForDocument(companyId: 1, documentTypeId: 2) {
    errors { field msg }
    data {
      documentSetId
      name
      isDefault
    }
  }
}

Document types are system-defined and fixed; use the documentTypes query to look up the ID for receipts.

Required fields

The ReceiptInsert input has these required fields:

FieldTypeDescription
documentSetIdInt!The receipt document set (numbering series)
dateDateTime!Date the payment was received
customerIdInt!The customer making the payment
totalValueFloat!Total amount received
relatedWith[RelatedDocumentInput!]!The invoice(s) being settled

Each entry in relatedWith links the receipt to an invoice via RelatedDocumentInput:

FieldTypeDescription
relatedDocumentIdInt!The documentId of the invoice being paid
valueFloat!The amount applied to that invoice

Paying an invoice in full

This example creates a receipt that fully pays an invoice:

mutation {
  receiptCreate(
    companyId: 1
    data: {
      documentSetId: 7
      date: "2025-03-20T14:00:00.000Z"
      customerId: 42
      totalValue: 99.98
      relatedWith: [
        {
          relatedDocumentId: 1234
          value: 99.98
        }
      ]
      payments: [
        {
          paymentMethodId: 2
          value: 99.98
          date: "2025-03-20T14:00:00.000Z"
        }
      ]
      status: 1
    }
  ) {
    errors { field msg }
    data {
      documentId
      number
      totalValue
    }
  }
}

The totalValue should match the sum of all relatedWith[].value entries.

Response:

{
  "data": {
    "receiptCreate": {
      "errors": [],
      "data": {
        "documentId": 5678,
        "number": 12,
        "totalValue": 99.98
      }
    }
  }
}

Specifying the payment method

The payments array in ReceiptInsert records how the payment was made. Each entry uses DocumentPaymentMethodInput:

FieldTypeDescription
paymentMethodIdIntPayment method ID (cash, transfer, etc.)
valueFloat!Amount paid via this method
dateDateTimePayment date
notesStringNotes about this payment

Paying with multiple methods

You can split the payment across methods. For example, part cash and part bank transfer:

payments: [
  {
    paymentMethodId: 1
    value: 50.00
    date: "2025-03-20T14:00:00.000Z"
    notes: "Cash payment"
  },
  {
    paymentMethodId: 2
    value: 49.98
    date: "2025-03-20T14:00:00.000Z"

  }
]

Partial payments

You can partially pay an invoice by specifying a value lower than the invoice total:

mutation {
  receiptCreate(
    companyId: 1
    data: {
      documentSetId: 7
      date: "2025-03-20T14:00:00.000Z"
      customerId: 42
      totalValue: 50.00
      relatedWith: [
        {
          relatedDocumentId: 1234
          value: 50.00
        }
      ]
      payments: [
        {
          paymentMethodId: 1
          value: 50.00
          date: "2025-03-20T14:00:00.000Z"
        }
      ]
      status: 1
    }
  ) {
    errors { field msg }
    data {
      documentId
      totalValue
    }
  }
}

The remaining balance on the invoice can be settled later with another receipt.

Settling multiple invoices at once

A single receipt can settle several invoices. List each invoice in the relatedWith array:

mutation {
  receiptCreate(
    companyId: 1
    data: {
      documentSetId: 7
      date: "2025-03-20T14:00:00.000Z"
      customerId: 42
      totalValue: 350.00
      relatedWith: [
        { relatedDocumentId: 1234, value: 200.00 },
        { relatedDocumentId: 1235, value: 150.00 }
      ]
      payments: [
        {
          paymentMethodId: 2
          value: 350.00
          date: "2025-03-20T14:00:00.000Z"
        }
      ]
      status: 1
    }
  ) {
    errors { field msg }
    data {
      documentId
      totalValue
    }
  }
}

The totalValue must equal the sum of all relatedWith values.

Draft vs finalized

Like invoices, receipts support draft and finalized states:

StatusMeaning
0Draft: can be edited or deleted
1Finalized: locked and reported to tax authorities (if applicable)

Next steps