Mark an Invoice as Paid — Invoice AI API Reference

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

string

required

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

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.

string

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

Path Parameters

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.

string

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

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

string

Unique public identifier for the invoice, prefixed in_.

string

Always "invoice".

string

The invoice number, unchanged from when it was finalized.

string

"paid" after a successful pay operation.

integer

Always 0 after the invoice is paid.

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.

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.

Overview

Invoices

Customers & Catalog

Webhooks

Mark an Invoice as Paid — Invoice AI API Reference

Authentication

Path Parameters

Body Parameters

Request Example

Response Example

Response Fields

Error Codes

​Authentication

​Path Parameters

​Body Parameters

​Request Example

​Response Example

​Response Fields

​Error Codes

Authentication

Path Parameters

Body Parameters

Request Example

Response Example

Response Fields

Error Codes