Skip to content
ZUTAX ZUTAX Documentation

Create a draft invoice (granular)

POST
/api/public/v1/invoices
Code sample: cURL 
curl --request POST \
  --url 'https://api.getzutax.com/api/public/v1/invoices?async=false' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-request-key>' \
  --data '{
  "external_id": "inv-2026-0001",
  "customer_external_id": "cust-obs-001",
  "supplier_external_id": "tenant-zutax-ng",
  "currency": "NGN",
  "issue_date": "2026-02-11",
  "due_date": "2026-02-25",
  "invoice_kind": "b2b",
  "note": "Implementation and monthly support services.",
  "payment_terms": "Net 14",
  "lines": [
    {
      "name": "ERP integration implementation",
      "description": "Discovery, implementation, and go-live support",
      "product_external_id": "svc-erp-integration",
      "quantity": 1,
      "unit_price_naira": 200000,
      "vat_rate": 0.075,
      "discount_naira": 0,
      "isic_code": "6202"
    },
    {
      "name": "Managed support",
      "quantity": 1,
      "unit_price_naira": 15000,
      "vat_rate": 0.075,
      "discount_naira": 0
    }
  ]
}'

Creates an invoice in ‘draft’ status. Does NOT validate, sign, or submit to Pasca. Use POST /invoices/{id}/transmit or the composite POST /invoices/transmit endpoint to advance the lifecycle. Pass ?async=true to enqueue the work and receive a 202 with job_id; otherwise the call is synchronous (201).

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters ”
async
Async
boolean

Request Body required

Section titled “Request Body required ”
Media type application/json
InvoiceCreateInput
object
external_id
required
External Id
string
>= 1 characters <= 255 characters
customer_external_id
required
Customer External Id
string
>= 1 characters <= 255 characters
supplier_external_id
Any of:
string
>= 1 characters <= 255 characters
currency
Currency
string
default: NGN >= 3 characters <= 3 characters
issue_date
required
Issue Date
string format: date
due_date
required
Due Date
string format: date
invoice_kind
Invoice Kind
string
default: b2b
Allowed values: b2b b2c b2g
note
Any of:
string
payment_terms
Any of:
string
lines
required
Lines
Array<object>
>= 1 items
InvoiceLineInput
object
name
required
Name
string
>= 1 characters <= 500 characters
description
Any of:
string
product_external_id
Any of:
string
quantity
required
Any of:
number
> 0
unit_price_naira
required
Any of:
number
vat_rate
required
Any of:
number
<= 1
discount_naira
Any of:
number
isic_code
Any of:
string
Examples
Example Service invoice

Create a draft B2B invoice

{
  "external_id": "inv-2026-0001",
  "customer_external_id": "cust-obs-001",
  "supplier_external_id": "tenant-zutax-ng",
  "currency": "NGN",
  "issue_date": "2026-02-11",
  "due_date": "2026-02-25",
  "invoice_kind": "b2b",
  "note": "Implementation and monthly support services.",
  "payment_terms": "Net 14",
  "lines": [
    {
      "name": "ERP integration implementation",
      "description": "Discovery, implementation, and go-live support",
      "product_external_id": "svc-erp-integration",
      "quantity": 1,
      "unit_price_naira": 200000,
      "vat_rate": 0.075,
      "discount_naira": 0,
      "isic_code": "6202"
    },
    {
      "name": "Managed support",
      "quantity": 1,
      "unit_price_naira": 15000,
      "vat_rate": 0.075,
      "discount_naira": 0
    }
  ]
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

Media type application/json
Examples
Example Sample response

200 response example

{
  "status": "ok",
  "message": "Request completed successfully."
}

201

Section titled “201 ”

Created

Media type application/json
InvoiceResponse
object
id
required
Id
string format: uuid
external_id
required
Any of:
string
status
required
Status
string
Allowed values: draft submitted validated dispatched delivered accepted rejected paid cancelled
invoice_number
Any of:
string
irn
Any of:
string
currency
required
Currency
string
issue_date
required
Issue Date
string format: date
due_date
required
Due Date
string format: date
subtotal_naira
required
Subtotal Naira
string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
vat_total_naira
required
Vat Total Naira
string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
total_naira
required
Total Naira
string
/^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$/
customer_external_id
Any of:
string
pasca_dispatch_id
Any of:
string
Examples
Example Invoice created

Draft invoice response

{
  "id": "f3df2967-7cbe-4cca-8c8c-975ee2f6857f",
  "external_id": "inv-2026-0001",
  "status": "draft",
  "invoice_number": "INV-2026-0001",
  "irn": null,
  "currency": "NGN",
  "issue_date": "2026-02-11",
  "due_date": "2026-02-25",
  "subtotal_naira": "215000.00",
  "vat_total_naira": "16125.00",
  "total_naira": "231125.00",
  "customer_external_id": "cust-obs-001",
  "pasca_dispatch_id": null
}

202

Section titled “202 ”

Accepted

Media type application/json
JobAcceptedResponse

202 response body returned when an ERP POSTs ?async=true.

object
job_id
required
Job Id
string format: uuid
status
required
Status
string
Allowed values: queued running succeeded failed
result_url
required
Result Url
string
Examples
Example Sample response

202 response example

{
  "job_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "status": "queued",
  "result_url": "string"
}

422

Section titled “422 ”

Validation Error

Media type application/json
HTTPValidationError
object
detail
Detail
Array<object>
ValidationError
object
loc
required
Location
Array
msg
required
Message
string
type
required
Error Type
string
Examples
Example Sample response

422 response example

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