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:

The invoice's documentId: returned when you created the invoice
A document set ID: the numbering series for receipts (separate from the invoice series)
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. See the Document Types guide for the complete list of IDs and codes, or use the documentTypes query at runtime.

Required fields

The ReceiptInsert input has these required fields:

Field	Type	Description
`documentSetId`	`Int!`	The receipt document set (numbering series)
`date`	`DateTime!`	Date the payment was received
`customerId`	`Int!`	The customer making the payment
`totalValue`	`Float!`	Total amount received
`relatedWith`	`[RelatedDocumentInput!]!`	The invoice(s) being settled

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

Field	Type	Description
`relatedDocumentId`	`Int!`	The `documentId` of the invoice being paid
`value`	`Float!`	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:

Field	Type	Description
`paymentMethodId`	`Int`	Payment method ID (cash, transfer, etc.)
`value`	`Float!`	Amount paid via this method
`date`	`DateTime`	Payment date
`notes`	`String`	Notes 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:

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

Once finalized (status: 1), a receipt cannot be edited or deleted.

Next steps

Querying Documents: List and filter your invoices and receipts
Downloading a Document PDF: Export receipts and invoices as PDF
Pagination: Page through large document lists
Filtering, Search & Ordering: Narrow results by date, status and more
See receiptCreate and ReceiptInsert for all fields