Invoices API

Base path: https://gateway.useyona.com/i/v1/invoices

Create invoice

POST /i/v1/invoices

Create a draft invoice.

Request body

Field	Type	Required	Description
`sellerId`	string (UUID)	Yes	Registered seller ID
`buyerId`	string (UUID)	Yes	Registered buyer ID
`invoiceNumber`	string	Yes	Unique per organization, max 100 chars
`invoiceType`	string	No	`standard` \| `credit_note` \| `debit_note` \| `prepayment`. Default: `standard`
`invoiceDate`	string	Yes	ISO date, e.g. `2026-04-30`
`dueDate`	string	No	ISO date
`currency`	string	No	`NGN` \| `USD` \| `EUR` \| `GBP`. Default: `NGN`
`lineItems`	array	Yes	At least one line item required
`allowanceAmount`	number	No	Document-level discount, min 0
`chargeAmount`	number	No	Document-level surcharge, min 0
`paymentStatus`	string	No	`unpaid` \| `partially_paid` \| `paid` \| `overdue`. Default: `unpaid`
`paymentTerms`	string	No	Max 500 chars
`notes`	string	No	Free text
`originalInvoiceNumber`	string	No	For credit/debit notes, max 100 chars

Line item fields

Field	Type	Required	Description
`description`	string	Yes	Max 500 chars
`hsnCode`	string	Conditional	HS code for goods (dotted format, e.g. `1006.30`). Required unless `isicCode` is provided.
`productCategory`	string	No	Full HS code description (e.g. `"Cereals; rice, semi-milled or wholly milled..."`). Resolved automatically from `hsnCode` if omitted.
`isicCode`	string	Conditional	ISIC code for services (e.g. `0112`). Alternative to `hsnCode`.
`serviceCategory`	string	No	Full ISIC code description (e.g. `"Growing of rice"`). Used with `isicCode`.
`quantity`	number	Yes	Min 0.001
`unitCode`	string	Yes	Unit of measure: `EA`, `KGM`, `HUR`, `LTR`, `XBG`, etc. Max 10 chars
`unitPrice`	number	Yes	Price per unit, min 0
`discountAmount`	number	No	Line-level discount, min 0
`taxPercent`	number	Yes	Tax rate 0-100 (e.g. 7.5 for 7.5%)

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e",
    "buyerId": "d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f",
    "invoiceNumber": "INV-2026-001",
    "invoiceDate": "2026-04-30",
    "dueDate": "2026-05-30",
    "currency": "NGN",
    "lineItems": [
      {
        "description": "Software development services - April 2026",
        "hsnCode": "9983",
        "quantity": 80,
        "unitCode": "HUR",
        "unitPrice": 15000,
        "taxPercent": 7.5
      },
      {
        "description": "Cloud infrastructure hosting",
        "hsnCode": "9984",
        "quantity": 1,
        "unitCode": "EA",
        "unitPrice": 450000,
        "taxPercent": 7.5
      }
    ],
    "paymentTerms": "Net 30"
  }'

Status	Code	Trigger
400	VAL001	Missing or invalid fields
400	INV001	Invalid invoice format
400	BIZ001	Insufficient credits
404	RES001	Seller or buyer not found
409	RES002	Invoice number already exists for this organization

List invoices

GET /i/v1/invoices

List invoices with filters and pagination.

Query parameters

Parameter	Type	Required	Default	Description
`status`	string	No	—	Filter: `draft`, `queued`, `pending`, `accepted`, `rejected`, `failed`, `cancelled`
`invoiceType`	string	No	—	Filter: `standard`, `credit_note`, `debit_note`, `prepayment`
`paymentStatus`	string	No	—	Filter: `unpaid`, `partially_paid`, `paid`, `overdue`
`currency`	string	No	—	Filter: `NGN`, `USD`, `EUR`, `GBP`
`sellerId`	string	No	—	Filter by seller UUID
`buyerId`	string	No	—	Filter by buyer UUID
`invoiceDateFrom`	string	No	—	ISO date, inclusive
`invoiceDateTo`	string	No	—	ISO date, inclusive
`search`	string	No	—	Search invoice number and notes
`page`	number	No	1	Page number
`limit`	number	No	20	Items per page
`sortBy`	string	No	`createdAt`	Sort field
`sortOrder`	string	No	`DESC`	`ASC` or `DESC`

bash

curl "https://gateway.useyona.com/i/v1/invoices?status=draft&page=1&limit=10&sortOrder=DESC" \
  -H "Authorization: Bearer sk_test_your_key_here"

Get invoice

GET /i/v1/invoices/:id

Retrieve a single invoice by ID. Returns the full invoice object including line items.

bash

curl https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Invoice not found

Update invoice

PATCH /i/v1/invoices/:id

Update a draft invoice. Only invoices in draft status can be updated. Fields sellerId, buyerId, and invoiceNumber are immutable after creation.

bash

curl -X PATCH https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "dueDate": "2026-06-30",
    "paymentTerms": "Net 60",
    "notes": "Updated payment terms per client agreement"
  }'

Status	Code	Trigger
400	INV003	Invoice is not in `draft` status
400	VAL001	Invalid field values
404	RES001	Invoice not found

Delete invoice

DELETE /i/v1/invoices/:id

Delete a draft invoice. Only invoices in draft status can be deleted.

bash

curl -X DELETE https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	INV003	Invoice is not in `draft` status
404	RES001	Invoice not found

Finalise invoice

POST /i/v1/invoices/:id/finalise

Lock a draft invoice for submission. Freezes totals, sets status to finalised, and sets finalisedAt timestamp. Required before submitting to the tax authority or sending to the buyer. Does not require an NRS connection. No request body.

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/finalise \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	INV003	Invoice is not in `draft` status
404	RES001	Invoice not found

Send invoice to buyer

POST /i/v1/invoices/:id/send

Send a finalised invoice to the buyer. The invoice must be locked (finalised or further). The buyer must have an email address on record. Always fires an invoice.sent webhook event. If your organization has email delivery enabled, the buyer receives the invoice as a PDF attachment via email. Works regardless of tax-authority connection — you can send invoices to buyers without being connected to NRS. No request body.

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/send \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	INV003	Invoice is not finalised (must be locked first)
400	BIZ005	Buyer does not have an email address
404	RES001	Invoice not found

Invoice lifecycle: Draft → Finalise → Send to buyer (optional) → Submit to tax authority. Finalising and sending work without an NRS connection; submission requires one. Connect your NRS identity

Submit invoice

POST /i/v1/invoices/:id/submit

Queue a finalised invoice for submission to the tax authority. The invoice must be in finalised status — use the Finalise endpoint first. Requires an active NRS connection (status: CONNECTED). In production, submission is irreversible.

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/submit \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	BIZ004	Invoice is not in `finalised` status
400	INV002	Invoice already submitted
400	BIZ001	Insufficient credits
403	BIZ006	Organization is not connected to the tax authority
404	RES001	Invoice not found

Batch submit

POST /i/v1/invoices/batch-submit

Submit multiple invoices at once. Maximum 100 invoices per request.

Request body

Field	Type	Required	Description
`invoiceIds`	string[]	Yes	Array of invoice UUIDs, 1-100 items

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/batch-submit \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceIds": [
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "b2c3d4e5-f6a7-8901-bcde-f12345678901",
      "c3d4e5f6-a7b8-9012-cdef-123456789012"
    ]
  }'

Retry failed submission

POST /i/v1/invoices/:id/retry

Retry a failed invoice submission. Only invoices in failed status can be retried. Maximum 5 retry attempts.

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/retry \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	BIZ004	Invoice is not in `failed` status
404	RES001	Invoice not found

Cancel invoice

POST /i/v1/invoices/:id/cancel

Cancel an accepted invoice. Creates a credit note automatically. Only invoices in accepted status can be cancelled.

Request body

Field	Type	Required	Description
`reason`	string	Yes	Cancellation reason
`notes`	string	No	Additional notes

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cancel \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Duplicate invoice issued in error" }'

Status	Code	Trigger
400	BIZ004	Invoice is not in `accepted` status
404	RES001	Invoice not found

Get invoice status

GET /i/v1/invoices/:id/status

Get current invoice status from the local database. Fast and suitable for polling.

bash

curl https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/status \
  -H "Authorization: Bearer sk_test_your_key_here"

Query real-time status

POST /i/v1/invoices/:id/query-status

Query real-time status directly from the tax authority. Slower than getStatus — use sparingly. Best for verifying final acceptance or investigating rejections.

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/query-status \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
404	RES001	Invoice not found
502	TAX001	Tax authority connection error

Validate invoice

POST /i/v1/invoices/validate

Validate invoice data without creating it. Uses the same request body as create invoice. Useful for pre-validation before submission.

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/validate \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "sellerId": "c7a1d3e5-8f2b-4a6c-9d0e-1f2a3b4c5d6e",
    "buyerId": "d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f",
    "invoiceNumber": "INV-2026-002",
    "invoiceDate": "2026-04-30",
    "lineItems": [{
      "description": "Annual ERP licensing fee",
      "hsnCode": "9984",
      "quantity": 1,
      "unitCode": "EA",
      "unitPrice": 2500000,
      "taxPercent": 7.5
    }]
  }'

Status	Code	Trigger
400	VAL001	Missing or invalid fields
400	INV001	Invalid invoice format
404	RES001	Seller or buyer not found

Download invoice

GET /i/v1/invoices/:id/download

Get a download URL for the invoice PDF. Only accepted invoices can be downloaded.

Query parameters

Parameter	Type	Default	Description
`format`	string	`pdf`	`pdf` \| `xml`. Default: `pdf`

bash

curl "https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download?format=pdf" \
  -H "Authorization: Bearer sk_test_your_key_here"

Get statistics

GET /i/v1/invoices/statistics

Get invoice counts and totals grouped by status.

Query parameters

Parameter	Type	Required	Description
`startDate`	string	No	ISO date, filter from
`endDate`	string	No	ISO date, filter to
`jurisdiction`	string	No	ISO 2-letter country code

bash

curl "https://gateway.useyona.com/i/v1/invoices/statistics?startDate=2026-01-01&endDate=2026-04-30" \
  -H "Authorization: Bearer sk_test_your_key_here"

Search HSN codes

GET /i/v1/invoices/hsn-codes

Search HSN/tax classification codes by keyword.

Query parameters

Parameter	Type	Required	Description
`search`	string	No	Keyword search
`category`	string	No	Filter by category

bash

curl "https://gateway.useyona.com/i/v1/invoices/hsn-codes?search=software&category=Services" \
  -H "Authorization: Bearer sk_test_your_key_here"

HSN code categories

GET /i/v1/invoices/hsn-codes/categories

List all available HSN code categories with their code counts.

bash

curl https://gateway.useyona.com/i/v1/invoices/hsn-codes/categories \
  -H "Authorization: Bearer sk_test_your_key_here"

Get invoice resources

GET /i/v1/invoices/resources

Returns all reference data needed for building invoice forms: countries, currencies, tax categories, payment means, invoice types, service codes, tax exemptions, and product codes.

bash

curl https://gateway.useyona.com/i/v1/invoices/resources \
  -H "Authorization: Bearer sk_test_your_key_here"

Get resource by type

GET /i/v1/invoices/resources/:type

Retrieve a single resource type instead of all resources at once.

Path parameters

Parameter	Type	Required	Description
`type`	string	Yes	`countries` \| `currencies` \| `tax-categories` \| `payment-means` \| `invoice-types` \| `service-codes` \| `tax-exemptions` \| `product-codes`

bash

curl https://gateway.useyona.com/i/v1/invoices/resources/tax-categories \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	VAL001	Invalid resource type

Look up tax ID

GET /i/v1/invoices/lookup/tax-id/:value

Look up a taxpayer by their tax identification number. Returns registration status and basic business information from the tax authority.

bash

curl https://gateway.useyona.com/i/v1/invoices/lookup/tax-id/12345678-0001 \
  -H "Authorization: Bearer sk_test_your_key_here"

Status	Code	Trigger
400	VAL001	Invalid tax ID format
502	TAX001	Tax authority connection error

Validate reference

POST /i/v1/invoices/reference/validate

Validate an invoice reference number against the tax authority. Useful for verifying that a reference is legitimate before processing payments.

Request body

Field	Type	Required	Description
`reference`	string	Yes	Invoice reference to validate
`businessId`	string	Yes	Business registration ID
`externalReference`	string	No	External reference for correlation

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/reference/validate \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reference": "NRS-2026-REF-00891",
    "businessId": "RC-123456"
  }'

Status	Code	Trigger
400	VAL001	Missing or invalid fields
502	TAX001	Tax authority connection error

Submit tax report

POST /i/v1/invoices/:id/tax-report

Submit a tax report for an invoice to the tax authority. This generates a formal tax declaration based on the invoice transaction details.

Request body

Field	Type	Required	Description
`invoiceReference`	string	Yes	Invoice reference number
`supplierTaxId`	string	Yes	Supplier tax identification number
`buyerTaxId`	string	Yes	Buyer tax identification number
`baseAmount`	number	Yes	Pre-tax amount
`taxAmount`	number	Yes	Tax amount
`taxRate`	number	Yes	Tax rate percentage (e.g. 7.5)
`totalAmount`	number	Yes	Total including tax
`currency`	string	Yes	Currency code: `NGN`, `USD`, `EUR`, `GBP`
`transactionDate`	string	Yes	ISO date of the transaction
`itemDescription`	string	Yes	Description of goods or services
`integratorServiceId`	string	No	Integrator service identifier
`otherTaxes`	number	No	Additional tax amounts
`taxStatus`	string	No	Tax status override

bash

curl -X POST https://gateway.useyona.com/i/v1/invoices/a1b2c3d4-e5f6-7890-abcd-ef1234567890/tax-report \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceReference": "NRS-2026-REF-00891",
    "supplierTaxId": "12345678-0001",
    "buyerTaxId": "87654321-0001",
    "baseAmount": 1650000,
    "taxAmount": 123750,
    "taxRate": 7.5,
    "totalAmount": 1773750,
    "currency": "NGN",
    "transactionDate": "2026-04-30",
    "itemDescription": "Software development and cloud hosting services"
  }'

Status	Code	Trigger
400	VAL001	Missing or invalid fields
404	RES001	Invoice not found
502	TAX001	Tax authority connection error