cURL

curl https://invoice.horizonpay.co/api/v1/invoices/in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8/pay \
  -H "Authorization: Bearer $INVOICE_AI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "paid_on": "2026-09-29", "reference": "chk_123456" }'

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.pay('in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8', {
  paid_on: '2026-09-29',
  reference: 'chk_123456',
})
console.log(invoice.status, invoice.paid_at)

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.pay(
    "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    paid_on="2026-09-29",
    reference="chk_123456",
)
print(invoice.status, invoice.paid_at)

{
  "data": {
    "id": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    "object": "invoice",
    "number": "INV-0042",
    "status": "paid",
    "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": "2026-09-29T14:20:00.000Z",
    "voided_at": null,
    "void_reason": null,
    "created": "2026-09-22T09:30:00.000Z",
    "updated": "2026-09-29T14:20:00.000Z"
  }
}

Invoices

Mark an invoice paid

Marks an open (or overdue) invoice paid outside Invoice-AI — no money moves. paid_on is an ISO 8601 date or timestamp (defaults to now); reference is up to 200 characters. Drafts, void and already-paid invoices return 409. The response omits lines. Emits invoice.paid, with reference in its meta.

Scope: payments:write

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.

POST

invoices

{id}

pay

cURL

curl https://invoice.horizonpay.co/api/v1/invoices/in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8/pay \
  -H "Authorization: Bearer $INVOICE_AI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ "paid_on": "2026-09-29", "reference": "chk_123456" }'

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.pay('in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8', {
  paid_on: '2026-09-29',
  reference: 'chk_123456',
})
console.log(invoice.status, invoice.paid_at)

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.pay(
    "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    paid_on="2026-09-29",
    reference="chk_123456",
)
print(invoice.status, invoice.paid_at)

{
  "data": {
    "id": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    "object": "invoice",
    "number": "INV-0042",
    "status": "paid",
    "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": "2026-09-29T14:20:00.000Z",
    "voided_at": null,
    "void_reason": null,
    "created": "2026-09-22T09:30:00.000Z",
    "updated": "2026-09-29T14:20:00.000Z"
  }
}

Authorizations

Authorization

string

header

required

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 details
clients:read — List and read your clients
clients:write — Create, update and archive clients
products:read — List and read products and prices
products:write — Create, update and archive products and prices
invoices:read — List and read invoices, including PDFs
invoices:write — Create, edit and delete drafts
invoices:finalize — Finalize invoices and void them
invoices:send — Email invoices to your clients
payments:write — Mark invoices as paid
webhooks:manage — Manage webhook endpoints

Keys cannot be created or revoked through the API, so a leaked key cannot mint more keys.

Headers

Idempotency-Key

string

required

A unique key per distinct operation (a UUID works), reused only when retrying that same request. Up to 255 characters; stored for 24 hours.

Maximum string length: 255

Example:

"6f1c2d9e-8a4b-4c3f-9e7d-2b5a1c8f4e30"

Path Parameters

string

required

The invoice, in_… or UUID.

Example:

"in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8"

Body

application/json

paid_on

string

When payment was received: an ISO 8601 date or timestamp. Defaults to now.

Example:

"2026-09-29"

reference

string

Your payment reference (cheque number, bank transfer id), up to 200 characters. Recorded on the invoice.paid event.

Example:

"chk_123456"

Response

The paid invoice (without lines).

data

object

required

The paid invoice.

Show child attributes

Overview

Endpoints

Mark an invoice paid

Authorizations

Headers

Path Parameters

Body

Response