Create Invoice

Create a new invoice for a specified business with detailed information including amounts, customer details, and line items.

Quick Reference

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

Request Structure

Path Parameters

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

Request Body

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

📋 Core Invoice Details

Field Type Required Description Validation
requesttype string Type of request Default: “B2C” (Business to Customer), “B2B” (Business to Business)
invoice_number string Unique invoice identifier
business_id string Business ID for the invoice
entity_id string Entity ID for the invoice
issue_date string Invoice issue date Format: YYYY-MM-DD
irn string Invoice Reference Number
due_date string Payment due date
issue_time string Invoice issue time
invoice_type_code string ✅ Invoice type code
payment_status string ✅ Payment status
note string Additional notes
tax_point_date string Tax point date
document_currency_code string ✅ Invoice currency code
tax_currency_code string Tax currency code

Additional Optional Fields

Field Type Description
accounting_cost string Accounting cost reference
buyer_reference string Buyer reference number
order_reference string Order reference number
actual_delivery_date string Actual delivery date
payment_terms_note string Payment terms details

👤 Customer Information

All customer fields are optional

Contact Details

Field Type Description
customer_party_id string Customer party ID
customer_party_tin string Customer Tax ID
customer_party_email string Customer email
customer_party_telephone string Customer phone
customer_party_name string Customer name
customer_party_business_description string Customer business description

Address Information

Field Type Description
customer_city_name string Customer city
customer_postal_zone string Customer postal code
customer_country string Customer country
customer_street_name string Customer street
customer_lga string Local Government Area
customer_state string Customer state

🏢 Supplier Information

Required fields for supplier details

Contact Details

Field Type Required Description Validation
supplier_party_id string Supplier party ID
supplier_party_tin string ✅ Supplier Tax ID Min 6 characters
supplier_party_email string ✅ Supplier email Valid email format
supplier_party_telephone string Supplier phone
supplier_party_name string ✅ Supplier name
supplier_party_business_description string ✅ Business description Min 6 characters

Address Information

Field Type Required Description
supplier_lga string ✅ Local Government Area
supplier_state string ✅ Supplier state
supplier_city_name string ✅ Supplier city
supplier_postal_zone string ✅ Supplier postal code
supplier_country string ✅ Supplier country
supplier_street_name string ✅ Supplier street

💰 Financial Information

Monetary Totals

All amounts are required and must be ≥ 0

Field Type Required Description
line_extension_amount number ✅ Line extension amount
tax_exclusive_amount number ✅ Amount excluding tax
tax_inclusive_amount number ✅ Amount including tax
payable_amount number ✅ Total payable amount

Allowances & Charges

Field Type Description
allowance_charge array Array of allowances/charges
allowance_charge[].invoiceAllowanceChargeIndicator boolean false = allowance, true = charge
allowance_charge[].invoiceAllowanceChargeAmount number Amount of allowance/charge

📋 Invoice Line Items

Required: At least one line item must be provided

Field Type Required Description Validation
invoice_line array ✅ Array of line items Cannot be empty

Line Item Structure

Field Type Required Description Validation
hsn_code string ✅ HSN code for item
product_category string ✅ Product category
invoiced_quantity number ✅ Quantity invoiced Must be > 0
line_extension_amount number ✅ Line item amount Must be ≥ 0
item_name string ✅ Item name
item_description string ✅ Item description
price_amount number ✅ Price per unit Must be ≥ 0
price_base_quantity number ✅ Base quantity for pricing Must be > 0
price_unit string ✅ Price unit

🧾 Tax Information

Required: Tax totals must be provided

Tax Totals

Field Type Required Description
tax_total array ✅ Array of tax totals
tax_total[].tax_amount number ✅ Total tax amount
tax_total[].tax_subtotal array ✅ Array of tax subtotals

Tax Subtotal Structure

Field Type Required Description Validation
taxable_amount number ✅ Taxable amount Must be ≥ 0
tax_amount number ✅ Tax amount Must be ≥ 0
category_id string ✅ Tax category ID
category_percent number ✅ Tax percentage Must be ≥ 0

📄 Document References

All document reference fields are optional

Field Type Description
contract_document_irn string Contract document IRN
contract_document_issue_date string Contract issue date
originator_document_irn string Originator document IRN
originator_document_issue_date string Originator issue date
receipt_document_irn string Receipt document IRN
receipt_document_issue_date string Receipt issue date
dispatch_document_irn string Dispatch document IRN
dispatch_document_issue_date string Dispatch issue date
delivery_period_start_date string Delivery start date
delivery_period_end_date string Delivery end date

Additional References

Field Type Description
additional_document_reference array Additional document references
billing_reference array Billing references
payment_means array Payment means information

📤 Response Format

Success Response (200)

Copy to Clipboard

📝 Example Request

Copy to Clipboard

✅ Validation Rules

Required Field Validation

  • All fields marked with ✅ 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

🔗 Related Endpoints

Required Field Validation

This endpoint is part of the invoice management system. Consider these related operations:

  • GET /invoices/ – Retrieve invoice details
  • PUT /invoices/ – Update invoice
  • DELETE /invoices/ – Cancel invoice
  • GET /invoices – List invoices

This endpoint is essential for managing invoices within the system, ensuring all necessary details are captured for processing and tracking.

Request

Header Params

Header Type Required Description Example
X-Business-Key string ✅ (Required) X-Business-Key BK-26EDE24BAC50475FAACC5EA6339F0863-DEV-B2Z6QCEHI3X9
Content-Type string ✅ Specifies content format application/json
Accept string ✅ Accepted response type */*

Body Params

Field Type Required
requestType string Optional
invoiceNumber string ✅ Required
invoiceBusinessId string ✅ Required
invoiceEntityId string ✅ Required
invoiceIssueDate string ✅ Required
invoiceDueDate string ✅ Required
invoiceIssueTime string ✅ Required
invoiceTypeCode string ✅ Required
invoicePaymentStatus string ✅ Required
invoiceNote string ✅ Required
invoiceTaxPointDate string ✅ Required
invoiceDocumentCurrencyCode string ✅ Required
invoiceTaxCurrencyCode string ✅ Required
invoiceCustomerPartyTin string ✅ Required
invoiceCustomerPartyEmail string ✅ Required
invoiceCustomerPartyTelephone string ✅ Required
invoiceCustomerPartyBusinessDescription string ✅ Required
invoiceCustomerPartyName string ✅ Required
invoiceCustomerCityName string ✅ Required
invoiceCustomerPostalZone string ✅ Required
invoiceCustomerCountry string ✅ Required
invoiceCustomerStreetName string ✅ Required
invoiceCustomerLga string ✅ Required
invoiceCustomerState string ✅ Required
invoiceSupplierPartyTin string ✅ Required
invoiceSupplierPartyEmail string ✅ Required
invoiceSupplierPartyTelephone string ✅ Required
invoiceSupplierPartyBusinessDescription string ✅ Required
invoiceSupplierPartyName string ✅ Required
invoiceSupplierLga string ✅ Required
invoiceSupplierState string ✅ Required
invoiceSupplierCityName string ✅ Required
invoiceSupplierPostalZone string ✅ Required
invoiceSupplierCountry string ✅ Required
invoiceSupplierStreetName string ✅ Required
invoiceLineExtensionAmount integer ✅ Required
invoiceTaxExclusiveAmount integer ✅ Required
invoiceTaxInclusiveAmount integer ✅ Required
invoicePayableAmount integer ✅ Required
invoiceAllowanceCharge array [object] ✅ Required
invoiceAllowanceChargeIndicator boolean Optional
invoiceAllowanceChargeAmount integer Optional
invoiceLine array [object] ✅ Required
invoiceLineHsnCode string ✅ Required
invoiceLineProductCategory string ✅ Required
invoiceLineInvoicedQuantity integer ✅ Required
invoiceLineExtensionAmount integer ✅ Required
invoiceLineItemName string ✅ Required
invoiceLineItemDescription string ✅ Required
invoiceLinePriceAmount number ✅ Required
invoiceLinePriceBaseQuantity integer ✅ Required
invoiceLinePriceUnit string ✅ Required
invoiceTaxTotal array [object] ✅ Required
invoiceTaxTotalAmount integer ✅ Required
invoiceTaxTotalSubTotal array [object] ✅ Required

Example

Copy to Clipboard

Response

Response Status

  • 200 OK

  • 201 Created

  • 401 Unauthorized

  • 403 Forbidden

  • 404 Not Found