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

{
  "requesttype": "MINIMAL",
  "invoice_number": "INV236",
  "business_id": "b4009129-ece8-45fc-9584-976fcbe35f8d",
  "entity_id": "107",
  "issue_date": "2025-08-26",
  "due_date": "2025-08-26",
  "issue_time": "12:57:15",
  "invoice_type_code": "389",
  "payment_status": "PAID",
  "note": "August Electricity Bill - Mr Ridwan",
  "tax_point_date": "2025-08-26",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  
  "customer_party_id": "b1261670-67a3-44d6-b38e-2dddd5dd1454",
  "customer_party_tin": "68721523-8104",
  "customer_party_email": "supplier_business@email.com",
  "customer_party_telephone": "+23480254099000",
  "customer_party_business_description": "this entity is into sales of Cement and building materials",
  "customer_party_name": "Dangote Group",
  "customer_city_name": "Gwarikpa",
  "customer_postal_zone": "023401",
  "customer_country": "NG",
  "customer_street_name": "32, owonikoko street",
  "customer_lga": "Aba",
  "customer_state": "Abia",
  
  "supplier_party_id": "b4009129-ece8-45fc-9584-976fcbe35f8d",
  "supplier_party_tin": "68721523-8104",
  "supplier_party_email": "redtech@gmail.com",
  "supplier_party_telephone": "+234447784433",
  "supplier_party_business_description": "AEDC Electricity Supply",
  "supplier_party_name": "alias-sit-fuga-ex",
  "supplier_lga": "Aba",
  "supplier_state": "Abia",
  "supplier_city_name": "Aba",
  "supplier_postal_zone": "101245",
  "supplier_country": "NG",
  "supplier_street_name": "vi",
  
  "line_extension_amount": 30030.0,
  "tax_exclusive_amount": 30030.0,
  "tax_inclusive_amount": 30255.22,
  "payable_amount": 30255.22,
  
  "allowance_charge": [
    {
      "allowanceChargeIndicator": false,
      "allowanceChargeReason": "Early payment discount",
      "allowanceChargeReasonCode": "95",
      "allowanceChargeAmount": 150.0,
      "allowanceChargeBaseAmount": 30030.0,
      "allowanceChargeMultiplierFactorNumeric": 0.005
    }
  ],
  
  "invoice_line": [
    {
      "hsn_code": "2716.00",
      "product_category": "Electrical energy",
      "invoiced_quantity": 200.0,
      "line_extension_amount": 30030.0,
      "item_name": "Electricity Supply",
      "item_description": "Electricity Units",
      "price_amount": 150.0,
      "price_base_quantity": 1.0,
      "price_unit": "NGN PER 1"
    }
  ],
  
  "tax_total": [
    {
      "tax_amount": 225.22,
      "tax_subtotal": [
        {
          "taxable_amount": 30030.0,
          "tax_amount": 225.22,
          "category_id": "STANDARD_VAT",
          "category_percent": 0.75
        }
      ]
    }
  ]
}

✅ 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

{
  "requestType": "B2B",
  "invoiceNumber": "INV2025001",
  "invoiceBusinessId": "26ede24b-ac50-475f-aacc-5ea6339f0863",
  "invoiceIssueDate": "2025-09-17",
  "invoiceDueDate": "2025-10-17",
  "invoiceIssueTime": "14:30:00",
  "invoiceTypeCode": "389",
  "invoicePaymentStatus": "UNPAID",
  "invoiceNote": "Monthly Software License Renewal",
  "invoiceTaxPointDate": "2025-09-17",
  "invoiceDocumentCurrencyCode": "NGN",
  "invoiceTaxCurrencyCode": "NGN",
  "invoiceCustomerPartyId": "b1261670-67a3-44d6-b38e-2dddd5dd1454",
  "invoiceCustomerPartyTin": "68721523-8104",
  "invoiceCustomerPartyEmail": "supplier_business@email.com",
  "invoiceCustomerPartyTelephone": "+23480254099000",
  "invoiceCustomerPartyBusinessDescription": "this entity is into sales of Cement and building materials",
  "invoiceCustomerPartyName": "Dangote Group",
  "invoiceCustomerCityName": "Gwarikpa",
  "invoiceCustomerPostalZone": "023401",
  "invoiceCustomerCountry": "NG",
  "invoiceCustomerStreetName": "32, owonikoko street",
  "invoiceCustomerLga": "Aba",
  "invoiceCustomerState": "Abia",
  "invoiceSupplierPartyId": "b4009129-ece8-45fc-9584-976fcbe35f8d",
  "invoiceSupplierPartyTin": "68721523-8104",
  "invoiceSupplierPartyEmail": "redtech@gmail.com",
  "invoiceSupplierPartyTelephone": "+234447784433",
  "invoiceSupplierPartyBusinessDescription": "AEDC Electricity Supply",
  "invoiceSupplierPartyName": "alias-sit-fuga-ex",
  "invoiceSupplierLga": "Aba",
  "invoiceSupplierState": "Abia",
  "invoiceSupplierCityName": "Aba",
  "invoiceSupplierPostalZone": "101245",
  "invoiceSupplierCountry": "NG",
  "invoiceSupplierStreetName": "vi",
  "invoiceLineExtensionAmount": 250000.0,
  "invoiceTaxExclusiveAmount": 250000.0,
  "invoiceTaxInclusiveAmount": 268750.0,
  "invoicePayableAmount": 268750.0,
  "invoiceAllowanceCharge": [
    {
      "invoiceAllowanceChargeIndicator": false,
      "invoiceAllowanceChargeAmount": 12500.0
    }
  ],
  "invoiceLine": [
    {
      "invoiceLineHsnCode": "8523.49",
      "invoiceLineProductCategory": "Software Services",
      "invoiceLineInvoicedQuantity": 12.0,
      "invoiceLineExtensionAmount": 250000.0,
      "invoiceLineItemName": "Enterprise Software License",
      "invoiceLineItemDescription": "Annual subscription for enterprise project management software - 50 users",
      "invoiceLinePriceAmount": 20833.33,
      "invoiceLinePriceBaseQuantity": 1.0,
      "invoiceLinePriceUnit": "NGN PER MONTH"
    }
  ],
  "invoiceTaxTotal": [
    {
      "invoiceTaxTotalAmount": 18750.0,
      "invoiceTaxTotalSubTotal": [
        {
          "taxSubTotalTaxableAmount": 250000.0,
          "taxSubTotalTaxAmount": 18750.0,
          "taxSubTotalCategoryId": "STANDARD_VAT",
          "taxSubTotalCategoryPercent": 7.5
        }
      ]
    }
  ]
}

Response

Response Status

200 OK
201 Created

401 Unauthorized
403 Forbidden
404 Not Found

Quick Reference

Request Structure

Path Parameters

Request Body

📋 Core Invoice Details

Additional Optional Fields

👤 Customer Information

Contact Details

Address Information

🏢 Supplier Information

Contact Details

Address Information

💰 Financial Information

Monetary Totals

Allowances & Charges

📋 Invoice Line Items

Line Item Structure

🧾 Tax Information

Tax Totals

Tax Subtotal Structure

📄 Document References

Additional References

📤 Response Format

Success Response (200)

📝 Example Request

✅ Validation Rules

Required Field Validation

Data Format Validation

Business Logic Validation

🔗 Related Endpoints

Required Field Validation

Request

Header Params

Body Params

Example

Response

Response Status

Exellent

Watch our journey

Let’s Make Things Happen!

Dilip Sadh

Kabeer Consulting Group

Global SAP Partner

Connect with us at:

Grow Your Business Strategically, and Improve Customer Retention.

Services

Company

Our Presence

We are at:

Grow Your Business Strategically, and Improve Customer Retention.

Connect with us at:

We are at:

Company

Services

Our Presence

Book your Seat

Few seats are left!

SAP ERP Demo for Your Industry