curl --request POST \
  --url https://api.panoflow.io/v1/collections/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cus_01JX45HY43KWJRP1XPA7Z3DJ8F",
  "line_items": [
    {
      "description": "Haulage, Kano to Abuja (40ft)",
      "quantity": 2,
      "unit_price": {
        "amount": 85000000,
        "currency": "NGN"
      }
    },
    {
      "description": "Loading and handling",
      "quantity": 1,
      "unit_price": {
        "amount": 12000000,
        "currency": "NGN"
      }
    }
  ],
  "vat_enabled": true,
  "due_in_days": 14,
  "virtual_account_requested": true,
  "reminders_enabled": true,
  "note": "Thank you for your business.",
  "send": true
}
'

{
  "id": "ivc_01JE28JT97KB6CQ643DZVMXXQK",
  "object": "invoice",
  "created_at": "2026-10-28T09:20:00Z",
  "updated_at": "2026-10-28T09:20:02Z",
  "number": "INV-0155",
  "status": "sent",
  "customer": {
    "id": "cus_01JX45HY43KWJRP1XPA7Z3DJ8F",
    "name": "Kano Freight Services",
    "email": "ap@kanofreight.ng"
  },
  "currency": "NGN",
  "line_items": [
    {
      "description": "Haulage, Kano to Abuja (40ft)",
      "quantity": 2,
      "unit_price": {
        "amount": 85000000,
        "currency": "NGN"
      },
      "amount": {
        "amount": 170000000,
        "currency": "NGN"
      }
    },
    {
      "description": "Loading and handling",
      "quantity": 1,
      "unit_price": {
        "amount": 12000000,
        "currency": "NGN"
      },
      "amount": {
        "amount": 12000000,
        "currency": "NGN"
      }
    }
  ],
  "vat_enabled": true,
  "vat_rate_bps": 750,
  "subtotal": {
    "amount": 182000000,
    "currency": "NGN"
  },
  "vat": {
    "amount": 13650000,
    "currency": "NGN"
  },
  "total": {
    "amount": 195650000,
    "currency": "NGN"
  },
  "amount_paid": {
    "amount": 0,
    "currency": "NGN"
  },
  "amount_due": {
    "amount": 195650000,
    "currency": "NGN"
  },
  "due_in_days": 14,
  "issued_on": "2026-10-28",
  "due_on": "2026-11-11",
  "virtual_account_requested": true,
  "virtual_account": {
    "account_number": "9011554730",
    "bank_name": "Providus Bank",
    "bank_code": "101",
    "account_name": "Adaeze Logistics Ltd / INV-0155",
    "status": "active",
    "created_at": "2026-10-28T09:20:01Z"
  },
  "pay_page": {
    "slug": "inv-0155",
    "url": "https://pay.panoflow.io/inv-0155"
  },
  "settlement_account": {
    "id": "acc_01J26W14WMCHWYFGCW8T7SWM4F",
    "name": "Naira · Main",
    "account_number": "8012457739"
  },
  "reminders_enabled": true,
  "next_reminder_on": "2026-11-08",
  "note": "Thank you for your business.",
  "payments": [],
  "activity": [
    {
      "type": "created",
      "at": "2026-10-28T09:20:00Z",
      "actor": {
        "type": "user",
        "id": "usr_01JNTH82F7AG3BCKKDJWBHP1G2",
        "name": "Adaeze Okafor"
      }
    },
    {
      "type": "virtual_account_created",
      "at": "2026-10-28T09:20:01Z"
    },
    {
      "type": "sent",
      "at": "2026-10-28T09:20:02Z",
      "to": "ap@kanofreight.ng"
    }
  ],
  "sent_at": "2026-10-28T09:20:02Z",
  "created_by": {
    "type": "user",
    "id": "usr_01JNTH82F7AG3BCKKDJWBHP1G2",
    "name": "Adaeze Okafor"
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "response_code": "13",
    "code": "amount_too_small",
    "message": "Add at least one priced item.",
    "param": "line_items",
    "request_id": "req_01JJJHHQGGCWFBFF9JCM4SGFE6"
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Invoices

Create an invoice (draft, or create and send)

Creates an invoice with the next invoice number (INV-0155). The server computes every line amount, the subtotal, VAT (7.5% of the subtotal, rounded half up to the kobo, when vat_enabled) and the total; clients never send totals.

send: false (default) saves a draft. Nothing is emailed and no account number is created.
send: true creates and sends in one call: same as creating a draft then calling sendInvoice. When virtual_account_requested is true, the per-invoice account number is opened at the partner bank before the email goes out; if the bank is unavailable the call fails with 503 and nothing is created (retry with the same Idempotency-Key).

The customer is either an existing one (customer_id) or a new one (customer), which is saved. Emits invoice.sent when sent.

Error codes: invalid_api_key, parameter_invalid, parameter_missing, resource_not_found, scope_missing, csrf_token_invalid, idempotency_key_reused, account_closed, amount_too_small, currency_mismatch, currency_not_enabled, bank_unavailable, rate_limited.

POST

collections

invoices

curl --request POST \
  --url https://api.panoflow.io/v1/collections/invoices \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer_id": "cus_01JX45HY43KWJRP1XPA7Z3DJ8F",
  "line_items": [
    {
      "description": "Haulage, Kano to Abuja (40ft)",
      "quantity": 2,
      "unit_price": {
        "amount": 85000000,
        "currency": "NGN"
      }
    },
    {
      "description": "Loading and handling",
      "quantity": 1,
      "unit_price": {
        "amount": 12000000,
        "currency": "NGN"
      }
    }
  ],
  "vat_enabled": true,
  "due_in_days": 14,
  "virtual_account_requested": true,
  "reminders_enabled": true,
  "note": "Thank you for your business.",
  "send": true
}
'

{
  "id": "ivc_01JE28JT97KB6CQ643DZVMXXQK",
  "object": "invoice",
  "created_at": "2026-10-28T09:20:00Z",
  "updated_at": "2026-10-28T09:20:02Z",
  "number": "INV-0155",
  "status": "sent",
  "customer": {
    "id": "cus_01JX45HY43KWJRP1XPA7Z3DJ8F",
    "name": "Kano Freight Services",
    "email": "ap@kanofreight.ng"
  },
  "currency": "NGN",
  "line_items": [
    {
      "description": "Haulage, Kano to Abuja (40ft)",
      "quantity": 2,
      "unit_price": {
        "amount": 85000000,
        "currency": "NGN"
      },
      "amount": {
        "amount": 170000000,
        "currency": "NGN"
      }
    },
    {
      "description": "Loading and handling",
      "quantity": 1,
      "unit_price": {
        "amount": 12000000,
        "currency": "NGN"
      },
      "amount": {
        "amount": 12000000,
        "currency": "NGN"
      }
    }
  ],
  "vat_enabled": true,
  "vat_rate_bps": 750,
  "subtotal": {
    "amount": 182000000,
    "currency": "NGN"
  },
  "vat": {
    "amount": 13650000,
    "currency": "NGN"
  },
  "total": {
    "amount": 195650000,
    "currency": "NGN"
  },
  "amount_paid": {
    "amount": 0,
    "currency": "NGN"
  },
  "amount_due": {
    "amount": 195650000,
    "currency": "NGN"
  },
  "due_in_days": 14,
  "issued_on": "2026-10-28",
  "due_on": "2026-11-11",
  "virtual_account_requested": true,
  "virtual_account": {
    "account_number": "9011554730",
    "bank_name": "Providus Bank",
    "bank_code": "101",
    "account_name": "Adaeze Logistics Ltd / INV-0155",
    "status": "active",
    "created_at": "2026-10-28T09:20:01Z"
  },
  "pay_page": {
    "slug": "inv-0155",
    "url": "https://pay.panoflow.io/inv-0155"
  },
  "settlement_account": {
    "id": "acc_01J26W14WMCHWYFGCW8T7SWM4F",
    "name": "Naira · Main",
    "account_number": "8012457739"
  },
  "reminders_enabled": true,
  "next_reminder_on": "2026-11-08",
  "note": "Thank you for your business.",
  "payments": [],
  "activity": [
    {
      "type": "created",
      "at": "2026-10-28T09:20:00Z",
      "actor": {
        "type": "user",
        "id": "usr_01JNTH82F7AG3BCKKDJWBHP1G2",
        "name": "Adaeze Okafor"
      }
    },
    {
      "type": "virtual_account_created",
      "at": "2026-10-28T09:20:01Z"
    },
    {
      "type": "sent",
      "at": "2026-10-28T09:20:02Z",
      "to": "ap@kanofreight.ng"
    }
  ],
  "sent_at": "2026-10-28T09:20:02Z",
  "created_by": {
    "type": "user",
    "id": "usr_01JNTH82F7AG3BCKKDJWBHP1G2",
    "name": "Adaeze Okafor"
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "type": "invalid_request",
    "response_code": "13",
    "code": "amount_too_small",
    "message": "Add at least one priced item.",
    "param": "line_items",
    "request_id": "req_01JJJHHQGGCWFBFF9JCM4SGFE6"
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

{
  "error": {
    "response_code": "00",
    "type": "invalid_request",
    "code": "invalid_json",
    "message": "<string>",
    "request_id": "<string>",
    "param": "<string>",
    "doc_url": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Server API key, scoped. pk_test_ keys hit the sandbox tenant.

Headers

Idempotency-Key

string

Optional on non-money POSTs; honoured when sent.

Required string length: 1 - 255

X-Request-Id

string

Optional client correlation id, up to 128 characters. It is not echoed: the response's X-Request-Id is always our own req_… id. We log your value with the request as client_request_id, so support can find a request by either id. A longer value is refused with 400 parameter_invalid.

Maximum string length: 128

Body

application/json

Exactly one of customer_id or customer is required.

line_items

object[]

required

At least one item; the total must be above zero.

Required array length: 1 - 100 elements

Show child attributes

due_in_days

enum<integer>

required

Payment terms: 0 = on receipt, else days after issued_on.

Available options:

0,

7,

14,

30

customer_id

string

A saved customer (cus_…).

customer

object

A new customer; saved for next time.

Show child attributes

vat_enabled

boolean

default:true

Add VAT at 7.5% of the subtotal.

virtual_account_requested

boolean

default:true

Give the invoice its own account number when it is sent (recommended in the app).

reminders_enabled

boolean

default:true

Automatic reminders 3 days before the due date, on it, and every 7 days after.

note

string

Note to the customer, shown on the invoice.

Maximum string length: 500

settlement_account_id

string

Account the money lands in (acc_…). Defaults to the business's Naira · Main account. Any of the business's active accounts in the same currency: Main, Payroll or a sub-account. Agent accounts are not allowed (an agent's money comes only from top-ups the team makes, within its limits). Payments are credited to this account directly.

404 resource_not_found if it isn't one of the business's accounts; 403 account_closed if it is closed; 422 currency_mismatch if it is in another currency; 400 parameter_invalid with param: settlement_account_id for an agent account, or one still opening.

send

boolean

default:false

True to send immediately (see sendInvoice); false saves a draft.

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Response

Invoice created (as a draft, or sent when send was true).

An invoice (ivc_…, an alias view of the shared col_ collection table).

string

required

ivc_…

object

string

required

Always invoice.

Allowed value: "invoice"

created_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

updated_at

string<date-time>

required

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

number

string

required

Human invoice number, sequential per business.

Pattern: ^INV-\d{4,}$

status

enum<string>

required

Invoice state (not a money movement; see CONVENTIONS §8 note in docs/discrepancies). draft → sent → partially_paid → paid; sent / partially_paid → overdue after due_on while money is still owed (an overdue invoice can have part payments; see amount_paid); draft / sent / partially_paid / overdue → void. UI labels: sent → "Awaiting payment", partially_paid → "Part paid".

Available options:

draft,

sent,

partially_paid,

overdue,

paid,

void

customer

object

required

The customer (payer) on an invoice or static virtual account.

Show child attributes

currency

enum<string>

required

ISO 4217. Only NGN is live at launch; others return 422 currency_not_enabled.

Available options:

NGN,

USD,

GBP,

EUR,

GHS,

KES

line_items

object[]

required

Lines in order.

Show child attributes

vat_enabled

boolean

required

Whether VAT is added.

vat_rate_bps

integer

required

Percentage in basis points (50 = 0.5%).

Required range: 0 <= x <= 10000

subtotal

object

required

Sum of line amounts, before VAT.

Show child attributes

vat

object

required

subtotal × vat_rate_bps / 10000, rounded half up to the minor unit. Zero when VAT is off.

Show child attributes

total

object

required

subtotal + vat.

Show child attributes

amount_paid

object

required

Sum of payments.

Show child attributes

amount_due

object

required

"Left to pay": total − amount_paid, never below zero. Zero when paid or void.

Show child attributes

due_in_days

enum<integer>

required

Payment terms.

Available options:

0,

7,

14,

30

virtual_account_requested

boolean

required

Whether the invoice gets (or got) its own account number.

pay_page

object

required

The invoice's pay page. Every invoice has one; it shows 404 to payers while a draft.

Show child attributes

settlement_account

object

required

One of the business's own PanoFlow accounts (owned by the Accounts service).

Show child attributes

reminders_enabled

boolean

required

Automatic reminders on.

overpaid

object

Present when payments exceed the total. The excess stays in the settlement account.

Show child attributes

issued_on

string<date>

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

due_on

string<date>

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

days_overdue

integer

Whole days past due_on, when overdue ("6 days late").

virtual_account

object

The invoice's own (per-invoice, dynamic) account number. Anything paid into it is recorded against this invoice.

Show child attributes

next_reminder_on

string<date>

Calendar date, interpreted in Africa/Lagos.

Example:

"2026-11-07"

note

string

Note to the customer.

payments

object[]

Money recorded against the invoice, oldest first.

Show child attributes

activity

object[]

Timeline for the drawer. Returned by getInvoice and invoice actions; omitted from lists.

Show child attributes

sent_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

paid_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

voided_at

string<date-time>

RFC 3339, UTC.

Example:

"2026-10-27T08:41:00Z"

created_by

object

Who did something. Shown in activity, approvals and the audit log.

Show child attributes

metadata

object

Up to 20 string keys (≤ 40 chars) with string values (≤ 500 chars). Returned on the resource and its events.

Show child attributes

Accounts & transactions

Payments

Collections

Payroll

Approvals

Webhooks & events

OAuth

Create an invoice (draft, or create and send)

Authorizations

Headers

Body

Response