Mark an Invoice as Paid — Invoice AI API Reference

Record an out-of-band payment against an open or overdue invoice, setting its status to paid and triggering the invoice.paid webhook event.

Marks an open or overdue invoice as paid. This is an out-of-band payment recording endpoint: it does not initiate a charge or move funds. Use it to reflect a payment that was received externally — via bank transfer, cheque, cash, or a payment processor outside of Invoice AI.

On success the invoice’s status moves to "paid", paid_at is set to the current server time (or to the paid_on date you supply), and amount_due drops to 0. The invoice.paid webhook event fires after the response is committed.

POST /api/v1/invoices/:id/pay

Base URL: https://invoice.horizonpay.co

---

Authentication

Authorization · string · required

Bearer token in the form Bearer inv_live_…. The token must carry the payments:write scope.

Idempotency-Key · string · required

A unique key (UUID or any string up to 255 characters) you generate per logical pay operation. This endpoint requires the header — the request is rejected with 428 if it is absent.

Content-Type · string

application/json. Required when sending a body; may be omitted if the body is empty.

---

Path Parameters

id · string · required

The invoice’s public ID (in_…) or its UUID. The invoice must be in open or overdue status.

---

Body Parameters

The request body is optional. If omitted, the invoice is marked paid at the current server time with no reference.

paid_on · string

ISO 8601 date the payment was received (YYYY-MM-DD). Defaults to today if omitted. Stored in paid_at.

reference · string

Free-text payment reference (e.g. a bank transaction ID, cheque number, or payment processor charge ID). Stored for your records only — not exposed on the invoice PDF.

---

Request Example

curl -X POST https://invoice.horizonpay.co/api/v1/invoices/in_01JABCDEFGHIJKLMNOPQRSTU01/pay \
  -H "Authorization: Bearer inv_live_sk_1234abcd5678efgh" \
  -H "Idempotency-Key: 018e4c70-3f2a-7b8d-9c12-c3d4e5f60234" \
  -H "Content-Type: application/json" \
  -d '{
    "paid_on": "2025-06-28",
    "reference": "WIRE-2025-06-28-00113"
  }'

---

Response Example

{
  "data": {
    "id": "in_01JABCDEFGHIJKLMNOPQRSTU01",
    "object": "invoice",
    "number": "INV/25-26/0042",
    "status": "paid",
    "customer": "cus_01J9ZXMQR7P4KBN2VWTF3D6H8A",
    "currency": "USD",
    "collection_method": "send_invoice",
    "issue_date": "2025-06-01",
    "due_date": "2025-07-01",
    "description": "Website redesign — Phase 2",
    "footer": "Payment due within 30 days. Bank transfer preferred.",
    "subtotal": 700000,
    "discount": 50000,
    "taxable": 650000,
    "tax": 108000,
    "total": 758000,
    "amount_due": 0,
    "amount_in_words": "Seven thousand five hundred and eighty dollars",
    "public_url_token": "tok_share_a1b2c3d4e5f6",
    "finalized_at": "2025-06-01T09:00:00.000Z",
    "paid_at": "2025-06-28T00:00:00.000Z",
    "voided_at": null,
    "void_reason": null,
    "created": "2025-06-01T08:00:00.000Z",
    "updated": "2025-06-28T14:05:33.000Z"
  }
}

Idempotency-Key is required on this endpoint. Recording a payment is not idempotent by default: a duplicate call without a key on an already-paid invoice returns 409 invalid_state, but a race between two retries can trigger two invoice.paid webhook deliveries and any downstream logic that depends on them (e.g. releasing a digital product, updating accounting software). Always generate a fresh UUID per pay operation and retain it for retries.

The response does not include the lines field. If you need line item detail alongside the payment confirmation, follow this call with GET /api/v1/invoices/:id.

A paid invoice cannot be voided. In accounting, reversing a paid invoice requires a credit note — a separate document with its own numbering. Credit notes are out of scope for v1 of this API.

---

Response Fields

data.id · string

Unique public identifier for the invoice, prefixed in_.

data.object · string

Always "invoice".

data.number · string

The invoice number, unchanged from when it was finalized.

data.status · string

"paid" after a successful pay operation.

data.amount_due · integer

Always 0 after the invoice is paid.

data.paid_at · string

ISO 8601 datetime the payment was recorded. Reflects the paid_on date if you supplied one, otherwise the server timestamp at the time of the API call.

data.total · integer

The full invoice total in minor units. Unchanged by the pay operation.

For all other fields, see the Retrieve Invoice response fields.

---

Error Codes

HTTP Status	code	Meaning
401	unauthorized	Missing or invalid Authorization header.
403	forbidden	Token does not carry the payments:write scope.
404	not_found	No invoice with that ID exists, or it belongs to a different account.
409	invalid_state	Invoice is not in open or overdue status — it may be a draft, already paid, or voided.
428	idempotency_key_required	Idempotency-Key header was not sent.
429	rate_limited	Per-credential rate limit exceeded. Check the Retry-After response header.