Skip to content
ZUTAX ZUTAX Documentation

Composite: upsert customer + create invoice + sign + submit

POST
/api/public/v1/invoices/transmit
Code sample: cURL 
curl --request POST \
  --url 'https://api.getzutax.com/api/public/v1/invoices/transmit?async=false' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <unique-request-key>' \
  --data '{
  "external_id": "inv-2026-0002",
  "currency": "NGN",
  "issue_date": "2026-02-11",
  "due_date": "2026-02-25",
  "invoice_kind": "b2b",
  "note": "Single-call invoice transmission through Pasca.",
  "customer": {
    "external_id": "cust-obs-001",
    "legal_name": "Optimum Business Solution Ltd",
    "trading_name": "OBS",
    "tin": "TIN-12345678",
    "email": "accounts@obs.ng",
    "phone": "+2348012345678",
    "is_peppol_participant": true,
    "address": {
      "address_type": "postal",
      "street_name": "Adeola Odeku Street",
      "city_name": "Lagos",
      "state": "Lagos",
      "country_code": "NG"
    }
  },
  "lines": [
    {
      "product": {
        "external_id": "svc-erp-integration",
        "name": "ERP integration implementation",
        "default_unit_price_naira": 200000
      },
      "name": "ERP integration implementation",
      "description": "Discovery, implementation, and go-live support",
      "quantity": 1,
      "unit_price_naira": 200000,
      "vat_rate": 0.075,
      "discount_naira": 0
    }
  ],
  "options": {
    "submit_to_pasca": true,
    "fail_fast": true,
    "validate_party_tin_via_pasca": true
  }
}'

One-call pipeline. On partial failure returns 422 with a ‘partial_state’ block containing invoice_id, irn (if signed), and next_action. Pass ?async=true for fire-and-forget — the call returns a 202 with job_id; poll GET /jobs/{id} for status.

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
InvoiceTransmitInput
object
external_id
required
External Id
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
customer
required
EmbeddedCustomer
object
external_id
required
External Id
string
>= 1 characters <= 255 characters
legal_name
required
Legal Name
string
>= 1 characters <= 500 characters
trading_name
Any of:
string
tin
Any of:
string
email
Any of:
string
phone
Any of:
string
is_peppol_participant
Is Peppol Participant
boolean
address
Any of:
EmbeddedAddress
object
address_type
Address Type
string
default: postal
street_name
Any of:
string
city_name
required
City Name
string
>= 1 characters <= 100 characters
state
Any of:
string
country_code
Country Code
string
default: NG >= 2 characters <= 2 characters
lines
required
Lines
Array<object>
>= 1 items
TransmitLineInput
object
product
Any of:
EmbeddedProduct
object
external_id
required
External Id
string
>= 1 characters <= 255 characters
name
required
Name
string
>= 1 characters <= 500 characters
default_unit_price_naira
Any of:
number
name
required
Name
string
>= 1 characters <= 500 characters
description
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
options
TransmitOptions
object
submit_to_pasca
Submit To Pasca
boolean
default: true
fail_fast
Fail Fast
boolean
default: true
validate_party_tin_via_pasca
Validate Party Tin Via Pasca
boolean
Examples
Example Create and transmit invoice

Composite flow: customer, invoice, validation, signing, Pasca submit

{
  "external_id": "inv-2026-0002",
  "currency": "NGN",
  "issue_date": "2026-02-11",
  "due_date": "2026-02-25",
  "invoice_kind": "b2b",
  "note": "Single-call invoice transmission through Pasca.",
  "customer": {
    "external_id": "cust-obs-001",
    "legal_name": "Optimum Business Solution Ltd",
    "trading_name": "OBS",
    "tin": "TIN-12345678",
    "email": "accounts@obs.ng",
    "phone": "+2348012345678",
    "is_peppol_participant": true,
    "address": {
      "address_type": "postal",
      "street_name": "Adeola Odeku Street",
      "city_name": "Lagos",
      "state": "Lagos",
      "country_code": "NG"
    }
  },
  "lines": [
    {
      "product": {
        "external_id": "svc-erp-integration",
        "name": "ERP integration implementation",
        "default_unit_price_naira": 200000
      },
      "name": "ERP integration implementation",
      "description": "Discovery, implementation, and go-live support",
      "quantity": 1,
      "unit_price_naira": 200000,
      "vat_rate": 0.075,
      "discount_naira": 0
    }
  ],
  "options": {
    "submit_to_pasca": true,
    "fail_fast": true,
    "validate_party_tin_via_pasca": true
  }
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Successful Response

Media type application/json
InvoiceTransmitResult
object
invoice
required
TransmitInvoiceSummary
object
id
required
Id
string format: uuid
external_id
required
External Id
string
status
required
Status
string
Allowed values: draft submitted validated dispatched delivered accepted rejected paid cancelled
irn
Any of:
string
pasca_dispatch_id
Any of:
string
customer
required
TransmitResourceRef
object
id
required
Id
string format: uuid
external_id
required
External Id
string
created
required
Created
boolean
products
Products
Array<object>
TransmitResourceRef
object
id
required
Id
string format: uuid
external_id
required
External Id
string
created
required
Created
boolean
steps_completed
required
Steps Completed
Array<string>
Allowed values: party_upsert products_upsert invoice_create validate irn_sign pasca_submit
elapsed_ms
required
Elapsed Ms
integer
Examples
Example Invoice transmitted

Composite flow completed

{
  "invoice": {
    "id": "f3df2967-7cbe-4cca-8c8c-975ee2f6857f",
    "external_id": "inv-2026-0002",
    "status": "submitted",
    "irn": "ZTX-INV-2026-0002",
    "pasca_dispatch_id": "pasca-dsp-01HQYEXAMPLE"
  },
  "customer": {
    "id": "8a1c7f6c-61a1-4d89-8d96-3f7e7747f0c0",
    "external_id": "cust-obs-001",
    "created": false
  },
  "products": [
    {
      "id": "086c9f4a-c469-4be6-b3c3-4b022b27e9f6",
      "external_id": "svc-erp-integration",
      "created": false
    }
  ],
  "steps_completed": [
    "party_upsert",
    "products_upsert",
    "invoice_create",
    "validate",
    "irn_sign",
    "pasca_submit"
  ],
  "elapsed_ms": 1840
}

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 ”

Unprocessable Entity

Media type application/json
InvoiceTransmitFailure
object
error
required
TransmitErrorBody
object
type
Type
string
default: step_failed
Allowed value: step_failed
step
required
TransmitStep

Discrete steps of the composite issue+transmit pipeline.

string
Allowed values: party_upsert products_upsert invoice_create validate irn_sign pasca_submit
message
required
Message
string
code
Any of:
string
request_id
Any of:
string
details
Any of:
object
key
additional properties
any
partial_state
required
TransmitPartialState
object
external_id
required
External Id
string
invoice_id
Any of:
string format: uuid
customer_id
Any of:
string format: uuid
products
Products
Array<object>
TransmitResourceRef
object
id
required
Id
string format: uuid
external_id
required
External Id
string
created
required
Created
boolean
irn
Any of:
string
steps_completed
required
Steps Completed
Array<string>
Allowed values: party_upsert products_upsert invoice_create validate irn_sign pasca_submit
next_action
Any of:
string
Examples
Example Sample response

422 response example

{
  "error": {
    "type": "step_failed",
    "step": "party_upsert",
    "message": "string",
    "code": "string",
    "request_id": "string",
    "details": {}
  },
  "partial_state": {
    "external_id": "string",
    "invoice_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "customer_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "products": [
      {}
    ],
    "irn": "string",
    "steps_completed": [
      "party_upsert"
    ]
  }
}