Payslips

Payslips represent a single pay period for one employee. They bundle payroll employee details, salary component lines, posting status, and payment tracking so external payroll tooling can stay in lockstep with Naqood.

Prerequisites

• A Naqood API secret or OAuth-issued secret scoped to the target organization
• The organization slug for every organization-scoped operation
• A role that grants Payroll permissions (payslips)

Payslip fields

Field	Type	Notes
id / number	ID! / Int!	number auto-increments per organization; admins can adjust the next number from the UI.
employee	PayrollEmployee!	Returns the full employee object for rendering PDFs or reconciling defaults.
periodStart / periodEnd	Date!	Defines the earning period printed on the payslip.
status	PayslipStatus!	draft, sent, or voided.
paymentStatus / remainder	String	Mirrors invoice payment tracking; remainder is 0 once fully paid.
currency / exchangeRate	String! / String	Required for FX payroll; provide exchangeRate when currency differs from the base currency.
totalEarnings / totalDeductions / netPay	String	Aggregated totals for the payslip currency.
lines	[PayslipLine!]!	Detailed earnings and deductions referencing salary components.
baseJournalEntry	JournalEntry	Ledger posting created when the payslip is sent or paid.
createdAt / updatedAt	Timestamp!	Audit timestamps.

List payslips

query Payslips(
  $slug: Slug!
  $offset: Int
  $limit: Int
  $orderBy: OrderByInput
  $filter: JSONObject
) {
  organization(slug: $slug) {
    payslips(
      offset: $offset
      limit: $limit
      orderBy: $orderBy
      filter: $filter
    ) {
      count
      entries {
        id
        number
        status
        paymentStatus
        periodStart
        periodEnd
        netPay
        remainder
        employee {
          id
          name
        }
      }
    }
  }
}

Apply filters to locate payslips by period, employee IDs, currency, or status using the same operators supported elsewhere (between, equalTo, in, and/or, etc.).

Create payslips

mutation CreatePayslip($input: CreatePayslipInput!) {
  createPayslip(input: $input) {
    id
    number
    status
    netPay
  }
}

CreatePayslipInput requires the following fields:

Field	Required	Notes
slug	✅	Organization issuing the payslip.
employeeId	✅	Employee receiving the payment.
periodStart / periodEnd	✅	Boundaries of the pay period.
currency	✅	Payslip currency; include exchangeRate when posting in a different currency than the organization default.
lines	✅	Array of PayslipLineInput entries.
status	Optional	Defaults to draft. Set to sent to post immediately.

PayslipLineInput pairs amounts with salary components:

Field	Required	Notes
salaryComponentId	✅	Must reference an existing salary component.
amount	✅	Decimal string; positive numbers are used for both earnings and deductions.
type	✅	earning or deduction, used to determine polarity.
rank	✅	Controls the ordering of lines on the UI and PDF.

Use updatePayslip to edit drafts. Deleting a draft removes it outright; deleting a sent payslip results in a voided record so ledger history remains intact.

Send payslips to employees

mutation SendPayslip($input: SendPayslipToEmployeeInput!) {
  sendPayslipToEmployee(input: $input)
}

SendPayslipToEmployeeInput fields:

Field	Required	Notes
payslipID	✅	Payslip to deliver.
emails	✅	Array of recipient email addresses

Naqood renders the PDF (including organization logos/stamps) and emails the listed recipients on your behalf.

Record payslip payments

mutation PayPayslip($input: PayPayslipInput!) {
  payPayslip(input: $input) {
    id
    remainder
    baseJournalEntry {
      id
      date
    }
  }
}

PayPayslipInput requires payslipID, amount, and accountId (cash or bank account). Optional fields let you capture FX amounts (currency, exchangeRate, transactionCurrency, etc.) or attach a narration with comment. Partial payments are supported; Naqood updates remainder until the net pay is fully covered.