Create Invoice

Create and process tax-compliant E-Invoices. Validates content, signs with NRS, verifies parties, and transmits (B2B, B2G, G2B) or reports (B2C) to NRS—all in one call.

POST  {{baseURL}}/{{stage}}/external/businesses/{{businessId}}/invoices

This endpoint combines multiple NRS operations:

Validates invoice against UBL standards

Signs invoice with NRS digital signature

Looks up IRN and TIN for party verification

Transmits to recipient (B2B, B2G, G2B) or reports to NRS (B2C)

Request Structure

Headers

Header	Value	Required
`Content-Type`	`application/json` or `/`	Yes
`Accept`	`application/json` or `/`	Yes
`X-Business-Key`	`businessKey`	Yes

Path Parameters

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

Request Body

The request body must be a JSON / XML object containing the following sections:

📋 Mandatory Invoice Details

Field	Type	Description	Example
`invoiceBusinessId`	String	A unique alphanumeric ID generated when the taxpayer is registered on the NRS Dashboard	`"6dj03c76-1d83-4a39-a4de-51bd70547aef"`
`invoiceIssueDate`	String	The date on which this document was issued. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceTypeCode`	String	Code specifying the type of invoice being issued	Check Resources for valid invoice type codes
`invoiceDocumentCurrencyCode`	String	Code specifying the default currency in which the invoice is issued	Check Resources for valid document currency codes
`invoiceTaxCurrencyCode`	String	The currency in which tax amounts are calculated	Check Resources for valid tax currency codes
`invoiceSupplierStreetName`	String	The street name where the supplier's business is located	`"10, Banana Island Road"`
`invoiceSupplierCityName`	String	The city where the supplier's business is registered	`"Ikoyi"`
`invoiceSupplierLga`	String	The local government code of the supplier	Check Resources for valid LGA codes
`invoiceSupplierState`	String	The state code of the supplier	Check Resources for valid state codes
`invoiceSupplierCountry`	String	The country code representing the supplier's registered country (ISO 3166-1 Alpha-2)	Check Resources for valid country codes
`invoiceSupplierPostalZone`	String	The official postal zone address of the supplier	`"100243"`
`invoiceSupplierPartyBusinessDescription`	String	A brief description of the supplier's line of business	`"Import and Sales of Foreign Rice"`
`invoiceSupplierPartyTin`	String	The Taxpayer Identification Number (TIN) assigned to the supplier for tax compliance	`"24058123-0001"`
`invoiceSupplierPartyEmail`	String	The supplier's official email address used for tax communication and invoicing correspondence	`"supplier_business@email.com"`
`invoiceSupplierPartyTelephone`	String	The supplier's contact number with country code prefix (+234 for Nigeria)	`"+23480254099000"`
`invoiceSupplierPartyName`	String	The registered name of the supplier issuing the invoice. Legal business name as recognized by tax authorities	`"ABC Rice Ltd."`
`invoiceCustomerStreetName`	String	The street name where the customer's business is located	`"15, Glover Road"`
`invoiceCustomerCityName`	String	The city where the customer's business is registered	`"Ikoyi"`
`invoiceCustomerLga`	String	The local government code of the customer	Check Resources for valid LGA codes
`invoiceCustomerState`	String	The state code of the customer	Check Resources for valid state codes
`invoiceCustomerCountry`	String	The country code representing the customer's registered country (ISO 3166-1 Alpha-2)	Check Resources for valid country codes
`invoiceCustomerPostalZone`	String	The official postal zone address of the customer	`"100243"`
`invoiceCustomerPartyBusinessDescription`	String	A brief description of the customer's line of business	`"Cement and building materials"`
`invoiceCustomerPartyTin`	String	The Taxpayer Identification Number (TIN) assigned to the customer for tax compliance	`"24058123-0001"`
`invoiceCustomerPartyEmail`	String	The customer's official email address used for tax communication and invoicing correspondence	`"customer_business@email.com"`
`invoiceCustomerPartyTelephone`	String	The customer's contact number with country code prefix (+234 for Nigeria)	`"+23480254099000"`
`invoiceCustomerPartyName`	String	The registered name of the customer. Legal business name as recognized by tax authorities	`"XYZ Ltd."`
`invoiceLine`	Array	Array of invoice line items	-
`↳ invoiceLineProductCategory`	String	The category the product belongs to	`"Cereals; husked (brown) rice"`
`↳ invoiceLineHsnCode`	String	The Harmonized System of Nomenclature (HSN) Code for the product	Check Resources for valid HSN codes e.g., `"1006.2"`
`↳ invoiceLineItemName`	String	The name of the item/service being sold	`"50kg Bag of Rice"`
`↳ invoiceLineItemDescription`	String	The description of the item/service being sold	`"Premium long-grain brown rice"`
`↳ invoiceLineItemSellersItemIdentification`	String	Seller's SKU or item identifier	`"Rice-50KG-001"`
`↳ invoiceLineInvoicedQuantity`	Number	Quantity of items invoiced	`10`
`↳ invoiceLineExtensionAmount`	Number	Total line amount (price × quantity + fees - discounts)	`200000`
`↳ invoiceLinePriceAmount`	Number	Price per unit	`20000`
`↳ invoiceLinePriceBaseQuantity`	Number	Base quantity for pricing	`1`
`↳ invoiceLinePriceUnit`	String	Unit of measurement for pricing	`EA`
`↳ invoiceLineDiscountRate`	Number	Discount percentage applied to line. Range: 0-100	`0`
`↳ invoiceLineDiscountAmount`	Number	Discount amount applied to line item (≥ 0)	`0`
`↳ invoiceLineFeeRate`	Number	Additional fee percentage (≥ 0)	`0`
`↳ invoiceLineFeeAmount`	Number	Additional fee amount (≥ 0)	`0`
`invoiceTaxTotal`	Array	Array of tax totals for the invoice	-
`↳ invoiceTaxTotalAmount`	Number	Total tax amount for all tax subtotals	`15000`
`↳ invoiceTaxTotalSubTotal`	Array	Breakdown of tax by category	-
`↳ taxSubTotalTaxableAmount`	Number	The total value of goods/services on which tax is calculated	`2000000`
`↳ taxSubTotalTaxAmount`	Number	The actual tax applied on the taxable amount	`15000`
`↳ taxSubTotalCategoryPercent`	Number	Tax rate percentage applied to this subtotal	`7.5`
`↳ taxSubTotalCategoryId`	String	Tax category identifier	Check Resources for valid tax category identifiers e.g., `"STANDARD_VAT"`
`invoiceLineExtensionAmount`	Number	The total amount of all invoice items before tax and any discounts/charges	`200000`
`invoiceTaxInclusiveAmount`	Number	The total invoice after tax is added	`215000`
`invoiceTaxExclusiveAmount`	Number	The total invoice amount before tax is added	`200000`
`invoicePayableAmount`	Number	The final amount the buyer must pay after applying discounts, charges, and tax	`215000`

📝 Additional Optional Fields

Field	Type	Description	Example
`invoiceDueDate`	Date	The date on which the invoice is due for payment. Format: YYYY-MM-DD	`"2025-03-29"`
`invoiceIssueTime`	String	The time at which this document was issued. Format: HH:MM:SS (24-hour)	`"17:59:04"`
`requestType`	String	Specifies the type of invoice being sent (B2B, B2G, or B2C)	`"B2B"`
`invoicePaymentStatus`	String	Shows whether the invoice has been paid or is still pending. Defaults to "PENDING"	`"PENDING"` or `"PAID"`
`invoiceActualDeliveryDate`	Date	The date the goods or services were delivered. Format: YYYY-MM-DD	`"2024-05-14"`
`invoicePaymentMeans`	Array	Defines how the invoice will be paid and when payment is due	-
`↳ invoicePaymentMeansCode`	Number	Payment method code (e.g., 10=Cash, 42=Bank transfer, 43=Credit card)	Check Resources for valid payment means codes e.g., `10`
`↳ invoicePaymentMeansDate`	Date	Date when payment is due. Format: YYYY-MM-DD	`"2024-05-14"`
`invoicePaymentTermsNote`	String	Describes the terms and conditions of payment	`"Payment due within 30 days of invoice issue."`
`invoiceAllowanceCharge`	Array	Defines any discounts (allowance) or extra charges (charge)	-
`↳ invoiceAllowanceChargeIndicator`	Boolean	`true` = charge (additional fee), `false` = allowance (discount)	`true`
`↳ invoiceAllowanceChargeAmount`	Number	Amount of the charge or allowance	`800.6`
`invoiceNote`	String	Free-form text pertinent to the invoice. Stored in encrypted format for security	`"This invoice includes a 5% discount."`
`invoiceTaxPointDate`	Date	The actual date when the tax becomes applicable. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceAccountingCost`	Number	Represents the accounting category or cost center assigned to the transaction	`2000`
`invoiceBuyerReference`	String	A reference number or code provided by the buyer to track the invoice	`"ITW001-E9E0C0D3-20240619"`
`invoiceDeliveryPeriodStartDate`	Date	Start date for when goods or services were delivered. Format: YYYY-MM-DD	`"2024-06-14"`
`invoiceDeliveryPeriodEndDate`	Date	End date for when goods or services were delivered. Format: YYYY-MM-DD	`"2024-06-16"`
`invoiceOrderReference`	String	The order number tied to the invoice	`"ITW001-E9E0C0D3-20240619"`
`invoiceBillingReference`	Array	Links the invoice to previous billing documents (e.g., credit notes, debit notes, or prior invoices)	-
`↳ invoiceDocumentReferenceIrn`	String	Invoice Reference Number of the billing document	`"ITW001-E9E0C0D3-20240619"`
`↳ invoiceDocumentReferenceIssueDate`	Date	Issue date of the billing document. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceDispatchDocumentIrn`	String	Identifier of a referenced dispatch advice. Tracks the dispatch of goods	`"ITW001-E9E0C0D3-20240619"`
`invoiceDispatchDocumentIssueDate`	Date	Issue date of the dispatch document. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceReceiptDocumentIrn`	String	Reference to a Receipt Advice associated with the invoice	`"ITW001-E9E0C0D3-20240619"`
`invoiceReceiptDocumentIssueDate`	Date	Issue date of the receipt document. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceOriginatorDocumentIrn`	String	Reference to the original document that initiated the invoice	`"ITW001-E9E0C0D3-20240619"`
`invoiceOriginatorDocumentIssueDate`	Date	Issue date of the originator document. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceContractDocumentIrn`	String	Reference to a contract governing the transaction	`"ITW001-E9E0C0D3-20240619"`
`invoiceContractDocumentIssueDate`	Date	Issue date of the contract document. Format: YYYY-MM-DD	`"2024-05-14"`
`invoiceAdditionalDocumentReference`	Array	Reference to additional documents associated with the invoice	-
`↳ invoiceDocumentReferenceIrn`	String	Invoice Reference Number of the additional document	`"ITW001-E9E0C0D3-20240619"`
`↳ invoiceDocumentReferenceIssueDate`	Date	Issue date of the additional document. Format: YYYY-MM-DD	`"2024-05-14"`

💳 Additional Optional Fields - Payee Party

If the payment goes to someone else, this field captures that entity's details.

Field	Type	Description	Example
`invoicePayeeStreetName`	String	The street name where the payee's business is located	`"15, Glover Road"`
`invoicePayeeCityName`	String	The city where the payee's business is registered	`"Ikoyi"`
`invoicePayeeLga`	String	The local government code of the payee	Check Resources for valid LGA codes
`invoicePayeeState`	String	The state code of the payee	Check Resources for valid state codes
`invoicePayeeCountry`	String	The country code representing the payee's registered country (ISO 3166-1 Alpha-2)	Check Resources for valid country codes
`invoicePayeePostalZone`	String	The official postal zone address of the payee	`"100243"`
`invoicePayeePartyBusinessDescription`	String	A brief description of the payee's line of business	`"Cement and building materials"`
`invoicePayeePartyTin`	String	The Taxpayer Identification Number (TIN) assigned to the payee for tax compliance	`"24058123-0001"`
`invoicePayeePartyEmail`	String	The payee's official email address used for tax communication and invoicing correspondence	`"payee_business@email.com"`
`invoicePayeePartyTelephone`	String	The payee's contact number with country code prefix (+234 for Nigeria)	`"+23480254099000"`
`invoicePayeePartyName`	String	The registered name of the payee. Legal business name as recognized by tax authorities	`"XYZ Ltd."`

📄 Additional Optional Fields - Bill Party

If the invoice is billed to someone else, this field captures that entity's details.

Field	Type	Description	Example
`invoiceBillPartyStreetName`	String	The street name where the bill party's business is located	`"15, Glover Road"`
`invoiceBillPartyCityName`	String	The city where the bill party's business is registered	`"Ikoyi"`
`invoiceBillPartyLga`	String	The local government code of the bill party	Check Resources for valid LGA codes
`invoiceBillPartyState`	String	The state code of the bill party	Check Resources for valid state codes
`invoiceBillPartyCountry`	String	The country code representing the bill party's registered country (ISO 3166-1 Alpha-2)	Check Resources for valid country codes
`invoiceBillPartyPostalZone`	String	The official postal zone address of the bill party	`"100243"`
`invoiceBillPartyBusinessDescription`	String	A brief description of the bill party's line of business	`"Cement and building materials"`
`invoiceBillPartyTin`	String	The Taxpayer Identification Number (TIN) assigned to the bill party for tax compliance	`"24058123-0001"`
`invoiceBillPartyEmail`	String	The bill party's official email address used for tax communication and invoicing correspondence	`"billparty_business@email.com"`
`invoiceBillPartyTelephone`	String	The bill party's contact number with country code prefix (+234 for Nigeria)	`"+23480254099000"`
`invoiceBillPartyName`	String	The registered name of the bill party. Legal business name as recognized by tax authorities	`"XYZ Ltd."`

🚚 Additional Optional Fields - Ship Party

If goods are shipped to someone else, this field captures that entity's details.

Field	Type	Description	Example
`invoiceShipPartyStreetName`	String	The street name where the ship party's business is located	`"15, Glover Road"`
`invoiceShipPartyCityName`	String	The city where the ship party's business is registered	`"Ikoyi"`
`invoiceShipPartyLga`	String	The local government code of the ship party	Check Resources for valid LGA codes
`invoiceShipPartyState`	String	The state code of the ship party	Check Resources for valid state codes
`invoiceShipPartyCountry`	String	The country code representing the ship party's registered country (ISO 3166-1 Alpha-2)	Check Resources for valid country codes
`invoiceShipPartyPostalZone`	String	The official postal zone address of the ship party	`"100243"`
`invoiceShipPartyBusinessDescription`	String	A brief description of the ship party's line of business	`"Cement and building materials"`
`invoiceShipPartyTin`	String	The Taxpayer Identification Number (TIN) assigned to the ship party for tax compliance	`"24058123-0001"`
`invoiceShipPartyEmail`	String	The ship party's official email address used for tax communication and invoicing correspondence	`"shipparty_business@email.com"`
`invoiceShipPartyTelephone`	String	The ship party's contact number with country code prefix (+234 for Nigeria)	`"+23480254099000"`
`invoiceShipPartyName`	String	The registered name of the ship party. Legal business name as recognized by tax authorities	`"XYZ Ltd."`

🏛️ Additional Optional Fields - Tax Representative Party

If a business has a tax agent handling invoicing and compliance, their details are entered here.

Field	Type	Description	Example
`invoiceTaxRepPartyStreetName`	String	The street name where the tax representative's business is located	`"15, Glover Road"`
`invoiceTaxRepPartyCityName`	String	The city where the tax representative's business is registered	`"Ikoyi"`
`invoiceTaxRepPartyLga`	String	The local government code of the tax representative	Check Resources for valid LGA codes
`invoiceTaxRepPartyState`	String	The state code of the tax representative	Check Resources for valid state codes
`invoiceTaxRepPartyCountry`	String	The country code representing the tax representative's registered country (ISO 3166-1 Alpha-2)	Check Resources for valid country codes
`invoiceTaxRepPartyPostalZone`	String	The official postal zone address of the tax representative	`"100243"`
`invoiceTaxRepPartyBusinessDescription`	String	A brief description of the tax representative's line of business	`"Tax and accounting services"`
`invoiceTaxRepPartyTin`	String	The Taxpayer Identification Number (TIN) assigned to the tax representative for tax compliance	`"24058123-0001"`
`invoiceTaxRepPartyEmail`	String	The tax representative's official email address used for tax communication and invoicing correspondence	`"taxrep_business@email.com"`
`invoiceTaxRepPartyTelephone`	String	The tax representative's contact number with country code prefix (+234 for Nigeria)	`"+23480254099000"`
`invoiceTaxRepPartyName`	String	The registered name of the tax representative. Legal business name as recognized by tax authorities	`"ABC Tax Consultants Ltd."`

📝 Example Request

{
  // Core Invoice Details
  "invoiceBusinessId": "", // mandatory
  "invoiceIssueDate": "", // mandatory (YYYY-MM-DD)
  "invoiceTypeCode": "", // mandatory
  "invoiceDocumentCurrencyCode": "", // mandatory
  "invoiceTaxCurrencyCode": "", // mandatory
  
  // Supplier Information
  "invoiceSupplierStreetName": "", // mandatory
  "invoiceSupplierCityName": "", // mandatory
  "invoiceSupplierLga": "", // mandatory
  "invoiceSupplierState": "", // mandatory
  "invoiceSupplierCountry": "", // mandatory
  "invoiceSupplierPostalZone": "", // mandatory
  "invoiceSupplierPartyBusinessDescription": "", // mandatory
  "invoiceSupplierPartyTin": "", // mandatory
  "invoiceSupplierPartyEmail": "", // mandatory
  "invoiceSupplierPartyTelephone": "", // mandatory
  "invoiceSupplierPartyName": "", // mandatory
  
  // Customer Information
  "invoiceCustomerStreetName": "", // mandatory for B2B 
  "invoiceCustomerCityName": "", // mandatory for B2B
  "invoiceCustomerLga": "", // mandatory for B2B
  "invoiceCustomerState": "", // mandatory for B2B
  "invoiceCustomerCountry": "", // mandatory for B2B
  "invoiceCustomerPostalZone": "", // mandatory for B2B
  "invoiceCustomerPartyBusinessDescription": "", // mandatory for B2B
  "invoiceCustomerPartyTin": "", // mandatory for B2B
  "invoiceCustomerPartyEmail": "", // mandatory for B2B
  "invoiceCustomerPartyTelephone": "", // mandatory for B2B
  "invoiceCustomerPartyName": "", // mandatory for B2B
  
  // Invoice Line Items
  "invoiceLine": [ // mandatory (at least one item)
    {
      "invoiceLineProductCategory": "", // mandatory
      "invoiceLineHsnCode": "", // mandatory
      "invoiceLineItemName": "", // mandatory
      "invoiceLineItemDescription": "", // mandatory
      "invoiceLineItemSellersItemIdentification": "", // mandatory
      "invoiceLineInvoicedQuantity": 0, // mandatory
      "invoiceLineExtensionAmount": 0, // mandatory
      "invoiceLinePriceAmount": 0, // mandatory
      "invoiceLinePriceBaseQuantity": 0, // mandatory
      "invoiceLinePriceUnit": "", // mandatory
      "invoiceLineDiscountRate": 0, // optional (0-100)
      "invoiceLineDiscountAmount": 0, // optional
      "invoiceLineFeeRate": 0, // optional
      "invoiceLineFeeAmount": 0 // optional
    }
  ],
  
  // Tax Information
  "invoiceTaxTotal": [ // mandatory (at least one item)
    {
      "invoiceTaxTotalAmount": 0, // mandatory
      "invoiceTaxTotalSubTotal": [ // mandatory (at least one item)
        {
          "taxSubTotalTaxableAmount": 0, // mandatory
          "taxSubTotalTaxAmount": 0, // mandatory
          "taxSubTotalCategoryPercent": 0, // mandatory
          "taxSubTotalCategoryId": "" // mandatory
        }
      ]
    }
  ],
  
  // Financial Totals
  "invoiceLineExtensionAmount": 0, // mandatory
  "invoiceTaxInclusiveAmount": 0, // mandatory
  "invoiceTaxExclusiveAmount": 0, // mandatory
  "invoicePayableAmount": 0, // mandatory
  
  // Optional Fields
  "invoiceDueDate": "", // optional (YYYY-MM-DD)
  "invoiceIssueTime": "", // optional (HH:MM:SS)
  "requestType": "", // optional (B2B, B2G, or B2C)
  "invoicePaymentStatus": "", // optional (PENDING or PAID)
  "invoiceActualDeliveryDate": "", // optional (YYYY-MM-DD)
  
  "invoicePaymentMeans": [ // optional
    {
      "invoicePaymentMeansCode": 0, // optional
      "invoicePaymentMeansDate": "" // optional (YYYY-MM-DD)
    }
  ],
  
  "invoicePaymentTermsNote": "", // optional
  
  "invoiceAllowanceCharge": [ // optional
    {
      "invoiceAllowanceChargeIndicator": true, // optional (true=charge, false=allowance)
      "invoiceAllowanceChargeAmount": 0 // optional
    }
  ],
  
  "invoiceNote": "", // optional
  "invoiceTaxPointDate": "", // optional (YYYY-MM-DD)
  "invoiceAccountingCost": 0, // optional
  "invoiceBuyerReference": "", // optional
  "invoiceDeliveryPeriodStartDate": "", // optional (YYYY-MM-DD)
  "invoiceDeliveryPeriodEndDate": "", // optional (YYYY-MM-DD)
  "invoiceOrderReference": "", // optional
  
  // Document References
  "invoiceBillingReference": [ // optional
    {
      "invoiceDocumentReferenceIrn": "", // optional
      "invoiceDocumentReferenceIssueDate": "" // optional (YYYY-MM-DD)
    }
  ],
  
  "invoiceDispatchDocumentIrn": "", // optional
  "invoiceDispatchDocumentIssueDate": "", // optional (YYYY-MM-DD)
  "invoiceReceiptDocumentIrn": "", // optional
  "invoiceReceiptDocumentIssueDate": "", // optional (YYYY-MM-DD)
  "invoiceOriginatorDocumentIrn": "", // optional
  "invoiceOriginatorDocumentIssueDate": "", // optional (YYYY-MM-DD)
  "invoiceContractDocumentIrn": "", // optional
  "invoiceContractDocumentIssueDate": "", // optional (YYYY-MM-DD)
  
  "invoiceAdditionalDocumentReference": [ // optional
    {
      "invoiceDocumentReferenceIrn": "", // optional
      "invoiceDocumentReferenceIssueDate": "" // optional (YYYY-MM-DD)
    }
  ],
  
  // Payee Party (optional - if payment goes to someone else)
  "invoicePayeeStreetName": "", // optional
  "invoicePayeeCityName": "", // optional
  "invoicePayeeLga": "", // optional
  "invoicePayeeState": "", // optional
  "invoicePayeeCountry": "", // optional
  "invoicePayeePostalZone": "", // optional
  "invoicePayeePartyBusinessDescription": "", // optional
  "invoicePayeePartyTin": "", // optional
  "invoicePayeePartyEmail": "", // optional
  "invoicePayeePartyTelephone": "", // optional
  "invoicePayeePartyName": "", // optional
  
  // Bill Party (optional - if invoice is billed to someone else)
  "invoiceBillPartyStreetName": "", // optional
  "invoiceBillPartyCityName": "", // optional
  "invoiceBillPartyLga": "", // optional
  "invoiceBillPartyState": "", // optional
  "invoiceBillPartyCountry": "", // optional
  "invoiceBillPartyPostalZone": "", // optional
  "invoiceBillPartyBusinessDescription": "", // optional
  "invoiceBillPartyTin": "", // optional
  "invoiceBillPartyEmail": "", // optional
  "invoiceBillPartyTelephone": "", // optional
  "invoiceBillPartyName": "", // optional
  
  // Ship Party (optional - if goods are shipped to someone else)
  "invoiceShipPartyStreetName": "", // optional
  "invoiceShipPartyCityName": "", // optional
  "invoiceShipPartyLga": "", // optional
  "invoiceShipPartyState": "", // optional
  "invoiceShipPartyCountry": "", // optional
  "invoiceShipPartyPostalZone": "", // optional
  "invoiceShipPartyBusinessDescription": "", // optional
  "invoiceShipPartyTin": "", // optional
  "invoiceShipPartyEmail": "", // optional
  "invoiceShipPartyTelephone": "", // optional
  "invoiceShipPartyName": "", // optional
  
  // Tax Representative Party (optional - if tax agent handles invoicing)
  "invoiceTaxRepPartyStreetName": "", // optional
  "invoiceTaxRepPartyCityName": "", // optional
  "invoiceTaxRepPartyLga": "", // optional
  "invoiceTaxRepPartyState": "", // optional
  "invoiceTaxRepPartyCountry": "", // optional
  "invoiceTaxRepPartyPostalZone": "", // optional
  "invoiceTaxRepPartyBusinessDescription": "", // optional
  "invoiceTaxRepPartyTin": "", // optional
  "invoiceTaxRepPartyEmail": "", // optional
  "invoiceTaxRepPartyTelephone": "", // optional
  "invoiceTaxRepPartyName": "" // optional
}

📤 Response Format

Success Response (200)

{
  "data": {
    "invoiceId": 132,
    "invoiceCreatedAt": "2025-08-26T12:57:15Z",
    "invoiceStatus": "CREATED",
    "invoiceNumber": "INV236",
    "invoiceNote": "August Electricity Bill - Mr Ridwan",
    "invoiceBusinessId": "b4009129-ece8-45fc-9584-976fcbe35f8d",
    "invoiceEntityId": "107",
    "invoiceIssueDate": "2025-08-26",
    "invoiceDueDate": "2025-08-26",
    "invoiceIssueTime": "12:57:15",
    "invoiceTypeCode": "389",
    "invoicePaymentStatus": "PAID",
    "invoiceDocumentCurrencyCode": "NGN",
    "invoiceTaxCurrencyCode": "NGN",
    "invoicePayableAmount": 30255.22,
    "invoiceTaxExclusiveAmount": 30030.0,
    "invoiceTaxInclusiveAmount": 30255.22,
    "invoiceLineExtensionAmount": 30030.0
  },
  "responseCode": "200",
  "responseMessage": "Invoice created successfully"
}

✅ Validation Rules

Required Field Validation

All fields marked mandatory must be provided

Arrays marked as required cannot be empty

supplier_party_tin: minimum 6 characters

supplier_party_email: valid email format required

supplier_party_business_description: minimum 6 characters

Data Format Validation

Dates: Must use YYYY-MM-DD format

Numbers: Must meet minimum value requirements (≥ 0 or > 0 as specified)

Strings: Accept text values

Booleans: Accept true/false values

Arrays: Must contain objects with specified structure

Business Logic Validation

At least one invoice line item must be provided

At least one tax total must be provided

Monetary amounts must be consistent across totals

Tax calculations must align with line item amounts

Create Invoice

Request Structure#

Headers#

Path Parameters#

Request Body#

📋 Mandatory Invoice Details#

📝 Additional Optional Fields#

💳 Additional Optional Fields - Payee Party#

📄 Additional Optional Fields - Bill Party#

🚚 Additional Optional Fields - Ship Party#

🏛️ Additional Optional Fields - Tax Representative Party#

📝 Example Request#

📤 Response Format#

Success Response (200)#

✅ Validation Rules#

Required Field Validation#

Data Format Validation#

Business Logic Validation#

Request

Responses