Invoices · Create invoice
Create an invoice
Create an invoice with customer details, line items, tax totals, monetary totals, and payment means.
/api/v1/organizations/{organizationReference}/invoices/posBearer token · X-Client-IdHow creation works
Authenticate with the bearer token from POST /api/v1/organizations/pos/authenticate (see Access token) and send the X-Client-Id header. Invoices created this way are automatically sent for validation and submission. The spec does not mark any request field as required, so validity is decided by the backend. Send only the fields you have real values for: leave the others out rather than filling them with dummy text. The NRS flow itself needs complete data, so send real values for the fields below.
Headers and path
| Field | Type | Description |
|---|---|---|
| Authorization | header | Bearer <access_token> from POST /api/v1/organizations/pos/authenticate. |
| X-Client-Id | header | The organization's client identifier. |
| Content-Type | header | application/json |
| organizationReference | path | The organization the invoice belongs to. |
Invoice fields
All keys are camelCase, except allowance_charges.
| Field | Type | Description |
|---|---|---|
| invoiceDate, dueDate, taxPointDate, actualDeliveryDate | date | yyyy-MM-dd. |
| invoiceTime | string | Time of issue. |
| reference, title, note, invoiceFooter | string | Free text. |
| invoiceKind, invoiceTypeCode | string | Plain strings in the spec (no enum). The web app sends invoiceKind in lowercase. |
| documentCurrencyCode, taxCurrencyCode | string | Currency codes, for example NGN. |
| paymentStatus | enum | PENDING, PAID or REJECTED. |
| paymentTermsNote, buyerReference, orderReference | string | Commercial references. |
| accountingCost | number | Accounting cost. |
| deliveryPeriod | object | { startDate, endDate }. |
| legalMonetaryTotal | object | lineExtensionAmount, taxExclusiveAmount, taxInclusiveAmount, payableAmount (numbers). |
| taxTotals | array | { taxAmount, taxSubtotals[{ taxableAmount, taxAmount, taxCategory{ categoryId, percent } }] }. |
| paymentMeans | array | { paymentMeansCode, paymentDueDate }. |
| allowance_charges | array | { amount, charge_indicator }. This one key is snake_case. |
| accountingSupplierParty | object | supplierName, supplierAddress, supplierTin, email, telephone, businessDescription, postalAddress. |
Customer fields
Customer details are flat fields on the invoice, not a nested object.
| Field | Type | Description |
|---|---|---|
| customerName | string | Customer name. |
| customerEmail | string (email) | With customerTin, used to link the customer record. |
| customerTin | string | Customer tax identification number. |
| customerAddress, customerPhone | string | Contact details. |
| vatNumber, businessDescription | string | Optional customer details. |
| customerType | enum | BUSINESS, INDIVIDUAL or GOVERNMENT. |
| postalAddress | object | streetName, cityName, postalZone, country, state, lga. |
Line items
| Field | Type | Description |
|---|---|---|
| invoicedQuantity | integer | Quantity invoiced. |
| lineExtensionAmount | number | Line total before tax. |
| item | object | { name, description, sellerItemIdentification }. |
| price | object | { priceAmount, priceBaseQuantity, currencyUnit (NGN, USD, EUR or GBP), priceUnit }. |
| hsnCode, isicCode | string | Classification codes. |
| productCategory, serviceCategory | string | Categories. |
| discountRate, feeRate | number (float) | Rates. The web app sends discountRate as a fraction (10% as 0.1). |
| discountAmount, feeAmount | number | Absolute amounts. |
Send the amounts yourself
Totals are plain numbers in the request (decimal NGN amounts, not minor units). The web app computes lineExtensionAmount, taxTotals and legalMonetaryTotal before sending.
Document references
dispatchDocumentReference, receiptDocumentReference, originatorDocumentReference and contractDocumentReference are single objects; billingReferences and additionalDocumentReferences are arrays of the same object.
| Field | Type | Description |
|---|---|---|
| invoiceNumber | string | The referenced IRN or invoice number. |
| issueDate | date | yyyy-MM-dd. |
IRN normalisation
The web app uppercases the reference and strips everything except A-Z, 0-9 and hyphen, because NRS requires IRNs in that form. References that end up empty are omitted from the request. Do the same in your integration.
Success response
A successful request returns 200 with the standard envelope; data is an InvoiceResponse.
| Field | Type | Description |
|---|---|---|
| data.id | string | Invoice identifier; use it to retrieve, update or delete the invoice. |
| data.status | enum | Invoice status; a new invoice starts as DRAFT in the example. |
| data.paymentStatus | enum | PENDING, PAID or REJECTED. |
| data.legalMonetaryTotal | object | Totals as stored. |
| data.lineItems, taxTotals, paymentMeans | array | Stored lines and taxes. |
| data.customerRecord | object | Linked customer record. |
| data.creationSource | enum | WEB, POS or ERP. |
| data.dateCreated, dateUpdated | date-time | Audit timestamps. |
200 OK
Keep data.id. Use it to retrieve the invoice with GET /invoices/pos/{invoiceId}.
Errors
| Field | Type | Description |
|---|---|---|
| 400 | Bad Request | Malformed or invalid request. |
| 401 | Unauthorized | Missing or invalid bearer token. |
| 403 | Forbidden | Caller is not permitted to create invoices. |
| 404 | Not Found | Organization does not exist. |
| 409 | Conflict | Request conflicts with existing data. |
| 500 | Server Error | Unexpected server error. |
Error bodies use the same envelope with a string data field.
Coming soon Soon
Idempotency keys
Safe retries with an Idempotency-Key header are planned. The API does not accept or require one today.