invoices

Mock

Mock. This operation is part of the approved contract but its module is not built yet. Run Core with N1_API_MODE=mock N1_DEV_AUTH=stub to get deterministic demo-shop data from it. The real server answers NOT_IMPLEMENTED until it ships; the schema and examples here will not change when it does.

Page through invoices by status and search

Try this operation →Use Postman ↗

The shop’s invoices, paged. Search matches invoice number, customer name, part and route card. The status filter uses the derived status, so OVERDUE works. Owner, admin and accountant. For the screen’s headline figures ask for invoiceSummary in the same document.

POST/graphqlapp audience

Who can call this. Owner, admin, accountant.

Headers

Required Optional

AuthorizationstringRequired
Bearer <token>, issued for this endpoint's audience. The token decides the shop and roles; nothing in the request body can change them.
Example: Bearer eyJhbGciOiJFZERTQSJ9…
Content-TypestringRequired
Always application/json. Only POST is accepted.
Example: application/json
X-Request-IdstringOptional
Your id for this request (8–128 characters of A–Z a–z 0–9 . _ : -). Echoed back in the response header and in every error, so you can quote it when reporting a problem. Core makes one if you send none.
Example: app-7f3c2a9e-checkout

Arguments

Required Optional

afterStringOptional
endCursor of the previous page.
beforeStringOptional
startCursor of the next page, when paging backwards.
filterInvoiceFilterOptional
Narrow by status, customer, order or job card.
Show children
- customerIdIDOptional
  Only this customer’s invoices.
- jobCardIdIDOptional
  Only invoices raised from this job card.
- orderIdIDOptional
  Only invoices for this order.
- statusInvoiceStatusOptional
  Only invoices in this state.
firstIntOptional
Page size, 1–100 (default 20).
Example: 3
lastIntOptional
Page size when paging backwards, 1–100.
searchStringOptional
Free text, 1–100 characters.
sortInvoiceSortOptional
Order (default: newest invoice date first).
Show children
- directionSortDirection!Required
  Ascending or descending.
- fieldInvoiceSortField!Required
  What to order by.

Returns

Required Optional

invoicesInvoiceConnection!Required
The shop’s invoices, paged. Search matches invoice number, customer name, part and route card. The status filter uses the derived status, so OVERDUE works. Owner, admin and accountant. For the screen’s headline figures ask for invoiceSummary in the same document.
Show children
- edges[InvoiceEdge!]!Required
  The rows on this page, in order.
  Example: [{"cursor":"WyIyMDI2LTEwLTA5IiwiMDE5MmYwYzEtMDAwMC03MDAwLTgwMDAtMDAwMDAwYjEwMDAxIl0","node":{"id":"0192f0c1-0000-7000-8000-000000b10001","number":"DPW/26-27/0012","customerName":"Alpha Auto Components 1","part":"Bush 25x30","status":"NEW","issuedAt":"2026-10-09","dueDate":"2026-11-08","totals":{"total":84960},"payment":null}},{"cursor":"WyIyMDI2LTEwLTA3IiwiMDE5MmYwYzEtMDAwMC03MDAwLTgwMDAtMDAwMDAwYjEwMDAyIl0","node":{"id":"0192f0c1-0000-7000-8000-000000b10002","number":"DPW/26-27/0011","customerName":"Bharat Hydraulics 2","part":"Pulley 90","status":"NEW","issuedAt":"2026-10-07","dueDate":"2026-11-06","totals":{"total":153400},"payment":null}},{"cursor":"WyIyMDI2LTA5LTE3IiwiMDE5MmYwYzEtMDAwMC03MDAwLTgwMDAtMDAwMDAwYjEwMDAzIl0","node":{"id":"0192f0c1-0000-7000-8000-000000b10003","number":"DPW/26-27/0010","customerName":"Cauvery Pumps 3","part":"Spindle Nut","status":"PAID","issuedAt":"2026-09-17","dueDate":"2026-10-17","totals":{"total":128620},"payment":{"paidOn":"2026-09-27"}}}]
  Show children
  - cursorString!Required
    Opaque position of this row in the list.
    Example: "WyIyMDI2LTEwLTA5IiwiMDE5MmYwYzEtMDAwMC03MDAwLTgwMDAtMDAwMDAwYjEwMDAxIl0"
  - nodeInvoice!Required
    The Invoice.
    Example: {"id":"0192f0c1-0000-7000-8000-000000b10001","number":"DPW/26-27/0012","customerName":"Alpha Auto Components 1","part":"Bush 25x30","status":"NEW","issuedAt":"2026-10-09","dueDate":"2026-11-08","totals":{"total":84960},"payment":null}
    Show children
    createdAtString!Required
    UTC time the invoice was made.
    customerIdID!Required
    The customer (see customer).
    customerNameString!Required
    The customer’s name, so a list needs no second call.
    Example: "Alpha Auto Components 1"
    discountInt!Required
    Paise discount asked for. The amount applied is totals.discount.
    dueDateString!Required
    Payment due date, YYYY-MM-DD. Defaults to the issue date plus the customer’s payment terms.
    Example: "2026-11-08"
    gstRateFloat!Required
    The GST percentage asked for. The rate applied is totals.gstRate.
    idID!Required
    Stable id (UUIDv7).
    Example: "0192f0c1-0000-7000-8000-000000b10001"
    issuedAtString!Required
    Invoice date, YYYY-MM-DD.
    Example: "2026-10-09"
    jobCardIdIDOptional
    The job card this was raised from (see jobCard); null for a manual invoice.
    lines[BillingLine!]!Required
    The priced operations, in the order given.
    Show children
    amountFloat!Required
    Integer paise: (quantity × minutesPerPiece + setupMinutes) × ratePerMinute, rounded half up to a whole paisa. Computed by the server.
    descriptionString!Required
    Free text for the customer; empty when none was given.
    idID!Required
    Stable id (UUIDv7).
    minutesPerPieceFloat!Required
    Machine minutes for one piece.
    operationString!Required
    The operation priced, such as Turning.
    ratePerMinuteInt!Required
    Paise per machine minute.
    setupMinutesFloat!Required
    One-off machine minutes to set up, charged once per line.
    notesStringOptional
    Printed on the invoice.
    numberString!Required
    The invoice number. Assigned by the server; gaps never happen.
    Example: "DPW/26-27/0012"
    orderIdIDOptional
    The order this bills (see order).
    partString!Required
    Part name or number.
    Example: "Bush 25x30"
    paymentPaymentOptional
    Set once the invoice is paid; null before that.
    Example: null
    Show children
    paidOnString!Required
    The day the money arrived, YYYY-MM-DD.
    receivedAmountInt!Required
    Paise actually received: the invoice total less tdsAmount.
    tdsAmountInt!Required
    Paise the customer deducted as tax at source; 0 when none.
    tdsSectionStringOptional
    The income-tax section the deduction was made under, such as 194C.
    poAmountIntOptional
    Paise: the amount on the customer’s PO, to compare against totals.total.
    quantityInt!Required
    Pieces billed.
    quoteIdIDOptional
    The quote this was priced from, if any (see quote).
    routeCardStringOptional
    The route card number printed on the job card.
    statusInvoiceStatus!Required
    NEW, OVERDUE or PAID. Derived from payment and dueDate.
    Example: "NEW"
    NEWIssued, not paid, and not yet past its due date.
    OVERDUENot paid and past its due date.
    PAIDA payment has been recorded.
    totalsTotals!Required
    Subtotal, GST and total, all in paise, worked out by the server.
    Example: {"total":84960}
    Show children
    cgstFloat!Required
    Central GST; 0 unless supply is INTRA.
    discountFloat!Required
    The discount applied. Never more than the subtotal.
    gstFloat!Required
    Total GST: cgst + sgst + igst.
    gstRateFloat!Required
    The GST percentage applied; 0 when supply is NONE.
    igstFloat!Required
    Integrated GST; 0 unless supply is INTER.
    sgstFloat!Required
    State GST; 0 unless supply is INTRA.
    subtotalFloat!Required
    Sum of the line amounts.
    supplyGstSupply!Required
    Whether CGST + SGST or IGST applies.
    INTERDifferent states: IGST.
    INTRAShop and customer are in the same state: CGST + SGST.
    NONEThe shop has no GSTIN, so no GST is charged.
    taxableFloat!Required
    Subtotal less discount.
    totalFloat!Required
    Taxable plus GST.
    Example: 84960
    updatedAtString!Required
    UTC time of the last change.
- pageInfoPageInfo!Required
  Whether more pages exist, and the cursors to reach them.
  Example: {"hasNextPage":true,"endCursor":"WyIyMDI2LTA5LTE3IiwiMDE5MmYwYzEtMDAwMC03MDAwLTgwMDAtMDAwMDAwYjEwMDAzIl0"}
  Show children
  - endCursorStringOptional
    Cursor of the last row; pass it as after to get the next page. Null when the page is empty.
    Example: "WyIyMDI2LTA5LTE3IiwiMDE5MmYwYzEtMDAwMC03MDAwLTgwMDAtMDAwMDAwYjEwMDAzIl0"
  - hasNextPageBoolean!Required
    Whether another page follows this one.
    Example: true
  - hasPreviousPageBoolean!Required
    Whether another page comes before this one.
  - startCursorStringOptional
    Cursor of the first row; pass it as before to page backwards. Null when the page is empty.
- totalCountInt!Required
  All rows matching the filter and search, not just this page.
  Example: 12

Errors

Code	HTTP	When
`FORBIDDEN`	`403`	Signed in, but the role or tenant does not allow the action.

Every error has the same body. See Errors.

Rate limit tier

Tier: per user. Over the limit you get RATE_LIMITED (HTTP 429) with a Retry-After header. See Response handling.