Nigeria E-Invoicing Mandates

The Federal Inland Revenue Service (FIRS) has introduced mandatory e-invoicing as part of Nigeria's tax modernization strategy. This section outlines the key mandates affecting businesses operating in Nigeria.

FIRS E-Invoicing Mandate

The FIRS has implemented a mandatory e-invoicing system through the FIRS Merchant-Buyer Solution (FIRSMBS) platform based on international Peppol BIS Billing 3.0 UBL standards.

What is FIRSMBS?

FIRSMBS (FIRS Merchant-Buyer Solution) is Nigeria's central electronic invoicing platform that validates, stamps, and tracks all taxable invoices. Every invoice must be submitted to FIRSMBS for clearance before being sent to the buyer (for B2B/B2G) or reported within 24 hours (for B2C).

Regulatory Framework

Implementation Timeline

Who Must Comply?

Transaction Coverage

How the System Works

Clearance Process Flow

B2B/B2G Transactions (Pre-Clearance Model)

B2C Transactions (Post-Reporting Model)

Invoice Components

Every FIRS-approved invoice contains:

Document Types

Key Technical Requirements

To comply with the FIRS e-invoicing mandate, businesses must:

Non-Compliance Penalties

The FIRS has established significant penalties for non-compliance:

Example Penalty Calculation

For a business that fails to comply for 30 days:

• First day: ₦1,000,000
• Remaining 29 days: ₦10,000 × 29 = ₦290,000
• Administrative penalty: ₦200,000
• Total: ₦1,490,000 (excluding tax penalties and interest)

Benefits of Compliance

Complying with the e-invoicing mandate provides several advantages:

Implementation Steps

Businesses should follow these steps to achieve compliance:

Support Resources

For the latest mandate updates and official guidance, please refer to FIRS circulars and announcements.

Nigeria Invoice Datapoints

These are the datapoints included in Nigeria's e-invoicing system following the Peppol BIS Billing 3.0 UBL standard.

Base-Level Invoice Datapoints

document_identifier

UBL Tag: cbc:ID
Requirement: Mandatory
Type: String

Unique identifier for the invoice assigned by the supplier.

{
  "document_identifier": "CNINV-1126519001"
}

Rules:

• Must be unique within the supplier's system
• Used for tracking and reference
• Will be used to generate the IRN (Invoice Reference Number) by FIRS

issue_date

UBL Tag: cbc:IssueDate
Requirement: Mandatory
Type: Date (YYYY-MM-DD)

The date when the invoice was issued.

{
  "issue_date": "2025-05-14"
}

Rules:

• Must be in ISO 8601 format: YYYY-MM-DD
• Cannot be a future date
• Must be within the current tax period

due_date

UBL Tag: cbc:DueDate
Requirement: Optional
Type: Date (YYYY-MM-DD)

The date by which payment is due.

{
  "due_date": "2025-03-29"
}

Rules:

• Must be in ISO 8601 format: YYYY-MM-DD
• Should be equal to or after issue_date
• Recommended for B2B transactions

invoice_type_code

UBL Tag: cbc:InvoiceTypeCode
Requirement: Mandatory
Type: Code

Specifies the type of invoice document.

{
  "invoice_type_code": "380"
}

Allowed Values:

Rules:

• Must be one of the approved codes for Nigeria
• Credit notes (381) require reference to original invoice

payment_status

UBL Tag: Custom field
Requirement: Optional
Type: String

Current payment status of the invoice.

{
  "payment_status": "PENDING"
}

Allowed Values:

• PENDING - Payment not yet received
• PAID - Payment received and confirmed
• REJECTED - Invoice rejected by buyer

document_currency_code

UBL Tag: cbc:DocumentCurrencyCode
Requirement: Mandatory
Type: Code (ISO 4217)

The currency in which all invoice amounts are expressed.

{
  "document_currency_code": "NGN"
}

Rules:

• Must be coded using ISO 4217 alpha-3 code
• For Nigerian transactions, typically "NGN" (Nigerian Naira)
• All amounts in the invoice must use this currency

tax_currency_code

UBL Tag: cbc:TaxCurrencyCode
Requirement: Mandatory
Type: Code (ISO 4217)

The currency used for tax calculations and reporting.

{
  "tax_currency_code": "NGN"
}

Rules:

• Must be "NGN" for FIRS tax reporting
• Required even if document_currency_code is also NGN

accounting_customer_party

UBL Tag: cac:AccountingCustomerParty
Requirement: Mandatory
Type: Object

Information about the buyer/customer receiving the invoice.

{
  "accounting_customer_party": {
    "party_name": "ABC Company Limited",
    "tin": "31976634-0001",
    "email": "customer@example.com",
    "telephone": "+234802540990",
    "business_description": "Sales of Cement and building materials",
    "postal_address": {
      "street_name": "32, Owonikoko Street",
      "city_name": "Gwarinpa",
      "postal_zone": "023401",
      "country": "NG"
    }
  }
}

Key Fields:

Address Fields:

Rules:

• TIN format must follow FIRS standards (e.g., "31976634-0001")
• All mandatory fields must be present for invoice validation
• Country code must be "NG" for Nigerian customers

invoice_line

UBL Tag: cac:InvoiceLine
Requirement: Mandatory (at least one)
Type: Array of Objects

Individual line items in the invoice representing products or services.

{
  "invoice_line": [
    {
      "hsn_code": "2710.19",
      "invoiced_quantity": 100,
      "price_amount": 1000,
      "discount_amount": 50,
      "discount_rate": 5,
      "fee_amount": 20,
      "fee_rate": 2,
      "uom": "ST",
      "product_category": "Food and Beverages",
      "tax_rate": 7.5,
      "tax_category_id": "LOCAL_SALES_TAX",
      "item_name": "Organic Tea Leaves",
      "sellers_item_identification": "209897"
    }
  ]
}

Key Fields:

UOM (Unit of Measurement) Common Codes:

Product Categories:

Common categories include (but not limited to):

• Food and Beverages
• Electronics
• Clothing and Textiles
• Building Materials
• Pharmaceuticals
• Agricultural Products
• Services

Tax Categories:

Rules:

• At least one invoice line must be present
• hsn_code is mandatory for goods classification
• tax_rate for VAT in Nigeria is typically 7.5%
• Line extension amount = (invoiced_quantity × price_amount) - discount_amount + fee_amount
• All amounts must be in the invoice currency

IRN and Validation Fields

These fields are generated by Flick before invoice submission and validation:

irn (Invoice Reference Number)

Generated By: FIRS
Type: String

Unique reference number issued by Flick.

Example: "CNINV-C1B44E6C-20250814"

Format: CNINV-{sequence}-{date}

qr_code

Generated By: FIRS
Type: Base64 String or Image

QR code containing invoice verification data for quick scanning and validation.

Contents: IRN, CSID, invoice date, amount, and other verification data

Complete Invoice Example

{
  "document_identifier": "CNINV-1126519001",
  "issue_date": "2025-05-14",
  "due_date": "2025-06-14",
  "invoice_type_code": "380",
  "payment_status": "PENDING",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "accounting_customer_party": {
    "party_name": "ABC Company Limited",
    "tin": "31976634-0001",
    "email": "customer@example.com",
    "telephone": "+234802540990",
    "business_description": "Sales of Cement and building materials",
    "postal_address": {
      "street_name": "32, Owonikoko Street",
      "city_name": "Gwarinpa",
      "postal_zone": "023401",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "2710.19",
      "invoiced_quantity": 100,
      "price_amount": 1000,
      "discount_amount": 50,
      "discount_rate": 5,
      "fee_amount": 20,
      "fee_rate": 2,
      "uom": "ST",
      "product_category": "Food and Beverages",
      "tax_rate": 7.5,
      "tax_category_id": "LOCAL_SALES_TAX",
      "item_name": "Organic Tea Leaves",
      "sellers_item_identification": "209897"
    }
  ]
}

Additional Resources

For detailed information on:

• Invoice submission: See eInvoicing Lifecycle
• API Examples: See Examples
• FIRS requirements: See Mandates

Nigeria eInvoicing Lifecycle

This guide covers the complete lifecycle of e-invoicing in Nigeria, from onboarding to FIRSMBS through sending and receiving invoices.

Onboarding to FIRSMBS

Before you can send or receive e-invoices through the FIRS platform, you must complete the onboarding process:

1. Obtain FIRS Credentials

You must obtain the following credentials from FIRS:

2. Select Access Point Provider (APP)

Choose a NITDA-accredited Access Point Provider to facilitate your connection to FIRSMBS:

• Verify APP is on the official NITDA accredited list
• Review APP's features and pricing
• Confirm APP supports your ERP/accounting system
• Establish service agreement

3. Complete Participant Onboarding

Register your business with FIRSMBS using the onboarding API:

Onboarding Endpoint

POST /onboard/participant

Required Information

{
  "business_id": "7af401ac-4e6c-480c-92b1-9b1c42bf6089",
  "party_name": "ABC Company Limited",
  "tin": "12345888-5789",
  "email": "contact@example.com",
  "telephone": "+234802540990",
  "business_description": "Sales of building materials and cement",
  "postal_address": {
    "street_name": "32, Owonikoko Street",
    "city_name": "Gwarinpa",
    "postal_zone": "023401",
    "country": "NG"
  },
  "certificate": "<base64-certificate>",
  "public_key": "<rsa-key>"
}

Request Headers:

Content-Type: application/json
x-flick-auth-key: {{x-flick-auth-key}}

4. Configure Your System

Set up your integration:

• Configure API authentication with client credentials
• Map your internal data models to UBL format
• Integrate with APP's APIs
• Test invoice submission in sandbox environment

5. Go Live

Once testing is complete:

• Activate your production account
• Begin submitting invoices to FIRSMBS
• Monitor compliance through your APP dashboard

Sending an Invoice

Sending an invoice in Nigeria involves creating the invoice, validating it with FIRSMBS, and delivering it to the buyer.

Invoice Submission Flow

B2B/B2G Transactions (Pre-Clearance)

1. Create invoice with all mandatory fields
   ↓
2. Submit to FIRSMBS via POST /invoice/generate
   ↓
3. FIRSMBS validates invoice
   ↓
4. Receive IRN and QR code
   ↓
5. Deliver invoice to buyer

B2C Transactions (Post-Reporting)

1. Issue invoice to customer at point of sale
   ↓
2. Report to FIRSMBS within 24 hours via POST /invoice/generate
   ↓
3. FIRSMBS validates and records
   ↓
4. Customer can verify using QR code

Generating an Invoice

Endpoint

POST /invoice/generate

Preparing the Invoice Data

Create your invoice following the FIRS specification. The /invoice/generate endpoint handles signing, validation, and exchange in a single API call — reducing the number of requests needed.

{
  "document_identifier": "CNINV-1126519001",
  "issue_date": "2025-05-14",
  "invoice_type_code": "380",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "accounting_customer_party": {
    "party_name": "Customer Company Ltd",
    "tin": "31976634-0001",
    "email": "customer@example.com",
    "telephone": "+234802540990",
    "business_description": "Retail of consumer goods",
    "postal_address": {
      "street_name": "15 Marina Road",
      "city_name": "Lagos",
      "postal_zone": "100001",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "2710.19",
      "price_amount": 1000,
      "uom": "ST",
      "invoiced_quantity": 100,
      "product_category": "Food and Beverages",
      "tax_rate": 7.5,
      "tax_category_id": "LOCAL_SALES_TAX",
      "item_name": "Organic Tea Leaves",
      "sellers_item_identification": "209897"
    }
  ]
}

Request Headers:

Content-Type: application/json
participant-id: {{participant-id}}
x-flick-auth-key: {{x-flick-auth-key}}

Key Points:

• The invoice_type_code "380" represents a standard commercial invoice
• Signing, validation, and exchange are all handled in this single API call
• Customer must have valid TIN
• At least one invoice line is mandatory
• For B2B/B2G, submission must occur before invoice delivery to buyer

Handling Responses

Success Response

Upon successful validation, FIRSMBS returns the approved invoice with IRN:

{
  "status": "approved",
  "irn": "CNINV-112275021707261522-C1B44E6C-20250814",
  "csid": "abc123def456...",
  "qr_code": "data:image/png;base64,iVBORw0KG...",
  "document_identifier": "CNINV-1126519001",
  "validated_at": "2025-05-14T10:30:00Z"
}

Response Fields:

Error Response

If validation fails, FIRSMBS returns error details:

{
  "error": true,
  "error_code": "VALIDATION_FAILED",
  "message": "Missing required field: tin",
  "document_identifier": "CNINV-1126519001",
  "details": {
    "field": "accounting_customer_party.tin",
    "reason": "TIN is mandatory for all customers"
  }
}

Common Error Codes:

Retrieving Invoices

Search Invoices

Retrieve all invoices associated with your business:

GET /invoice/search

Request Headers:

participant-id: {{participant-id}}
x-flick-auth-key: {{x-flick-auth-key}}

Response:

{
  "invoices": [
    {
      "irn": "CNINV-112275021707261522-C1B44E6C-20250814",
      "document_identifier": "CNINV-1126519001",
      "issue_date": "2025-05-14",
      "customer_name": "Customer Company Ltd",
      "total_amount": 107500,
      "payment_status": "PENDING",
      "validated_at": "2025-05-14T10:30:00Z"
    }
  ],
  "total_count": 1
}

Get Invoice Details

Retrieve detailed information for a specific invoice:

GET /invoice/details/:irn

Example: /invoice/details/CNINV-117589493872308491-C1B44E6C-20250814

Response:

{
  "irn": "CNINV-117589493872308491-C1B44E6C-20250814",
  "document_identifier": "CNINV-1126519001",
  "issue_date": "2025-05-14",
  "invoice_type_code": "380",
  "payment_status": "PENDING",
  "qr_code": "data:image/png;base64,iVBORw0KG...",
  "accounting_customer_party": {
    "party_name": "Customer Company Ltd",
    "tin": "31976634-0001"
  },
  "invoice_line": [
    {
      "item_name": "Organic Tea Leaves",
      "invoiced_quantity": 100,
      "price_amount": 1000,
      "tax_rate": 7.5
    }
  ],
  "validated_at": "2025-05-14T10:30:00Z"
}

Download Invoice

Download the complete invoice document (XML/JSON/PDF):

GET /invoice/download/:irn

Example: /invoice/download/CNINV-112275021707261522-C1B44E6C-20250814

Request Headers:

participant-id: {{participant-id}}
x-flick-auth-key: {{x-flick-auth-key}}
Accept: application/xml  # or application/json or application/pdf

Response: Invoice document in requested format

Updating Invoice Status

After payment is received or if an invoice is rejected, update the payment status:

Update Payment Status

PATCH /invoice/:irn

{
  "payment_status": "PAID",
  "reference": "PAYMENT-REF-12345"
}

Available Status Values:

• PENDING - Payment not yet received
• PAID - Payment received and confirmed
• REJECTED - Invoice rejected by buyer

Request Headers:

Content-Type: application/json
participant-id: {{participant-id}}
x-flick-auth-key: {{x-flick-auth-key}}

Reporting Invoices

For audit and compliance purposes, generate reports on your invoices:

POST /invoice/report/:irn

Example: /invoice/report/CNINV-117589493872308491-C1B44E6C-20250814

Generates a compliance report for the specified invoice including:

• Invoice validation details
• Tax calculation breakdown
• Submission timestamps
• Current payment status

Resource APIs

FIRSMBS provides resource APIs to help with invoice creation:

Get All Resources

Retrieve master data for invoice categorization:

GET /resources/all

Returns all available resource codes including:

• Countries
• Currencies
• Tax categories
• Payment means
• Invoice types
• Service codes
• VAT exemptions
• HS codes

Specific Resource Endpoints

Request Headers:

Content-Type: application/json
participant-id: {{participant-id}}
x-flick-auth-key: {{x-flick-auth-key}}

Complete Lifecycle Example

Sending Flow

1. Onboard to FIRSMBS
   POST /onboard/participant
   ↓
2. Retrieve resource codes (optional)
   GET /resources/all
   ↓
3. Create invoice with all mandatory fields
   ↓
4. Submit invoice for validation
   POST /invoice/generate
   ↓
5. Receive IRN, CSID, and QR code
   ↓
6. Deliver invoice to buyer (B2B/B2G)
   or Display to customer (B2C)
   ↓
7. Monitor payment status
   GET /invoice/details/:irn
   ↓
8. Update payment status when paid
   PATCH /invoice/:irn

Receiving Flow

1. Buyer receives invoice with IRN
   ↓
2. Verify invoice authenticity
   - Scan QR code, or
   - Check IRN via GET /invoice/details/:irn
   ↓
3. Process invoice in accounting system
   ↓
4. Make payment to supplier
   ↓
5. Supplier updates payment status
   PATCH /invoice/:irn

Integration Checklist

Before Going Live

• Complete FIRSMBS participant onboarding
• Obtain and secure certificate and public key from FIRS
• Establish connection with NITDA-accredited APP
• Implement invoice data preparation following UBL format
• Set up error handling for all API responses
• Test invoice generation in sandbox environment
• Verify IRN, CSID, and QR code generation
• Test invoice retrieval and download functions
• Implement payment status update mechanism
• Train users on the new system
• Have rollback plan ready

Compliance Requirements

• All invoices must follow Peppol BIS Billing 3.0 UBL format
• Supplier and customer must have valid FIRS TIN
• B2B/B2G invoices must be pre-cleared before delivery
• B2C invoices (>₦50,000) must be reported within 24 hours
• Display IRN, CSID, and QR code on all invoices
• Tax calculations must be accurate (7.5% standard VAT rate)
• Retain all invoices and validation records for audit
• Implement proper data security measures
• Use secure API authentication
• Monitor for FIRSMBS system updates

Additional Resources

For detailed information on:

• Invoice structure: See Invoice Datapoints
• FIRS requirements: See Mandates
• API Examples: See Examples
• Technical specifications: Refer to FIRS official documentation at www.firs.gov.ng

Nigeria E-Invoicing Examples

Complete collection of FIRS-compliant invoice examples covering standard invoices, credit notes, and various transaction scenarios.

Standard Invoices

Standard Commercial Invoice

A typical B2B commercial invoice with standard 7.5% VAT rate.

Key Features:

• Invoice Type Code: 380 (Commercial invoice)
• Standard VAT rate: 7.5%
• Full customer information with TIN
• Mandatory fields only

{
  "document_identifier": "CNINV-1126519001",
  "issue_date": "2025-05-14",
  "due_date": "2025-06-14",
  "invoice_type_code": "380",
  "payment_status": "PENDING",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "accounting_customer_party": {
    "party_name": "ABC Company Limited",
    "tin": "31976634-0001",
    "email": "customer@example.com",
    "telephone": "+234802540990",
    "business_description": "Sales of Cement and building materials",
    "postal_address": {
      "street_name": "32, Owonikoko Street",
      "city_name": "Gwarinpa",
      "postal_zone": "023401",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "CC-00001",
      "invoiced_quantity": 100,
      "price_amount": 1000,
      "uom": "1",
      "product_category": "Food and Beverages",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Organic Tea Leaves",
      "sellers_item_identification": "TEA-ORG-001"
    }
  ]
}

Invoice with Discounts and Fees

Standard invoice including line-level discounts and additional fees.

Key Features:

• Discount amount and rate applied
• Additional fees included
• Net amount calculation

{
  "document_identifier": "CNINV-2025-00542",
  "issue_date": "2025-06-20",
  "due_date": "2025-07-20",
  "invoice_type_code": "380",
  "payment_status": "PENDING",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "accounting_customer_party": {
    "party_name": "XYZ Retailers Limited",
    "tin": "45678901-0001",
    "email": "accounts@xyzretailers.ng",
    "telephone": "+234803456789",
    "business_description": "Retail and distribution",
    "postal_address": {
      "street_name": "Plot 45, Adeola Odeku Street",
      "city_name": "Lagos",
      "postal_zone": "100001",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "HS-84716020",
      "invoiced_quantity": 50,
      "price_amount": 25000,
      "discount_amount": 125000,
      "discount_rate": 10,
      "fee_amount": 50000,
      "fee_rate": 4,
      "uom": "1",
      "product_category": "Electronics",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Laptop Computer - Model X500",
      "sellers_item_identification": "LAP-X500-BLK"
    },
    {
      "hsn_code": "HS-85176200",
      "invoiced_quantity": 100,
      "price_amount": 5000,
      "discount_amount": 25000,
      "discount_rate": 5,
      "uom": "1",
      "product_category": "Electronics",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Wireless Mouse",
      "sellers_item_identification": "MSE-WL-002"
    }
  ]
}

Calculation Breakdown:

Line 1 (Laptops):

• Gross Amount: 50 × ₦25,000 = ₦1,250,000
• Discount (10%): -₦125,000
• Fee (4%): +₦50,000
• Net Amount: ₦1,175,000
• VAT (7.5%): ₦88,125
• Total: ₦1,263,125

Line 2 (Mice):

• Gross Amount: 100 × ₦5,000 = ₦500,000
• Discount (5%): -₦25,000
• Net Amount: ₦475,000
• VAT (7.5%): ₦35,625
• Total: ₦510,625

Invoice Total: ₦1,773,750

Credit Notes

Standard Credit Note

Credit note for returns or adjustments.

Key Features:

• Invoice Type Code: 381 (Credit note)
• References original invoice
• Negative or reduced amounts

{
  "document_identifier": "CN-2025-00123",
  "issue_date": "2025-06-25",
  "invoice_type_code": "381",
  "payment_status": "PENDING",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "original_invoice_reference": "CNINV-1126519001",
  "accounting_customer_party": {
    "party_name": "ABC Company Limited",
    "tin": "31976634-0001",
    "email": "customer@example.com",
    "telephone": "+234802540990",
    "business_description": "Sales of Cement and building materials",
    "postal_address": {
      "street_name": "32, Owonikoko Street",
      "city_name": "Gwarinpa",
      "postal_zone": "023401",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "CC-00001",
      "invoiced_quantity": 10,
      "price_amount": 1000,
      "uom": "1",
      "product_category": "Food and Beverages",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Organic Tea Leaves - Returned",
      "sellers_item_identification": "TEA-ORG-001"
    }
  ]
}

Simplified Invoices (B2C)

Simplified B2C Invoice

Invoice for high-value consumer transactions (above ₦50,000).

Key Features:

• Invoice Type Code: 394 (Simplified invoice)
• For B2C transactions
• Reported within 24 hours
• Simplified customer details

{
  "document_identifier": "B2C-2025-089456",
  "issue_date": "2025-07-15",
  "invoice_type_code": "394",
  "payment_status": "PAID",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "accounting_customer_party": {
    "party_name": "Walk-in Customer",
    "tin": "00000000-0000",
    "email": "customer@retail.ng",
    "telephone": "+234803123456",
    "business_description": "Consumer",
    "postal_address": {
      "street_name": "N/A",
      "city_name": "Abuja",
      "postal_zone": "900001",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "HS-61091000",
      "invoiced_quantity": 2,
      "price_amount": 35000,
      "uom": "1",
      "product_category": "Clothing and Textiles",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Designer T-Shirt",
      "sellers_item_identification": "TSH-DSN-BLU"
    }
  ]
}

Total Calculation:

• Subtotal: 2 × ₦35,000 = ₦70,000
• VAT (7.5%): ₦5,250
• Total: ₦75,250

Multi-Line Invoice

Invoice with Multiple Products

Complex invoice with various products, different tax rates, and categories.

{
  "document_identifier": "CNINV-2025-01234",
  "issue_date": "2025-08-01",
  "due_date": "2025-08-31",
  "invoice_type_code": "380",
  "payment_status": "PENDING",
  "document_currency_code": "NGN",
  "tax_currency_code": "NGN",
  "accounting_customer_party": {
    "party_name": "General Hospital Abuja",
    "tin": "78901234-0001",
    "email": "procurement@ghospital.ng",
    "telephone": "+234809876543",
    "business_description": "Healthcare services",
    "postal_address": {
      "street_name": "Maitama District",
      "city_name": "Abuja",
      "postal_zone": "900001",
      "country": "NG"
    }
  },
  "invoice_line": [
    {
      "hsn_code": "HS-30049099",
      "invoiced_quantity": 500,
      "price_amount": 1200,
      "uom": "1",
      "product_category": "Pharmaceuticals",
      "tax_rate": 0,
      "tax_category_id": "EXEMPT",
      "item_name": "Antibiotic Tablets - Pack of 10",
      "sellers_item_identification": "MED-ANT-010"
    },
    {
      "hsn_code": "HS-90181990",
      "invoiced_quantity": 20,
      "price_amount": 85000,
      "uom": "1",
      "product_category": "Medical Equipment",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Blood Pressure Monitor",
      "sellers_item_identification": "MED-BPM-200"
    },
    {
      "hsn_code": "HS-30051010",
      "invoiced_quantity": 1000,
      "price_amount": 150,
      "uom": "1",
      "product_category": "Pharmaceuticals",
      "tax_rate": 0,
      "tax_category_id": "EXEMPT",
      "item_name": "Surgical Bandages",
      "sellers_item_identification": "MED-BND-050"
    },
    {
      "hsn_code": "HS-94029000",
      "invoiced_quantity": 10,
      "price_amount": 125000,
      "uom": "1",
      "product_category": "Furniture",
      "tax_rate": 7.5,
      "tax_category_id": "STANDARD_VAT",
      "item_name": "Hospital Bed",
      "sellers_item_identification": "FRN-BED-HOS"
    }
  ]
}

Invoice Breakdown:

API Response Examples

Successful Invoice Generation

After submitting an invoice to FIRSMBS:

{
  "status": "approved",
  "irn": "CNINV-112275021707261522-C1B44E6C-20250814",
  "csid": "7f8d9e1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s",
  "qr_code": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...",
  "document_identifier": "CNINV-1126519001",
  "validated_at": "2025-05-14T10:30:00Z",
  "message": "Invoice successfully validated and approved"
}

Error Response Example

Validation failure due to missing required field:

{
  "error": true,
  "error_code": "VALIDATION_FAILED",
  "message": "Missing required field: tin",
  "document_identifier": "CNINV-1126519001",
  "details": {
    "field": "accounting_customer_party.tin",
    "reason": "TIN is mandatory for all customers",
    "expected_format": "########-####"
  },
  "timestamp": "2025-05-14T10:30:00Z"
}

Invoice Search Response

Result from GET /invoice/search:

{
  "invoices": [
    {
      "irn": "CNINV-112275021707261522-C1B44E6C-20250814",
      "document_identifier": "CNINV-1126519001",
      "issue_date": "2025-05-14",
      "invoice_type_code": "380",
      "customer_name": "ABC Company Limited",
      "customer_tin": "31976634-0001",
      "total_amount": 107500,
      "tax_amount": 7500,
      "payment_status": "PENDING",
      "validated_at": "2025-05-14T10:30:00Z"
    },
    {
      "irn": "CNINV-117589493872308491-C1B44E6C-20250814",
      "document_identifier": "CNINV-2025-00542",
      "issue_date": "2025-06-20",
      "invoice_type_code": "380",
      "customer_name": "XYZ Retailers Limited",
      "customer_tin": "45678901-0001",
      "total_amount": 1773750,
      "tax_amount": 123750,
      "payment_status": "PAID",
      "validated_at": "2025-06-20T14:15:30Z"
    }
  ],
  "total_count": 2,
  "page": 1,
  "per_page": 20
}

Invoice Type Codes Reference

Tax Category Codes Reference

Common Product Categories

Best Practices for Examples

Using Examples Effectively

1. Start Simple: Begin with standard invoice template and add complexity as needed
2. Verify TIN Format: Ensure customer TIN follows FIRS format (########-####)
3. Validate Tax Calculations: Standard VAT rate is 7.5%
4. Test in Sandbox: Always test with example data before production
5. Save Successful Examples: Keep records for reference and troubleshooting

Common Patterns

Simple B2B Sale (Standard VAT):

Type Code: 380
Tax Category: STANDARD_VAT (7.5%)
Required: Customer TIN, line items, amounts

B2C Retail Transaction:

Type Code: 394
Threshold: > ₦50,000
Reporting: Within 24 hours
Simplified customer details allowed

Credit Adjustment:

Type Code: 381
Must Reference: Original invoice identifier
Reduced or negative quantities

Exempt Supplies:

Type Code: 380
Tax Category: EXEMPT (0%)
Examples: Pharmaceuticals, educational materials

Additional Resources

• Invoice Datapoints: Full field specifications at Invoice Datapoints
• Lifecycle Guide: Integration steps at eInvoicing Lifecycle
• Official Specification: Refer to FIRS documentation at www.firs.gov.ng