createInvoice

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.

Bill a job card, or enter an invoice by hand

Try this operation →Use Postman ↗

Raise an invoice from a job card or by hand, and give it the next number in the shop’s series. Owner, admin and accountant. JOB_CARD_NOT_FOUND or CUSTOMER_NOT_FOUND for an unknown id; VALIDATION_FAILED when a field needed without a job card is missing, the due date is before the issue date, or the total is too large.

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
Idempotency-KeystringRequired
A key you generate once per user action (a UUID). Retrying with the same key never applies the change twice.
Example: 0192f0c1-9b2a-7d40-8c3e-1f5a6b7c8d9e
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

inputInvoiceInput!Required
The invoice.
Example: {"jobCardId":"0192f0c1-0000-7000-8000-000000d20083","gstRate":18,"discount":5000,"poAmount":2500000,"notes":"Packed in 10 crates.","lines":[{"operation":"Turning","description":"Rough and finish","minutesPerPiece":4.5,"setupMinutes":30,"ratePerMinute":1200},{"operation":"Drilling","minutesPerPiece":1.5,"ratePerMinute":900}]}
Show children
- customerIdIDOptional
  The customer; required without a job card.
- discountIntOptional
  Paise off the subtotal. Capped at the subtotal. Default 0.
- dueDateStringOptional
  Payment due date, YYYY-MM-DD, not before issuedAt. Default: the issue date plus the customer’s payment terms.
- gstRateFloat!Required
  GST percentage, 0–28. Ignored when the shop has no GSTIN.
- issuedAtStringOptional
  Invoice date, YYYY-MM-DD. Default: today in the shop’s timezone.
- jobCardIdIDOptional
  The job card to bill.
- lines[BillingLineInput!]!Required
  The operations to price, 1–30 lines.
- notesStringOptional
  Printed on the invoice.
- partStringOptional
  Part name; required without a job card.
- poAmountIntOptional
  Paise on the customer’s PO.
- quantityIntOptional
  Pieces billed, 1–1,000,000; required without a job card.
- quoteIdIDOptional
  The quote this was priced from.
- routeCardStringOptional
  The route card number.

Returns

Required Optional

createInvoiceInvoice!Required
Raise an invoice from a job card or by hand, and give it the next number in the shop’s series. Owner, admin and accountant. JOB_CARD_NOT_FOUND or CUSTOMER_NOT_FOUND for an unknown id; VALIDATION_FAILED when a field needed without a job card is missing, the due date is before the issue date, or the total is too large.
Show children
- createdAtString!Required
  UTC time the invoice was made.
  Example: "2026-10-12T04:30:00.000Z"
- customerIdID!Required
  The customer (see customer).
  Example: "0192f0c1-0000-7000-8000-0000000c0001"
- 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.
  Example: 5000
- dueDateString!Required
  Payment due date, YYYY-MM-DD. Defaults to the issue date plus the customer’s payment terms.
  Example: "2026-10-12"
- gstRateFloat!Required
  The GST percentage asked for. The rate applied is totals.gstRate.
  Example: 18
- idID!Required
  Stable id (UUIDv7).
  Example: "0192f0c1-0000-7000-8000-000000b103f5"
- issuedAtString!Required
  Invoice date, YYYY-MM-DD.
  Example: "2026-10-12"
- jobCardIdIDOptional
  The job card this was raised from (see jobCard); null for a manual invoice.
  Example: "0192f0c1-0000-7000-8000-000000d20083"
- lines[BillingLine!]!Required
  The priced operations, in the order given.
  Example: [{"id":"0192f0c1-0000-7000-8000-b00000000001","operation":"Turning","description":"Rough and finish","minutesPerPiece":4.5,"setupMinutes":30,"ratePerMinute":1200,"amount":576000},{"id":"0192f0c1-0000-7000-8000-b00000000002","operation":"Drilling","description":"","minutesPerPiece":1.5,"setupMinutes":0,"ratePerMinute":900,"amount":135000}]
  Show children
  - amountFloat!Required
    Integer paise: (quantity × minutesPerPiece + setupMinutes) × ratePerMinute, rounded half up to a whole paisa. Computed by the server.
    Example: 576000
  - descriptionString!Required
    Free text for the customer; empty when none was given.
    Example: "Rough and finish"
  - idID!Required
    Stable id (UUIDv7).
    Example: "0192f0c1-0000-7000-8000-b00000000001"
  - minutesPerPieceFloat!Required
    Machine minutes for one piece.
    Example: 4.5
  - operationString!Required
    The operation priced, such as Turning.
    Example: "Turning"
  - ratePerMinuteInt!Required
    Paise per machine minute.
    Example: 1200
  - setupMinutesFloat!Required
    One-off machine minutes to set up, charged once per line.
    Example: 30
- notesStringOptional
  Printed on the invoice.
  Example: "Packed in 10 crates."
- numberString!Required
  The invoice number. Assigned by the server; gaps never happen.
  Example: "DPW/26-27/0013"
- orderIdIDOptional
  The order this bills (see order).
  Example: "0192f0c1-0000-7000-8000-000000d0000d"
- partString!Required
  Part name or number.
  Example: "Coupling Hub"
- 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.
  Example: 2500000
- quantityInt!Required
  Pieces billed.
  Example: 100
- quoteIdIDOptional
  The quote this was priced from, if any (see quote).
  Example: null
- routeCardStringOptional
  The route card number printed on the job card.
  Example: "JC-00025"
- 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: {"subtotal":711000,"discount":5000,"taxable":706000,"gstRate":18,"supply":"INTRA","cgst":63540,"sgst":63540,"igst":0,"gst":127080,"total":833080}
  Show children
  - cgstFloat!Required
    Central GST; 0 unless supply is INTRA.
    Example: 63540
  - discountFloat!Required
    The discount applied. Never more than the subtotal.
    Example: 5000
  - gstFloat!Required
    Total GST: cgst + sgst + igst.
    Example: 127080
  - gstRateFloat!Required
    The GST percentage applied; 0 when supply is NONE.
    Example: 18
  - igstFloat!Required
    Integrated GST; 0 unless supply is INTER.
    Example: 0
  - sgstFloat!Required
    State GST; 0 unless supply is INTRA.
    Example: 63540
  - subtotalFloat!Required
    Sum of the line amounts.
    Example: 711000
  - supplyGstSupply!Required
    Whether CGST + SGST or IGST applies.
    Example: "INTRA"
    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.
    Example: 706000
  - totalFloat!Required
    Taxable plus GST.
    Example: 833080
- updatedAtString!Required
  UTC time of the last change.
  Example: "2026-10-12T04:30:00.000Z"

Errors

Code	HTTP	When
`CUSTOMER_NOT_FOUND`	`404`	The id is unknown in this shop (another shop's ids answer the same).
`VALIDATION_FAILED`	`400`	Input failed Zod or route schema validation. `details` lists each field path and problem.
`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.