Invoice Reversal

Invoice Reversal API

Reverse an existing invoice by providing its Invoice Reference Number (IRN). This operation creates a credit note on that invoice.

Quick Reference

Method Endpoint Content-Type
POST https://api-dev.nairainvoice.com/dev/external/businesses/:businessId/invoices/reversal application/json

Request Structure

Path Parameters

Parameter Type Required Description
businessId string ✅ The unique identifier of the business

🔐 Authentication Headers

Header Type Required Description
X-Business-Key string ✅ Business authentication key for API access

📋 Request Body

Field Type Required Description Validation
irn string ✅ Invoice Reference Number Must be a valid IRN format
Example: INV236-1070ECE8-20250826

📤 Response Format

Success Response (200)

Copy to Clipboard

Response Fields

Top-Level Response

Field Type Description
responseCode string Response status code ("00" = success)
responseMessage string Human-readable response message
data object Invoice data object

Invoice Core Details

Field Type Description
invoiceId number Unique invoice identifier
invoiceBusinessId string Business ID associated with invoice
invoiceEntityId string Entity ID for the invoice
invoiceIrn string Invoice Reference Number
invoiceIssueDate string Date invoice was issued (YYYY-MM-DD)
invoiceDueDate string Payment due date (YYYY-MM-DD)
invoiceIssueTime string Time invoice was issued (HH:MM:SS)
invoiceTypeCode string Invoice type code
invoicePaymentStatus string Payment status (e.g., "PAID", "UNPAID")
invoiceStatus string Current invoice status (e.g., "PENDING", "REVERSED")
invoiceNote string Additional notes or description
invoiceDocumentCurrencyCode string Invoice currency code
invoiceTaxCurrencyCode string Tax currency code
invoiceCreatedAt string Timestamp when invoice was created
invoiceUpdatedAt string Timestamp when invoice was last updated

Customer Information

Field Type Description
invoiceCustomerPartyTin string Customer Tax Identification Number
invoiceCustomerPartyEmail string Customer email address
invoiceCustomerPartyTelephone string Customer phone number
invoiceCustomerPartyName string Customer name
invoiceCustomerPartyBusinessDescription string Customer business description
invoiceCustomerCityName string Customer city
invoiceCustomerPostalZone string Customer postal code
invoiceCustomerCountry string Customer country code
invoiceCustomerStreetName string Customer street address
invoiceCustomerLga string Customer Local Government Area
invoiceCustomerState string Customer state

Supplier Information

Field Type Description
invoiceSupplierPartyId string Supplier party ID
invoiceSupplierPartyTin string Supplier Tax Identification Number
invoiceSupplierPartyEmail string Supplier email address
invoiceSupplierPartyTelephone string Supplier phone number
invoiceSupplierPartyName string Supplier name
invoiceSupplierPartyBusinessDescription string Supplier business description
invoiceSupplierCityName string Supplier city
invoiceSupplierPostalZone string Supplier postal code
invoiceSupplierCountry string Supplier country code
invoiceSupplierStreetName string Supplier street address
invoiceSupplierLga string Supplier Local Government Area
invoiceSupplierState string Supplier state

Financial Summary

Field Type Description
invoiceLineExtensionAmount number Line extension total amount
invoiceTaxExclusiveAmount number Total amount excluding tax
invoiceTaxInclusiveAmount number Total amount including tax
invoicePayableAmount number Total amount payable

Line Items

Field Type Description
invoiceLine array Array of invoice line items
invoiceLineInvoiceId number Associated invoice ID
invoiceLineProductCategory string Product category
invoiceLineDiscountRate number Discount rate applied
invoiceLineDiscountAmount number Discount amount
invoiceLineFeeRate number Fee rate applied
invoiceLineFeeAmount number Fee amount
invoiceLineInvoicedQuantity number Quantity invoiced
invoiceLineExtensionAmount number Line item total amount
invoiceLineHsnCode string HSN classification code
invoiceLineItemDescription string Item description
invoiceLineItemName string Item name
invoiceLinePriceBaseQuantity number Base quantity for pricing
invoiceLinePriceUnit string Price unit description
invoiceLinePriceAmount number Price per unit

Tax Information

Field Type Description
invoiceTaxTotal array Array of tax totals
invoiceTaxTotalInvoiceId number Associated invoice ID
invoiceTaxTotalAmount number Total tax amount
invoiceTaxTotalSubTotal array Array of tax subtotals by category
taxSubTotalTaxableAmount number Taxable amount
taxSubTotalTaxAmount number Tax amount for this category
taxSubTotalCategoryId string Tax category identifier
taxSubTotalCategoryPercent number Tax percentage rate

📝 Example Usage

cURL Example

Copy to Clipboard

JSON Request Body

Copy to Clipboard

✅ Validation Rules

Request Validation

  • businessId: Must be a valid UUID format in the URL path
  • X-Business-Key: Required authentication header, must be valid
  • irn: Required field, must match an existing invoice IRN

Business Logic Validation

  • The specified invoice must exist in the system
  • The invoice must belong to the specified business
  • The invoice must be in a reversible state
  • User must have appropriate permissions to reverse invoices

⚠️ Error Responses

Common Error Codes

Status Code Response Code Description
400 – Bad Request – Invalid IRN format or missing required fields
401 – Unauthorized – Invalid or missing X-Business-Key
404 – Not Found – Invoice with specified IRN does not exist
403 – Forbidden – Insufficient permissions to reverse invoice
409 – Conflict – Invoice cannot be reversed (already reversed or in invalid state)

Error Response Format

Copy to Clipboard

💡 Use Cases

When to Use This Endpoint

  1. Accounting Corrections: Reverse an invoice that was issued incorrectly
  2. Transaction Cancellations: Cancel a transaction that needs to be voided
  3. Credit Note Generation: Create a reversal for issuing credits to customers
  4. Compliance Requirements: Maintain audit trails for reversed transactions

Important Considerations

  • A reversal will trigger the creation of a credit note or adjustment entry

  • Reversed invoices usually cannot be un-reversed; a new invoice must be created instead

📊 Workflow Example

Copy to Clipboard

Request

Path Params

Field Type Required Example
stage string ✅
businessId string ✅

Header Params

Field Type Required Description / Example
X-Business-Key string ✅ (Required) X-Business-Key
Example: BK-26EDE24BAC50475FAACC5EA6339F0863-DEV-B2Z6QCEHI3X9
Content-Type string ✅ Example: application/json
Accept string ✅ Example: */*

Body Params

Field Type Description
invoiceCustomerPartyTin string Customer Tax Identification Number

Response

Response Status

  • 200 OK

  • 201 Created

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found