Invoices

List invoices

GET /i/v1/invoices

Requires invoice.read. The organisation’s invoices, credit notes and debit notes in the token’s mode, filtered and sorted by the query; newest first by default. List items carry no lineItems.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`status`	query	string	No	One of `draft` \| `finalised` \| `queued` \| `signed` \| `transmitted` \| `accepted` \| `rejected` \| `failed` \| `cancellation_pending` \| `cancelled`.
`invoiceType`	query	string	No	One of `standard` \| `credit_note` \| `debit_note`.
`paymentStatus`	query	string	No	One of `unpaid` \| `partially_paid` \| `paid` \| `payment_failed`.
`currency`	query	string	No
`buyerId`	query	string (uuid)	No
`sellerId`	query	string (uuid)	No	Only the organisation’s own seller id.
`createdBy`	query	string (uuid)	No	Only documents created by this actor id (`createdBy.id`): an auth user id, or an API-key id with `createdByType=api_key`.
`createdByType`	query	string	No	Only documents created by this kind of actor (`createdBy.type`). One of `user` \| `api_key` \| `service` \| `system`.
`invoiceDateFrom`	query	string	No
`invoiceDateTo`	query	string	No
`dueDateFrom`	query	string	No
`dueDateTo`	query	string	No
`createdAtFrom`	query	string	No
`createdAtTo`	query	string	No	Exclusive.
`search`	query	string	No	Matches the document number, the number NRS holds or the IRN by prefix, and the buyer name or TIN anywhere in it. Case-insensitive; `%` and `_` are plain characters. At most 100 characters.
`simpleStatus`	query	string	No	Only documents with this simple status (`simpleStatus`). One of `draft` \| `issued` \| `reported` \| `delivered` \| `paid` \| `part_paid` \| `cancelled`.
`reporting`	query	string	No	Only documents at this reporting stage, as the summary cards count them (`needs_attention` = rejected or on hold, not cancelled). One of `draft` \| `not_reported` \| `in_progress` \| `reported` \| `needs_attention`.
`delivery`	query	string	No	Only documents with this delivery channel (`reporting.delivery`). One of `nrs` \| `deliver_to_buyer` \| `sent_email` \| `shared_link` \| `none`.
`credited`	query	string	No	`true`: documents credited by a credit note that counts against them; `false`: invoices no credit note credits. One of `true` \| `false`.
`refundOwed`	query	string	No	`true`: documents on which a refund is still owed to the buyer; `false`: documents on which none is. One of `true` \| `false`.
`overdue`	query	string	No	Only issued invoices still owing (net of credit notes) past their due date today. One of `true`.
`amountFromMinor`	query	number	No	Payable amount at least this (minor units). At least 0.
`amountToMinor`	query	number	No	Payable amount at most this (minor units). At least 0.
`page`	query	number	No	Default: `1`. At least 1.
`limit`	query	number	No	Default: `20`. Between 1 and 100.
`sortBy`	query	string	No	One of `createdAt` \| `invoiceDate` \| `invoiceNumber` \| `payableMinor` \| `dueDate` \| `taxMinor`. Default: `createdAt`.
`sortOrder`	query	string	No	One of `ASC` \| `DESC`. Default: `DESC`.

Example request

bash

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

Responses

One page of documents (without lineItems), meta.pagination set.

Create a draft invoice

POST /i/v1/invoices

Requires invoice.create; charged as one invoice creation. Creates a draft (status: draft); the number is allocated from the series when invoiceNumber is omitted. Send an Idempotency-Key to make a retry safe: a repeated key answers the first result with Idempotent-Replayed: true. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Request body

Field	Type	Required	Description
`sellerId`	string (uuid)	No	Only the organisation’s own seller id.
`buyerId`	string (uuid)	No
`invoiceKind`	string	Yes	A kind of the jurisdiction (Nigeria: B2B, B2C, B2G, G2B).
`invoiceNumber`	string	No	Alphanumeric, 1–50; allocated when absent.
`invoiceType`	string	No	Only `standard`: credit and debit notes are issued against an invoice (cancel, credit-notes, debit-notes). One of `standard`.
`invoiceDate`	string	Yes	The issue date.
`issueTime`	string	No
`dueDate`	string	No	≥ the issue date.
`currency`	string	Yes
`lineItems`	array of InvoiceLineItem	Yes	1 to 500 items.
`allowanceAmount`	string or number	No	Document allowance, major units, ≤ 2 decimals.
`chargeAmount`	string or number	No	Document charge, major units, ≤ 2 decimals.
`paymentTerms`	string	No	At most 500 characters.
`notes`	string	No	At most 2000 characters.
`purchaseOrderReference`	string	No	At most 100 characters.
`buyerReference`	string	No	At most 100 characters.
`accountingCost`	string	No	At most 100 characters.

lineItems[]

Field	Type	Required	Description
`itemId`	string (uuid)	No	A saved item of the organisation: every field of the line left out is filled from the item, and a field sent wins.
`description`	string	No	Required without an itemId. 1 to 500 characters.
`itemName`	string	No	At most 255 characters.
`hsnCode`	string	No	HS code (goods).
`productCategory`	string	No	The HS description (goods). At most 500 characters.
`isicCode`	string	No	ISIC code (services); stored as the service code.
`serviceCategory`	string	No	The ISIC description (services). Stored as the line’s product category; send it or productCategory, not both. At most 500 characters.
`quantity`	string or number	Yes	Decimal string (≤ 6 decimals) or number; > 0.
`unitCode`	string	No	A unit code of the jurisdiction’s list. Required without an itemId.
`unitPrice`	string or number	No	Major units, decimal string (≤ 4 decimals) or number; ≥ 0. Required without an itemId.
`discountAmount`	string or number	No	Major units, ≤ 2 decimals.
`feeAmount`	string or number	No	Major units, ≤ 2 decimals.
`taxCategory`	string	No	A tax-category code-list id, or a short alias (standard \| zero \| exempt). Required without an itemId.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceKind": "B2B",
    "invoiceNumber": "INV00042",
    "invoiceDate": "2026-09-30",
    "issueTime": "14:30:00",
    "dueDate": "2026-10-30",
    "currency": "NGN",
    "lineItems": [
      {
        "description": "Consulting services",
        "hsnCode": "1006.30",
        "isicCode": "0112",
        "quantity": "2.5",
        "unitCode": "EA",
        "unitPrice": "50000.00",
        "discountAmount": "0",
        "feeAmount": "0",
        "taxCategory": "STANDARD_VAT"
      }
    ],
    "allowanceAmount": "0",
    "chargeAmount": "0"
  }'

Responses

The draft.

Get an invoice

GET /i/v1/invoices/{id}

Requires invoice.read. One document with its lines. A document of another organisation or of the other mode answers 404 RES001, like a missing one. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Update a draft invoice

PATCH /i/v1/invoices/{id}

Requires invoice.update_draft. Drafts only (409 BIZ201 otherwise). An absent field is unchanged; null clears an optional one; lineItems replaces every line. If-Match: "<version>" is optional; a stale version answers 409 RES003. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Field	Type	Required	Description
`sellerId`	string (uuid)	No
`buyerId`	string (uuid) or null	No	`null` removes the buyer.
`invoiceKind`	string	No
`invoiceNumber`	string	No
`invoiceDate`	string	No
`issueTime`	string or null	No
`dueDate`	string or null	No
`currency`	string	No
`lineItems`	array of InvoiceLineItem	No
`allowanceAmount`	string or number or null	No	Document allowance, major units, ≤ 2 decimals.
`chargeAmount`	string or number or null	No	Document charge, major units, ≤ 2 decimals.
`paymentTerms`	string or null	No	At most 500 characters.
`notes`	string or null	No	At most 2000 characters.
`purchaseOrderReference`	string or null	No	At most 100 characters.
`buyerReference`	string or null	No	At most 100 characters.
`accountingCost`	string or null	No	At most 100 characters.

lineItems[]

Field	Type	Required	Description
`itemId`	string (uuid)	No	A saved item of the organisation: every field of the line left out is filled from the item, and a field sent wins.
`description`	string	No	Required without an itemId. 1 to 500 characters.
`itemName`	string	No	At most 255 characters.
`hsnCode`	string	No	HS code (goods).
`productCategory`	string	No	The HS description (goods). At most 500 characters.
`isicCode`	string	No	ISIC code (services); stored as the service code.
`serviceCategory`	string	No	The ISIC description (services). Stored as the line’s product category; send it or productCategory, not both. At most 500 characters.
`quantity`	string or number	Yes	Decimal string (≤ 6 decimals) or number; > 0.
`unitCode`	string	No	A unit code of the jurisdiction’s list. Required without an itemId.
`unitPrice`	string or number	No	Major units, decimal string (≤ 4 decimals) or number; ≥ 0. Required without an itemId.
`discountAmount`	string or number	No	Major units, ≤ 2 decimals.
`feeAmount`	string or number	No	Major units, ≤ 2 decimals.
`taxCategory`	string	No	A tax-category code-list id, or a short alias (standard \| zero \| exempt). Required without an itemId.

Example request

bash

curl -X PATCH https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceKind": "B2C",
    "invoiceNumber": "INV00042",
    "invoiceDate": "2026-09-30",
    "issueTime": "14:30:00",
    "dueDate": "2026-10-30",
    "currency": "NGN"
  }'

Responses

The updated draft.

Delete a draft invoice

DELETE /i/v1/invoices/{id}

Requires invoice.delete_draft. Drafts only; the draft is deleted permanently and its number is never reused.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X DELETE https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210 \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Submit several invoices

POST /i/v1/invoices/batch-submit

Requires invoice.submit. Submits 1 to 100 invoices, each independently (its own charge and outcome); the batch counts once against the rate limit. Per-invoice results say which were queued and which failed.

Who can call it: API key or signed-in user.

Request body

Field	Type	Required	Description
`invoiceIds`	array of string (uuid)	Yes	1 to 100 items.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/batch-submit \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceIds": [
      "9f8e7d6c-5b4a-3210-fedc-ba9876543210"
    ]
  }'

Responses

List previously used HS or service codes

GET /i/v1/invoices/codes/used

item.read. type=goods reads the lines’ HS codes, type=service their service codes, over the organisation’s invoices in the token’s mode, every status (drafts and cancelled count). Most used first, then most recent; description is the most recent line’s product category for the code. This reads your own invoices, not the tax authority’s code lists.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`type`	query	string	Yes	goods → HS codes; service → service codes. One of `goods` \| `service`.
`limit`	query	number	No	Default: `20`. Between 1 and 100.

Example request

bash

curl "https://gp.useyona.com/i/v1/invoices/codes/used?type=goods" \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The codes, at most limit (default 20).

Errors: 400, 401, 403, 429

Create an invoice and submit it

POST /i/v1/invoices/create-and-submit

Requires invoice.create and invoice.submit. Creates the invoice as POST /invoices does, then submits it. When the submit is refused the draft is kept and submitRefusal says why. Accepts an Idempotency-Key.

Who can call it: API key or signed-in user.

Request body

Field	Type	Required	Description
`sellerId`	string (uuid)	No	Only the organisation’s own seller id.
`buyerId`	string (uuid)	No
`invoiceKind`	string	Yes	A kind of the jurisdiction (Nigeria: B2B, B2C, B2G, G2B).
`invoiceNumber`	string	No	Alphanumeric, 1–50; allocated when absent.
`invoiceType`	string	No	Only `standard`: credit and debit notes are issued against an invoice (cancel, credit-notes, debit-notes). One of `standard`.
`invoiceDate`	string	Yes	The issue date.
`issueTime`	string	No
`dueDate`	string	No	≥ the issue date.
`currency`	string	Yes
`lineItems`	array of InvoiceLineItem	Yes	1 to 500 items.
`allowanceAmount`	string or number	No	Document allowance, major units, ≤ 2 decimals.
`chargeAmount`	string or number	No	Document charge, major units, ≤ 2 decimals.
`paymentTerms`	string	No	At most 500 characters.
`notes`	string	No	At most 2000 characters.
`purchaseOrderReference`	string	No	At most 100 characters.
`buyerReference`	string	No	At most 100 characters.
`accountingCost`	string	No	At most 100 characters.

lineItems[]

Field	Type	Required	Description
`itemId`	string (uuid)	No	A saved item of the organisation: every field of the line left out is filled from the item, and a field sent wins.
`description`	string	No	Required without an itemId. 1 to 500 characters.
`itemName`	string	No	At most 255 characters.
`hsnCode`	string	No	HS code (goods).
`productCategory`	string	No	The HS description (goods). At most 500 characters.
`isicCode`	string	No	ISIC code (services); stored as the service code.
`serviceCategory`	string	No	The ISIC description (services). Stored as the line’s product category; send it or productCategory, not both. At most 500 characters.
`quantity`	string or number	Yes	Decimal string (≤ 6 decimals) or number; > 0.
`unitCode`	string	No	A unit code of the jurisdiction’s list. Required without an itemId.
`unitPrice`	string or number	No	Major units, decimal string (≤ 4 decimals) or number; ≥ 0. Required without an itemId.
`discountAmount`	string or number	No	Major units, ≤ 2 decimals.
`feeAmount`	string or number	No	Major units, ≤ 2 decimals.
`taxCategory`	string	No	A tax-category code-list id, or a short alias (standard \| zero \| exempt). Required without an itemId.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/create-and-submit \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceKind": "B2B",
    "invoiceNumber": "INV00042",
    "invoiceDate": "2026-09-30",
    "issueTime": "14:30:00",
    "dueDate": "2026-10-30",
    "currency": "NGN",
    "lineItems": [
      {
        "description": "Consulting services",
        "hsnCode": "1006.30",
        "isicCode": "0112",
        "quantity": "2.5",
        "unitCode": "EA",
        "unitPrice": "50000.00",
        "discountAmount": "0",
        "feeAmount": "0",
        "taxCategory": "STANDARD_VAT"
      }
    ],
    "allowanceAmount": "0",
    "chargeAmount": "0"
  }'

Responses

Get the invoicing dashboard overview

GET /i/v1/invoices/overview

Requires invoice.stats.read. Key figures over the last windowDays compared with the window before, the daily trend, status and payment distribution, collections, alerts, readiness and the most recent documents.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`windowDays`	query	number	No	Default: `7`. Between 1 and 90.

Example request

bash

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

Responses

Get the reference data for the invoice form

GET /i/v1/invoices/setup

Requires invoice.read. Currencies, invoice kinds, tax categories with their current rates, unit codes, the tax connection state, and the next invoice number (a preview, not reserved).

Who can call it: API key or signed-in user.

Example request

bash

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

Responses

Get invoice statistics

GET /i/v1/invoices/statistics

Requires invoice.stats.read. Over documents created in the window (default the last 30 days, at most 366): counts by status and by payment status, the success rate, totals by currency, and output tax.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`from`	query	string	No
`to`	query	string	No	Exclusive.

Example request

bash

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

Responses

Summarise the documents a list filter selects

GET /i/v1/invoices/summary

Requires invoice.stats.read. Takes the list’s filters (no paging or sorting) and counts the documents they select by reporting stage, with the money still owed (net of credit notes) and its overdue part per currency.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`status`	query	string	No	One of `draft` \| `finalised` \| `queued` \| `signed` \| `transmitted` \| `accepted` \| `rejected` \| `failed` \| `cancellation_pending` \| `cancelled`.
`invoiceType`	query	string	No	One of `standard` \| `credit_note` \| `debit_note`.
`paymentStatus`	query	string	No	One of `unpaid` \| `partially_paid` \| `paid` \| `payment_failed`.
`currency`	query	string	No
`buyerId`	query	string (uuid)	No
`sellerId`	query	string (uuid)	No	Only the organisation’s own seller id.
`createdBy`	query	string (uuid)	No	Only documents created by this actor id (`createdBy.id`): an auth user id, or an API-key id with `createdByType=api_key`.
`createdByType`	query	string	No	Only documents created by this kind of actor (`createdBy.type`). One of `user` \| `api_key` \| `service` \| `system`.
`invoiceDateFrom`	query	string	No
`invoiceDateTo`	query	string	No
`dueDateFrom`	query	string	No
`dueDateTo`	query	string	No
`createdAtFrom`	query	string	No
`createdAtTo`	query	string	No	Exclusive.
`search`	query	string	No	Matches the document number, the number NRS holds or the IRN by prefix, and the buyer name or TIN anywhere in it. Case-insensitive; `%` and `_` are plain characters. At most 100 characters.
`simpleStatus`	query	string	No	Only documents with this simple status (`simpleStatus`). One of `draft` \| `issued` \| `reported` \| `delivered` \| `paid` \| `part_paid` \| `cancelled`.
`reporting`	query	string	No	Only documents at this reporting stage, as the summary cards count them (`needs_attention` = rejected or on hold, not cancelled). One of `draft` \| `not_reported` \| `in_progress` \| `reported` \| `needs_attention`.
`delivery`	query	string	No	Only documents with this delivery channel (`reporting.delivery`). One of `nrs` \| `deliver_to_buyer` \| `sent_email` \| `shared_link` \| `none`.
`credited`	query	string	No	`true`: documents credited by a credit note that counts against them; `false`: invoices no credit note credits. One of `true` \| `false`.
`refundOwed`	query	string	No	`true`: documents on which a refund is still owed to the buyer; `false`: documents on which none is. One of `true` \| `false`.
`overdue`	query	string	No	Only issued invoices still owing (net of credit notes) past their due date today. One of `true`.
`amountFromMinor`	query	number	No	Payable amount at least this (minor units). At least 0.
`amountToMinor`	query	number	No	Payable amount at most this (minor units). At least 0.

Example request

bash

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

Responses

Validate an invoice with the tax authority (dry run)

POST /i/v1/invoices/validate

invoice.validate; charged per call before the tax authority gateway is asked, refunded when it could not answer. Answers 200 whether the document is valid or not: the verdict is the answer. Nothing is stored.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`Idempotency-Key`	header	string	No	8–128 of [A-Za-z0-9_-].

Request body

Field	Type	Required	Description
`invoiceId`	string (uuid)	No	Validate a stored invoice (alone).
`sellerId`	string (uuid)	No	Only the organisation’s own seller id.
`buyerId`	string (uuid)	No
`invoiceKind`	string	No
`invoiceNumber`	string	No
`invoiceType`	string	No	Only `standard`: credit notes are not validated here. One of `standard`.
`invoiceDate`	string	No	The issue date (required with an invoice body).
`issueTime`	string	No
`dueDate`	string	No
`currency`	string	No	ISO 4217 (required with an invoice body).
`lineItems`	array of ValidateLineItem	No	1 to 500 items.
`allowanceAmount`	string or number	No
`chargeAmount`	string or number	No
`paymentTerms`	string	No	At most 500 characters.
`notes`	string	No	At most 2000 characters.
`purchaseOrderReference`	string	No	At most 100 characters.
`buyerReference`	string	No	At most 100 characters.
`accountingCost`	string	No	At most 100 characters.

lineItems[]

Field	Type	Required	Description
`itemId`	string (uuid)	No	A saved item of the organisation: every omitted field below is filled from it.
`description`	string	No	Required without an itemId. 1 to 500 characters.
`itemName`	string	No	At most 255 characters.
`hsnCode`	string	No	At most 32 characters.
`productCategory`	string	No	At most 100 characters.
`isicCode`	string	No	The service code. At most 32 characters.
`serviceCategory`	string	No	At most 100 characters.
`quantity`	string or number	Yes	> 0, ≤ 6 decimals.
`unitCode`	string	No	Required without an itemId.
`unitPrice`	string or number	No	≥ 0, ≤ 4 decimals, major units. Required without an itemId.
`discountAmount`	string or number	No	major units, ≤ 2 decimals.
`feeAmount`	string or number	No	major units, ≤ 2 decimals.
`taxCategory`	string	No	Required without an itemId.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/validate \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "invoiceKind": "B2B",
    "invoiceDate": "2026-09-30",
    "issueTime": "10:30:00",
    "dueDate": "2026-10-30",
    "currency": "NGN"
  }'

Responses

The verdict.

Errors: 400, 402, 403, 404, 409, 422, 503

Get the tax authority’s copy of an invoice

GET /i/v1/invoices/{id}/authority-download

Requires invoice.download_authority_copy. The tax authority’s own decrypted copy of a registered document, as JSON. Not charged.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/authority-download \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Cancel an invoice

POST /i/v1/invoices/{id}/cancel

Requires invoice.cancel. A finalised invoice the tax authority does not hold (never submitted, rejected, or still queued) is voided locally, free of charge. A registered one is cancelled with a credit note for everything left, charged as one cancellation; it becomes cancelled once the credit note registers. A draft is 409 BIZ201 (delete it instead); a document in flight to the tax authority, a credit note, or one already cancelled is 409 BIZ004. Accepts an Idempotency-Key. Answers the original as it now stands. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Field	Type	Required	Description
`reason`	string	Yes	3 to 500 characters.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/cancel \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Issued to the wrong buyer"
  }'

Responses

The original invoice, cancelled or being cancelled.

Issue a credit note against a registered invoice

POST /i/v1/invoices/{id}/credit-notes

Requires invoice.cancel. Credits everything left (full), chosen lines and quantities (lines), or a tax-inclusive amount; several credit notes may be issued as long as their total stays within the payable amount plus any debit notes. Each credit note is charged as one cancellation. Accepts an Idempotency-Key. With preview: true nothing is written or charged and the answer is 200 with the preview.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Field	Type	Required	Description
`reason`	string	Yes	3 to 500 characters.
`mode`	string	Yes	One of `full` \| `lines` \| `amount`.
`lines`	array of CreditNoteLine	No	mode ‘lines’ only (required there)
`amountMinor`	number	No	mode ‘amount’ only (required there): the TAX-INCLUSIVE amount, minor units.
`lineNo`	number	No	mode ‘amount’ only: the original line whose text, codes and VAT the credit line takes (default 1)
`preview`	boolean	No	true: answer what would be issued; nothing is written or charged.

lines[]

Field	Type	Required	Description
`lineNo`	number	Yes	the ORIGINAL invoice’s line number.
`quantity`	string or number	Yes	decimal > 0, at most 6 decimals, ≤ what is left of the line.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/credit-notes \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Two units returned",
    "mode": "full",
    "amountMinor": 107500,
    "lineNo": 1
  }'

Responses

With preview: true: what would be issued.

The original invoice as it now stands and the credit note just issued.

Issue a debit note against a registered invoice

POST /i/v1/invoices/{id}/debit-notes

Requires invoice.create and invoice.submit. Adds lines to a registered invoice as a debit note and submits it; the charge is held and captured when it registers (released if the tax authority rejects it). Accepts an Idempotency-Key. With preview: true nothing is written or charged and the answer is 200 with the preview.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Field	Type	Required	Description
`reason`	string	No	At most 500 characters.
`lineItems`	array of InvoiceLineItem	Yes
`preview`	boolean	No	true: answer what would be issued; nothing is written or charged.

lineItems[]

Field	Type	Required	Description
`itemId`	string (uuid)	No	A saved item of the organisation: every field of the line left out is filled from the item, and a field sent wins.
`description`	string	No	Required without an itemId. 1 to 500 characters.
`itemName`	string	No	At most 255 characters.
`hsnCode`	string	No	HS code (goods).
`productCategory`	string	No	The HS description (goods). At most 500 characters.
`isicCode`	string	No	ISIC code (services); stored as the service code.
`serviceCategory`	string	No	The ISIC description (services). Stored as the line’s product category; send it or productCategory, not both. At most 500 characters.
`quantity`	string or number	Yes	Decimal string (≤ 6 decimals) or number; > 0.
`unitCode`	string	No	A unit code of the jurisdiction’s list. Required without an itemId.
`unitPrice`	string or number	No	Major units, decimal string (≤ 4 decimals) or number; ≥ 0. Required without an itemId.
`discountAmount`	string or number	No	Major units, ≤ 2 decimals.
`feeAmount`	string or number	No	Major units, ≤ 2 decimals.
`taxCategory`	string	No	A tax-category code-list id, or a short alias (standard \| zero \| exempt). Required without an itemId.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/debit-notes \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "Delivery charge omitted",
    "lineItems": [
      {
        "description": "Consulting services",
        "hsnCode": "1006.30",
        "isicCode": "0112",
        "quantity": "2.5",
        "unitCode": "EA",
        "unitPrice": "50000.00",
        "discountAmount": "0",
        "feeAmount": "0",
        "taxCategory": "STANDARD_VAT"
      }
    ]
  }'

Responses

With preview: true: what would be issued.

The original invoice as it now stands and the debit note just issued.

Download an invoice as a PDF

GET /i/v1/invoices/{id}/download

Content negotiation on Accept: application/pdf answers the PDF itself as an attachment; anything else (or no Accept) answers a short-lived download link in the JSON envelope. Never cached (Cache-Control: private, no-store, Vary: Accept).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes
`format`	query	string	No	Only `pdf` exists. One of `pdf`.

Example request

bash

curl https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/download \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The PDF (application/pdf), or a download link (application/json).

Errors: 400, 402, 404, 503

Finalise a draft invoice

POST /i/v1/invoices/{id}/finalise

Requires invoice.finalise. Freezes the seller and buyer onto the document; 422 VAL001 when the jurisdiction’s checks refuse it. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/finalise \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The finalised invoice.

Issue a draft invoice

POST /i/v1/invoices/{id}/issue

Requires invoice.finalise and invoice.submit. When the organisation is connected to NRS and reports automatically, the draft is finalised and submitted (202). Otherwise it is finalised and sent to the buyer without being reported (200, notReportedReason says why). Accepts an Idempotency-Key.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/issue \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Finalised and sent to the buyer, not reported.

Finalised and queued for reporting.

Record an invoice’s payment status

PATCH /i/v1/invoices/{id}/payment-status

Requires invoice.record_payment. Only for a document registered with the tax authority; the latest report is relayed to it. Not charged. amountPaidMinor moves only once the tax authority accepts the report (see payments).

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Field	Type	Required	Description
`status`	string	Yes	unpaid is local only (refused once anything was reported); payment_failed follows an accepted part or full payment. One of `unpaid` \| `partially_paid` \| `paid` \| `payment_failed`.
`amountMinor`	integer	No	Integer minor units; required for partially_paid: the TOTAL received to date (cumulative), not the installment.
`reference`	string	No	At most 100 characters.
`note`	string	No	At most 500 characters.

Example request

bash

curl -X PATCH https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/payment-status \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "unpaid"
  }'

Responses

The invoice.

Refresh an invoice’s status from the tax authority

POST /i/v1/invoices/{id}/query-status

Requires invoice.query_status; charged as one status query before the call and refunded when the tax authority is unavailable (503 SYS202, nothing changed). The answer only ever moves the status forward. An Idempotency-Key is bound to this invoice; reusing it for another invoice is 409 BIZ107.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/query-status \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Renumber an invoice and resubmit it

POST /i/v1/invoices/{id}/renumber

Requires invoice.submit. Only when the current submission is on hold because the tax authority already holds the invoice number: the invoice takes the next number of its series (the old one is kept on the withdrawn submission) and a new submission is queued with a new charge hold. Otherwise 409 BIZ004 says why. Accepts an Idempotency-Key; a repeated key answers 200 with replayed: true.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/renumber \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

A replay of an earlier request with the same key.

Renumbered and queued.

Reopen a finalised invoice as a draft

POST /i/v1/invoices/{id}/reopen

Requires invoice.reopen. Allowed while the current submission was rejected by the tax authority, or when the invoice was never submitted (then it is revised: same number, next version). If-Match is optional. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/reopen \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The draft.

Retry an invoice submission on hold

POST /i/v1/invoices/{id}/retry

Requires invoice.retry. Resumes the same submission that is on hold, with its existing charge hold.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/retry \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Revise an issued invoice that was never reported

POST /i/v1/invoices/{id}/revise

Requires invoice.reopen. An issued invoice never reported to the tax authority and unpaid goes back to a draft with the same number and the next version; otherwise 409 BIZ201 says what to do instead. If-Match is optional. The ETag header carries the invoice version.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/revise \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The draft.

Send an invoice to its buyer

POST /i/v1/invoices/{id}/send

invoice.send_to_buyer; charged per send (refunded if it cannot be recorded). Queues an email of a finalised invoice to the buyer email on the issued document (never an address from the request), with an optional message. 202 means accepted and queued, not delivered. In sandbox no email leaves: shareUrl links to the PDF for preview. A replayed Idempotency-Key answers the first result with replayed: true.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Request body

Field	Type	Required	Description
`message`	string	No	At most 1000 characters.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/send \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Please find our invoice attached."
  }'

Responses

The send was queued.

Errors: 400, 402, 404, 409, 503

GET /i/v1/invoices/{id}/share-links

invoice.share. Every link of the invoice, newest first, revoked and expired included (kept 90 days); url is always null here.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/share-links \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The links, newest first.

Errors: 400, 401, 403, 404, 429

POST /i/v1/invoices/{id}/share-links

invoice.share. A random, stored, revocable token; url is answered ONCE (only its sha256 is kept). expiresInSeconds 3600–2592000 (default 604800), maxViews 1–10000 (absent = unlimited). At most 20 live links per invoice. Emits the invoice.share_link.created event.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes

Request body

Field	Type	Required	Description
`expiresInSeconds`	number	No	Lifetime in seconds: 3600 (1 hour) to 2592000 (30 days); default 604800 (7 days). Between 3600 and 2592000.
`maxViews`	number	No	How many times the link may be opened (1 = open once); absent = unlimited. Between 1 and 10000.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/share-links \
  -H "Authorization: Bearer sk_test_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "expiresInSeconds": 604800,
    "maxViews": 1
  }'

Responses

The link, with its url — the one time the token is shown.

Errors: 400, 401, 403, 404, 409, 429

DELETE /i/v1/invoices/{id}/share-links/{linkId}

invoice.share. Immediate: the next resolve is 404. Idempotent (a revoked link answers 200 with its view). Emits the invoice.share_link.revoked event.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string (uuid)	Yes
`linkId`	path	string (uuid)	Yes

Example request

bash

curl -X DELETE https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/share-links/d8b2e4f6-9a3c-5b7d-0e1f-2a3b4c5d6e7f \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

The link, revoked.

Errors: 400, 401, 403, 404, 429

Get an invoice’s submission status

GET /i/v1/invoices/{id}/status

Requires invoice.read. The status as last recorded, with every submission; the tax authority is not called and nothing is charged.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes

Example request

bash

curl https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/status \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Submit an invoice to the tax authority

POST /i/v1/invoices/{id}/submit

Requires invoice.submit. Queues a submission of a finalised invoice; with finalise=true a draft is finalised and submitted in one step. Idempotent per invoice: while a submission is in flight the same one is answered with 200 and replayed: true. Accepts an Idempotency-Key.

Who can call it: API key or signed-in user.

Parameters

Name	In	Type	Required	Description
`id`	path	string	Yes
`finalise`	query	string	No	Finalise a draft and submit it in one step. One of `true` \| `false`.

Example request

bash

curl -X POST https://gp.useyona.com/i/v1/invoices/9f8e7d6c-5b4a-3210-fedc-ba9876543210/submit \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

A submission already in flight (replayed: true).

Queued.

Get the invoice settings

GET /i/v1/invoice-settings

Requires invoice.read. The organisation’s invoice settings in the token’s mode; the defaults (version 0) when they were never changed. The ETag header carries the version.

Who can call it: API key or signed-in user.

Example request

bash

curl https://gp.useyona.com/i/v1/invoice-settings \
  -H "Authorization: Bearer sk_test_your_key_here"

Responses

Update the invoice settings

PATCH /i/v1/invoice-settings

Users only, with tax_connection.connect. Turning reportAutomatically off needs a recent second-factor step-up (403 AUTH033 with a WWW-Authenticate challenge otherwise); turning it on does not. If-Match: "<version>" is optional ("0" while never changed); a stale version answers 409 RES003. The ETag header carries the new version.

Who can call it: Signed-in user only: do this in the Yona app.

Request body

Field	Type	Required	Description
`reportAutomatically`	boolean	Yes	On (the default): an organisation connected to NRS reports every invoice it issues. Off: issuing finalises the invoice and sends it to the buyer without reporting it; it can be submitted to NRS later.

Example request

bash

curl -X PATCH https://gp.useyona.com/i/v1/invoice-settings \
  -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "reportAutomatically": true
  }'

Responses

Invoices

List invoices

Create a draft invoice

Get an invoice

Update a draft invoice

Delete a draft invoice

Submit several invoices

List previously used HS or service codes

Create an invoice and submit it

Get the invoicing dashboard overview

Get the reference data for the invoice form

Get invoice statistics

Summarise the documents a list filter selects

Validate an invoice with the tax authority (dry run)

Get the tax authority’s copy of an invoice

Cancel an invoice

Issue a credit note against a registered invoice

Issue a debit note against a registered invoice

Download an invoice as a PDF

Finalise a draft invoice

Issue a draft invoice

Record an invoice’s payment status

Refresh an invoice’s status from the tax authority

Renumber an invoice and resubmit it

Reopen a finalised invoice as a draft

Retry an invoice submission on hold

Revise an issued invoice that was never reported

Send an invoice to its buyer

List an invoice’s share links

Create a share link to a finalised invoice

Revoke a share link

Get an invoice’s submission status

Submit an invoice to the tax authority

Get the invoice settings

Update the invoice settings