Invoices

Invoices drive outgoing billing in Naqood. You can create drafts, send them to customers, record payments, or void them for corrections.

Prerequisites

• A Naqood API secret or OAuth-issued secret scoped to the target organization
• The organization slug for every operation
• A role that grants the Invoices permission set

Invoice fields

Invoice objects returned by the API expose commercial, presentation, and posting metadata.

Field	Type	Notes
id	ID!	Stable identifier for follow-up mutations.
number	Int!	Auto-incremented per organization.
status	String!	draft, sent, or voided.
paymentStatus	String	Payment indicator shown in the UI (unpaid, overdue, paid).
contactId	ID!	Linked customer.
contactDetails	String!	Serialized snapshot of the customer’s bill-to details.
date	Date!	Posting date.
dueDate	Date!	Calculated from paymentTermType + paymentTermDays.
title	String	Large document heading rendered above the bill-to block.
header	String	Secondary subtitle shown beneath the title, above the line items.
comment	String	Freeform body copy displayed between the invoice metadata and the header.
lineItems	[JSONObject!]!	Array of line breakdowns (see Products & Services).
subtotal / vat / total	String	Monetary amounts in organization currency.
originalSubtotal / originalVat / originalTotal	String	Amounts in the original transaction currency.
remainder	String!	Outstanding balance (negative values mean the customer still owes money).
currency	String!	Defaults to the organization currency, override for FX invoices.
exchangeRate	String	Required when currency differs from the base currency.
bankAccountId	ID!	Settlement account credited when the invoice is paid.
bankAccount	BankAccount	Helpful when you fetch invoices with related bank data.
pdf	Base64	Supplied on demand when emailing invoices.
baseJournalEntry	JournalEntry	The primary posting created when the invoice was issued.
createdAt / updatedAt	Timestamp!	Audit timestamps.

For information about quote-only documents, including how to convert them into invoices, refer to the Quotes guide.

Fetch a single invoice

query Invoice($invoiceID: ID!) {
  invoice(invoiceID: $invoiceID) {
    id
    number
    status
    date
    dueDate
    contact {
      id
      name
    }
    lineItems
    subtotal
    vat
    total
    remainder
    currency
    paymentStatus
    bankAccount {
      id
      name
    }
  }
}

List invoices

Use the organization-scoped query with pagination, filters, and ordering:

query Invoices(
  $slug: Slug!
  $offset: Int
  $limit: Int
  $orderBy: OrderByInput
  $filter: JSONObject
) {
  organization(slug: $slug) {
    invoices(
      offset: $offset
      limit: $limit
      orderBy: $orderBy
      filter: $filter
    ) {
      count
      entries {
        id
        number
        status
        date
        total
        remainder
        contact {
          id
          name
        }
      }
    }
  }
}

Filters support the standard operators (equalTo, greaterThan, in, and/or, etc.). Apply date ranges, contact IDs, currencies, or statuses as needed.

Create an invoice

mutation CreateInvoice($input: CreateInvoiceInput!) {
  createInvoice(input: $input) {
    id
    number
    status
    total
  }
}

CreateInvoiceInput highlights:

Field	Required	Notes
slug	✅	Organization issuing the invoice.
contactId	✅	Customer to bill.
contactDetails	✅	Serialized string stored on the document (typically from the UI).
date	✅	Posting date.
paymentTermType	✅	days, current_month, etc.
paymentTermDays	✅	Number of days added to calculate the due date.
bankAccountId	✅	Default receiving account.
lineItems	✅	Array of line item payloads (quantity, unit price, VAT, account IDs).
currency	Optional	Defaults to the org currency. Provide exchangeRate when overriding.
status	Optional	Omit for draft. Set to sent to post immediately after creation.
title	Optional	Hero heading shown at the top of the PDF.
header	Optional	Subtitle appearing under the title.
comment	Optional	Introductory paragraph shown before the header and line items.
orgLogoImageId, orgStampImageId	Optional	Reuse stored imagery without re-uploading.

Example variables:

{
  "input": {
    "slug": "acme-co",
    "contactId": "d8f59f7d-08b1-4fe6-8ae1-3a3dfd65ac87",
    "contactDetails": "Acme Trading LLC\nAccounts Payable",
    "date": "2026-01-04",
    "paymentTermType": "days",
    "paymentTermDays": 30,
    "bankAccountId": "b34aa6b1-b527-4d8f-8e7f-66b07f1b6f51",
    "status": "draft",
    "lineItems": [
      {
        "type": "item",
        "lineItemId": "1e68d9a7-6ce6-403a-887f-5c3ed003e5da",
        "quantity": "10",
        "unitPrice": "150.00",
        "discount": "0",
        "vatId": "5ea0cb4a-6bd5-4d59-a859-9eaec4ee2c05"
      }
    ]
  }
}

Update an invoice

mutation UpdateInvoice($input: UpdateInvoiceInput!) {
  updateInvoice(input: $input) {
    id
    status
    total
    updatedAt
  }
}

• Only invoices in draft status can be edited. Sent invoices must be voided and recreated.
• Provide the id plus any fields to change; omitted fields remain untouched.

Send invoices to customers

mutation SendInvoice($input: SendInvoiceToCustomerInput!) {
  sendInvoiceToCustomer(input: $input)
}

Field	Required	Notes
invoiceID	✅	Target invoice or quote.
emails	Optional	Array of additional recipients. Defaults to the contact email.

Naqood generates the PDF (including logos/stamps if provided) and emails it to the customer.

Record payments

mutation PayInvoice($input: PayInvoiceInput!) {
  payInvoice(input: $input) {
    id
    remainder
  }
}

PayInvoiceInput fields:

Field	Required	Notes
invoiceID	✅	Invoice to settle.
amount	✅	Decimal string in invoice currency. Partial payments are supported.
accountID	✅	Cash or bank account credited for the receipt.
date	Optional	Defaults to today.
comment	Optional	Narration stored on the journal entry.
exchangeRate	Optional	Invoice currency to organization currency. Omit it when they differ and Naqood uses the rate for date (or today). Pass a value to use that rate instead.
transactionCurrency / transactionAmount / transactionExchangeRate	Optional	Bank side of the payment when it is not in the invoice currency. transactionExchangeRate is required when the bank currency differs from both the invoice currency and the organization currency.

Each payment generates the necessary journal entries, adjusts remainder, and updates invoice status when fully paid.

Delete or void

mutation DeleteInvoice($invoiceID: ID!) {
  deleteInvoice(invoiceID: $invoiceID)
}

• Drafts and quotes are permanently deleted.
• Sent invoices cannot be deleted outright; calling deleteInvoice voids their journal entries and marks the document as voided so history remains intact.

Use these flows to keep external billing systems, CPQ tools, or customer portals aligned with the data your finance team sees inside Naqood.