Fetch Received Invoices

Retrieve a paginated list of invoices for a specified business with flexible filtering and sorting options.

Quick Reference

Method	Endpoint	Content-Type
`POST`	`{{baseUrl}}/{{stage}}/external/businesses/{{businessId}}/fetchInvoices`	`application/json`

Request Structure

Path Parameters

Parameter	Type	Required	Description	Example
`businessId`	string	✅	Unique identifier of the business	`26ede24b-ac50-475f-aacc-5ea6339f0863`

Headers

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

Query Parameters

Parameter	Type	Required	Description	Example
`invoicePaymentStatus`	string	optional	this filters the invoices using the payment status	`PENDING`,`PAID`,`REJECTED`

Request Body

The request body must be a JSON object containing pagination parameters:

Field	Type	Required	Description	Default	Validation
`page`	number	✅	Page number for pagination		Must be ≥ 1
`size`	number	✅	Number of results per page		Must be between 1-100
`invoicePaymentStatus`	string	optional	this filters the invoices using the payment status	`PENDING`,`PAID`,`REJECTED`
`dateTo`	string	optional	this filters the invoices within a specific date range	`PENDING`,`PAID`,`REJECTED`
`dateFrom`	string	optional	this filters the invoices within a specific date range	`PENDING`,`PAID`,`REJECTED`

📤 Response Format

Success Response (200)

{
  "data": {
    "invoices": [
      {
        "irn": "INV237-1070ECE8-20250826",
        "invoiceNumber": "INV237",
        "issueDate": "2025-08-26",
        "dueDate": "2025-08-26",
        "paymentStatus": "PAID",
        "documentCurrencyCode": "NGN",
        "payableAmount": 30255.22,
        "taxInclusiveAmount": 30255.22,
        "customerPartyName": "Dangote Group",
        "supplierPartyName": "AEDC Electricity Supply",
        "note": "August Electricity Bill - Mr Ridwan"
      },
      {
        "irn": "INV238-1070ECE8-20250826",
        "invoiceNumber": "INV238",
        "issueDate": "2025-08-26",
        "dueDate": "2025-09-25",
        "paymentStatus": "PENDING",
        "documentCurrencyCode": "NGN",
        "payableAmount": 161250.0,
        "taxInclusiveAmount": 161250.0,
        "customerPartyName": "Tech Solutions Ltd",
        "supplierPartyName": "Office Supplies Co",
        "note": "IT Equipment Purchase"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "pageSize": 2,
      "totalPages": 15,
      "totalElements": 29,
      "hasNext": true,
      "hasPrevious": false
    },
    "summary": {
      "totalInvoices": 29,
      "totalAmount": 875432.50,
      "paidInvoices": 18,
      "pendingInvoices": 8,
      "rejectedInvoices": 3
    }
  },
  "responseCode": "200",
  "responseMessage": "Invoices fetched successfully"
}

📋 Response Data Structure

Invoice Object

Field	Type	Description
`irn`	string	Invoice Reference Number
`invoiceNumber`	string	User-defined invoice number
`issueDate`	string	Date invoice was issued (YYYY-MM-DD)
`dueDate`	string	Payment due date (YYYY-MM-DD)
`paymentStatus`	string	Payment status: PENDING, PAID, REJECTED
`documentCurrencyCode`	string	Currency code (e.g., NGN, USD)
`payableAmount`	number	Total amount payable
`taxInclusiveAmount`	number	Amount including tax
`customerPartyName`	string	Customer name
`supplierPartyName`	string	Supplier name
`note`	string	Additional notes about the invoice

Pagination Object

Field	Type	Description
`currentPage`	number	Current page number
`pageSize`	number	Number of items per page
`totalPages`	number	Total number of pages
`totalElements`	number	Total number of invoices
`hasNext`	boolean	Whether there are more pages
`hasPrevious`	boolean	Whether there are previous pages

Summary Object

Field	Type	Description
`totalInvoices`	number	Total number of invoices
`totalAmount`	number	Sum of all invoice amounts
`paidInvoices`	number	Count of paid invoices
`pendingInvoices`	number	Count of pending invoices
`rejectedInvoices`	number	Count of rejected invoices

✅ Validation Rules

Request Body Validation

page must be a positive integer (≥ 1)

size must be between 1 and 100

Both fields are required

Path Parameter Validation

businessId must be a valid UUID format

Business must exist and be accessible to the user

Business Logic Validation

User must have permission to access the business's invoices

Only finalized/sent invoices are included in results

Deleted invoices are excluded from results

⚠️ Error Responses

Common Error Scenarios

Error Code	Message	Description	Solution
`400`	Invalid page parameter	Page number is less than 1	Use page ≥ 1
`400`	Invalid size parameter	Page size is outside allowed range	Use size between 1-100
`404`	Business not found	Business ID doesn't exist	Verify business ID
`403`	Access denied	User doesn't have permission	Check user permissions
`422`	Missing required fields	Page or size not provided	Include both page and size

Example Error Response

{
  "data": null,
  "responseCode": "400",
  "responseMessage": "Invalid page parameter: must be greater than 0"
}

💡 Pagination Best Practices

Efficient Data Loading

Start small: Use page size 10-25 for initial loads

Progressive loading: Increase page size for subsequent requests

Maximum limit: Don't exceed 100 items per page

Use pagination object: Leverage hasNext and hasPrevious for navigation

Total pages: Display total pages using totalPages

Current position: Show current page context

Performance Optimization

Cache results: Store frequently accessed pages client-side

Debounce requests: Avoid rapid-fire pagination requests

Loading states: Show loading indicators during fetch operations

📊 Use Cases

Common Implementation Scenarios

Invoice Dashboard

Fetch invoices → Display in table → Show pagination controls

Financial Reports

Iterate through pages → Aggregate data → Generate reports

Customer Portal

Filter by customer → Paginate results → Display relevant invoices

Bulk Operations

Fetch all pages → Select invoices → Perform bulk actions

🔍 Filtering & Sorting Considerations

While this endpoint provides basic pagination, consider these future enhancements:

Potential Filter Parameters

Payment status filtering

Date range filtering

Customer/supplier filtering

Amount range filtering

Potential Sort Options

Sort by issue date

Sort by due date

Sort by amount

Sort by payment status

Note: Current endpoint provides basic pagination. Contact API team for advanced filtering requirements.

Invoice Operations

GET /invoices/{invoiceIrn} - Get specific invoice details

POST /invoices - Create new invoice

POST /invoices/bulk - Bulk invoice creation

POST /invoices/update-payment/{invoiceIrn} - Update payment status

Business Management

GET /businesses/{businessId} - Get business details

GET /businesses/{businessId}/statistics - Get business statistics

GET /businesses/{businessId}/reports - Generate business reports

📈 Response Time & Performance

Expected Performance

Typical response time: 200-800ms depending on page size

Large datasets: May take longer for businesses with many invoices

Concurrent requests: Multiple pagination requests are supported

Optimization Tips

Use appropriate page sizes for your use case

Implement client-side caching for frequently accessed pages

Consider using the summary data to avoid unnecessary full-page loads

This endpoint provides efficient access to invoice data with comprehensive pagination support, enabling businesses to manage large volumes of invoices effectively while maintaining optimal performance.

Fetch Received Invoices

Quick Reference#

Request Structure#

Path Parameters#

Headers#

Query Parameters#

Request Body#

📤 Response Format#

Success Response (200)#

📋 Response Data Structure#

Invoice Object#

Pagination Object#

Summary Object#

✅ Validation Rules#

Request Body Validation#

Path Parameter Validation#

Business Logic Validation#

⚠️ Error Responses#

Common Error Scenarios#

Example Error Response#

💡 Pagination Best Practices#

Efficient Data Loading#

Navigation Implementation#

Performance Optimization#

📊 Use Cases#

Common Implementation Scenarios#

🔍 Filtering & Sorting Considerations#

Potential Filter Parameters#

Potential Sort Options#

🔗 Related Endpoints#

Invoice Operations#

Business Management#

📈 Response Time & Performance#

Expected Performance#

Optimization Tips#

Request

Responses