Create invoice

Authorizations

HTTPBearer
HTTPBearer

Header Parameters

X-Workspace-ID

Any of:

string
null

string

X-API-Key

Any of:

string
null

string

X-Tenant-ID

Any of:

string
null

string

Request Body^required

InvoiceCreate

Create invoice schema.

object

irn

Any of:

string
null

string

<= 200 characters

invoice_number

Any of:

string
null

string

<= 200 characters

invoice_number_policy_id

Any of:

string
null

string format: uuid

invoice_type_code

Invoice Type Code

string

default: 380 <= 10 characters

invoice_kind

Any of:

string
null

string

/^(b2b|b2c|b2g)$/

issue_date

required

Issue Date

string format: date

issue_time

Any of:

string
null

string

<= 20 characters

due_date

Any of:

string
null

string format: date

tax_point_date

Any of:

string
null

string format: date

document_currency_code

Document Currency Code

string

default: NGN <= 3 characters

tax_currency_code

Any of:

string
null

string

<= 3 characters

supplier_id

required

Supplier Id

string format: uuid

customer_id

required

Customer Id

string format: uuid

note

Any of:

string
null

string

order_reference

Any of:

string
null

string

<= 200 characters

buyer_reference

Any of:

string
null

string

<= 200 characters

contract_reference

Any of:

string
null

string

<= 200 characters

accounting_cost

Any of:

string
null

string

<= 100 characters

invoice_period_start

Any of:

string
null

string format: date

invoice_period_end

Any of:

string
null

string format: date

actual_delivery_date

Any of:

string
null

string format: date

payment_terms_note

Any of:

string
null

string

<= 2000 characters

credit_reason_code

Any of:

string
null

string

<= 32 characters

credit_reason_text

Any of:

string
null

string

referenced_invoice_id

Any of:

string
null

string format: uuid

referenced_invoice_irn

Any of:

string
null

string

<= 200 characters

lines

required

Lines

Array<object>

>= 1 items

InvoiceLineCreate

Create invoice line schema.

object

line_number

required

Line Number

integer

>= 1

item_name

required

Item Name

string

<= 500 characters

item_description

Any of:

string
null

string

sellers_item_id

Any of:

string
null

string

<= 200 characters

buyers_item_id

Any of:

string
null

string

<= 200 characters

item_type

Any of:

string
null

string

/^(good|service)$/

hsn_code

Any of:

string
null

string

<= 100 characters

product_category

Any of:

string
null

string

<= 255 characters

isic_code

Any of:

integer
null

integer

service_category

Any of:

string
null

string

<= 255 characters

discount_rate

Any of:

number
string

number

discount_amount

Any of:

number
string

number

fee_rate

Any of:

number
string

number

fee_amount

Any of:

number
string

number

invoiced_quantity

required

Any of:

number
string

number

> 0

unit_code

Unit Code

string

default: C62 <= 10 characters

base_quantity

Any of:

number
string

number

> 0

price_amount

required

Any of:

number
string

number

tax_category_code

Any of:

string
null

string

<= 64 characters

tax_rate

Any of:

number

<= 100

note

Any of:

string
null

string

line_extension_amount

Any of:

number

payment_means

Payment Means

Array<object>

default:

PaymentMeansCreate

Create payment means schema.

object

payment_means_code

required

Payment Means Code

string

<= 10 characters

payment_account_id

Any of:

string
null

string

<= 100 characters

payment_account_name

Any of:

string
null

string

<= 255 characters

financial_institution_branch_id

Any of:

string
null

string

<= 50 characters

document_references

Document References

Array<object>

default:

DocumentReferenceCreate

Create document reference schema.

object

reference_type

required

Reference Type

string

document_id

required

Document Id

string

>= 1 characters <= 200 characters

issue_date

Any of:

string
null

string format: date

party_roles

Party Roles

Array<object>

default:

InvoicePartyRoleCreate

Create additional party role schema.

object

role

required

Role

string

<= 30 characters /^(payee|bill|ship|tax_representative)$/

party_name

required

Party Name

string

>= 1 characters <= 500 characters

tin

Any of:

string
null

string

<= 100 characters

email

Any of:

string
null

string

<= 255 characters

phone

Any of:

string
null

string

<= 30 characters

street_name

Any of:

string
null

string

<= 500 characters

city_name

Any of:

string
null

string

<= 255 characters

postal_zone

Any of:

string
null

string

<= 50 characters

state

Any of:

string
null

string

<= 20 characters

country_code

Any of:

string
null

string

<= 2 characters

direction

InvoiceDirection

Invoice direction - sent or received.

string

default: outbound

Allowed values: outbound inbound

source_type

InvoiceSourceType

Source of the invoice record.

string

default: native

Allowed values: native external

external_invoice_number

Any of:

string
null

string

<= 200 characters

line_extension_amount

Any of:

number

tax_amount_total

Any of:

number

payable_amount

Any of:

number

Examples

Professional services invoice

{
  "irn": "ZTX-INV-2026-0001",
  "issue_date": "2026-02-11",
  "due_date": "2026-02-25",
  "document_currency_code": "NGN",
  "supplier_id": "2e7d8795-0b14-4df5-b1d7-65d3f4f1f77c",
  "customer_id": "8a1c7f6c-61a1-4d89-8d96-3f7e7747f0c0",
  "note": "Implementation and monthly support services.",
  "order_reference": "PO-2026-0019",
  "buyer_reference": "FIN-OPS",
  "lines": [
    {
      "line_number": 1,
      "item_name": "ERP integration services",
      "item_description": "Discovery, implementation, and go-live support",
      "invoiced_quantity": 1,
      "unit_code": "C62",
      "price_amount": 200000,
      "tax_category_code": "STANDARD_VAT",
      "tax_rate": 7.5
    },
    {
      "line_number": 2,
      "item_name": "Managed support",
      "invoiced_quantity": 1,
      "unit_code": "C62",
      "price_amount": 15000,
      "tax_category_code": "STANDARD_VAT",
      "tax_rate": 7.5
    }
  ],
  "payment_means": [
    {
      "payment_means_code": "58",
      "payment_account_id": "0123456789",
      "payment_account_name": "ZUTAX Nigeria Ltd",
      "financial_institution_branch_id": "011"
    }
  ]
}

Export goods invoice

{
  "irn": "ZTX-INV-2026-0002",
  "issue_date": "2026-02-11",
  "document_currency_code": "USD",
  "supplier_id": "2e7d8795-0b14-4df5-b1d7-65d3f4f1f77c",
  "customer_id": "8a1c7f6c-61a1-4d89-8d96-3f7e7747f0c0",
  "lines": [
    {
      "line_number": 1,
      "item_name": "E-invoicing appliance",
      "invoiced_quantity": 2,
      "unit_code": "C62",
      "price_amount": 350,
      "tax_category_code": "ZERO_VAT",
      "tax_rate": 0
    }
  ]
}

201

Successful Response

Examples

Created invoice response

{
  "id": "f3df2967-7cbe-4cca-8c8c-975ee2f6857f",
  "irn": "ZTX-INV-2026-0001",
  "status": "DRAFT",
  "issue_date": "2026-02-11",
  "document_currency_code": "NGN",
  "payable_amount": "235000.00"
}

422

Validation Error

HTTPValidationError

object

detail

Detail

Array<object>

ValidationError

object

loc

required

Location

Array

msg

required

Message

string

type

required

Error Type

string

Examples

422 response example

{
  "detail": [
    {
      "loc": [],
      "msg": "string",
      "type": "string"
    }
  ]
}

Create invoice

Authorizations

Parameters

Header Parameters

Request Body required

Examples

Responses

201

Examples

422

Examples

Request Body^required