curl https://invoice.horizonpay.co/api/v1/invoices/in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8/void \
-H "Authorization: Bearer $INVOICE_AI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "reason": "Raised against the wrong customer." }'import InvoiceAI from '@horizonpay/invoice-ai'
const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY
// Retries reuse one Idempotency-Key; pass { idempotencyKey } to set your own.
const invoice = await invoiceai.invoices.void('in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8', {
reason: 'Raised against the wrong customer.',
})
console.log(invoice.status, invoice.void_reason)from invoice_ai import InvoiceAI
client = InvoiceAI() # reads INVOICE_AI_API_KEY
# Retries reuse one Idempotency-Key; pass idempotency_key=... to set your own.
invoice = client.invoices.void(
"in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
reason="Raised against the wrong customer.",
)
print(invoice.status, invoice.void_reason){
"data": {
"id": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
"object": "invoice",
"number": "INV-0042",
"status": "void",
"customer": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
"currency": "USD",
"collection_method": "send_invoice",
"issue_date": "2026-09-22",
"due_date": "2026-10-22",
"description": "Consulting retainer.",
"footer": null,
"subtotal": 2550000,
"discount": 0,
"taxable": 2550000,
"tax": 0,
"total": 2550000,
"amount_due": 0,
"amount_in_words": "Twenty Five Thousand Five Hundred USD Only",
"public_url_token": "2b7e4c1a-9f3d-4e68-8a5b-0d1c7f3e9a46",
"finalized_at": "2026-09-22T10:00:00.000Z",
"paid_at": null,
"voided_at": "2026-09-29T14:20:00.000Z",
"void_reason": "Raised against the wrong customer.",
"created": "2026-09-22T09:30:00.000Z",
"updated": "2026-09-29T14:20:00.000Z"
}
}Void an invoice
Voids an open (or overdue) invoice. reason is required, up to 500 characters. The number stays on record, so the series has no gaps. A paid invoice cannot be voided (it needs a credit note) and a draft should be deleted instead — both 409. The response omits lines. Emits invoice.voided.
Scope: invoices:finalize
Idempotency: Idempotency-Key required (428 without it). A retry with the same key and body replays the first response (Idempotent-Replayed: true); the same key with a different body is a 422 idempotency_mismatch.
curl https://invoice.horizonpay.co/api/v1/invoices/in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8/void \
-H "Authorization: Bearer $INVOICE_AI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{ "reason": "Raised against the wrong customer." }'import InvoiceAI from '@horizonpay/invoice-ai'
const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY
// Retries reuse one Idempotency-Key; pass { idempotencyKey } to set your own.
const invoice = await invoiceai.invoices.void('in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8', {
reason: 'Raised against the wrong customer.',
})
console.log(invoice.status, invoice.void_reason)from invoice_ai import InvoiceAI
client = InvoiceAI() # reads INVOICE_AI_API_KEY
# Retries reuse one Idempotency-Key; pass idempotency_key=... to set your own.
invoice = client.invoices.void(
"in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
reason="Raised against the wrong customer.",
)
print(invoice.status, invoice.void_reason){
"data": {
"id": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
"object": "invoice",
"number": "INV-0042",
"status": "void",
"customer": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
"currency": "USD",
"collection_method": "send_invoice",
"issue_date": "2026-09-22",
"due_date": "2026-10-22",
"description": "Consulting retainer.",
"footer": null,
"subtotal": 2550000,
"discount": 0,
"taxable": 2550000,
"tax": 0,
"total": 2550000,
"amount_due": 0,
"amount_in_words": "Twenty Five Thousand Five Hundred USD Only",
"public_url_token": "2b7e4c1a-9f3d-4e68-8a5b-0d1c7f3e9a46",
"finalized_at": "2026-09-22T10:00:00.000Z",
"paid_at": null,
"voided_at": "2026-09-29T14:20:00.000Z",
"void_reason": "Raised against the wrong customer.",
"created": "2026-09-22T09:30:00.000Z",
"updated": "2026-09-29T14:20:00.000Z"
}
}Authorizations
An Invoice-AI API key sent as Authorization: Bearer inv_live_….
Create keys in Settings → API keys; the secret is shown once. Each key carries scopes, and every operation lists the scope it needs (x-required-scope):
business:read— Read your business profile, tax ID and bank detailsclients:read— List and read your clientsclients:write— Create, update and archive clientsproducts:read— List and read products and pricesproducts:write— Create, update and archive products and pricesinvoices:read— List and read invoices, including PDFsinvoices:write— Create, edit and delete draftsinvoices:finalize— Finalize invoices and void theminvoices:send— Email invoices to your clientspayments:write— Mark invoices as paidwebhooks:manage— Manage webhook endpoints
Keys cannot be created or revoked through the API, so a leaked key cannot mint more keys.
Headers
A unique key per distinct operation (a UUID works), reused only when retrying that same request. Up to 255 characters; stored for 24 hours.
255"6f1c2d9e-8a4b-4c3f-9e7d-2b5a1c8f4e30"
Path Parameters
The invoice, in_… or UUID.
"in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8"
Body
Why the invoice is void: required, non-blank, up to 500 characters. Stored as void_reason.
1"Raised against the wrong customer."
Response
The voided invoice (without lines).
The voided invoice.
Show child attributes
Show child attributes