Update a Draft Invoice — Invoice AI API Reference

Updates a draft invoice in place. All body fields are optional — only the keys you include are changed. Once an invoice has been finalized (status open, paid, overdue, or void), it is immutable: the customer may already have the PDF, and a silent edit would create a discrepancy. Attempting to PATCH a non-draft invoice returns a 409 invalid_state error. When you supply an items array, it replaces all existing line items on the invoice. Omit items entirely to leave the existing items untouched.

PATCH /api/v1/invoices/:id

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

Authentication

string

required

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

string

required

Must be application/json.

Path Parameters

string

required

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

Body Parameters

All fields are optional. Omitting a field leaves its current value unchanged.

string

Reassign the invoice to a different customer by their cus_… public ID or UUID.

string

Three-letter ISO 4217 currency code. Changing the currency clears any catalog-based lines whose price was denominated in the old currency.

string

"send_invoice" or "charge_automatically".

string

ISO 8601 date (YYYY-MM-DD).

string

ISO 8601 date (YYYY-MM-DD), or "" to clear the due date.

integer

Number of days from issue_date until payment is due (0–365). Ignored if due_date is also supplied.

string

Notes shown on the invoice body. Pass null to clear.

string

Footer text shown at the bottom of the invoice, typically used for payment terms. Pass null to clear.

array

Replaces all existing line items. Omit this field to keep the current items unchanged. The array must contain at least one item if supplied.

Show Line item fields

string

The price_… public ID of a catalog price. When set, description, unit_amount, and tax_rate may be omitted and are inherited from the price.

string

Description of the line. Required for ad-hoc lines (those without a price).

number

Number of units. Must be greater than zero. Defaults to 1.

string

Unit of measure. One of: NOS, PCS, KGS, GMS, LTR, MTR, SQF, SQM, HRS, DAY, MON, BOX, SET, OTH.

integer

Price per unit in integer minor units. Required for ad-hoc lines; inherited from the catalog price otherwise.

number

Percentage discount on this line (0–100). Defaults to 0.

number

Tax rate as a percentage (0–100). Defaults to 0 for ad-hoc lines.

Request Example

curl -X PATCH https://invoice.horizonpay.co/api/v1/invoices/in_01JABCDEFGHIJKLMNOPQRSTU01 \
  -H "Authorization: Bearer inv_live_sk_1234abcd5678efgh" \
  -H "Content-Type: application/json" \
  -d '{
    "due_date": "2025-07-15",
    "description": "Website redesign — Phase 2 (revised scope)",
    "items": [
      {
        "description": "UI/UX Design",
        "quantity": 48,
        "unit": "HRS",
        "unit_amount": 15000,
        "discount_percent": 0,
        "tax_rate": 18
      },
      {
        "description": "Frontend Development",
        "quantity": 24,
        "unit": "HRS",
        "unit_amount": 18000,
        "discount_percent": 0,
        "tax_rate": 18
      }
    ]
  }'

Response Example

{
  "data": {
    "id": "in_01JABCDEFGHIJKLMNOPQRSTU01",
    "object": "invoice",
    "number": null,
    "status": "draft",
    "customer": "cus_01J9ZXMQR7P4KBN2VWTF3D6H8A",
    "currency": "USD",
    "collection_method": "send_invoice",
    "issue_date": "2025-06-01",
    "due_date": "2025-07-15",
    "description": "Website redesign — Phase 2 (revised scope)",
    "footer": "Payment due within 30 days. Bank transfer preferred.",
    "subtotal": 1152000,
    "discount": 0,
    "taxable": 1152000,
    "tax": 207360,
    "total": 1359360,
    "amount_due": 0,
    "amount_in_words": null,
    "public_url_token": null,
    "finalized_at": null,
    "paid_at": null,
    "voided_at": null,
    "void_reason": null,
    "created": "2025-06-01T08:00:00.000Z",
    "updated": "2025-06-01T11:22:00.000Z",
    "lines": {
      "data": [
        {
          "id": "ii_01JABCDEFGHIJKLMNOPQRSTU04",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "UI/UX Design",
          "quantity": 48,
          "unit": "HRS",
          "unit_amount": 15000,
          "amount": 720000,
          "discount_percent": 0,
          "tax_rate": 18,
          "tax_amount": 129600
        },
        {
          "id": "ii_01JABCDEFGHIJKLMNOPQRSTU05",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "Frontend Development",
          "quantity": 24,
          "unit": "HRS",
          "unit_amount": 18000,
          "amount": 432000,
          "discount_percent": 0,
          "tax_rate": 18,
          "tax_amount": 77760
        }
      ]
    }
  }
}

PATCH is only allowed on draft invoices. Attempting to update an invoice with status open, paid, overdue, or void returns 409 invalid_state. Use POST /api/v1/invoices/:id/void to cancel an open invoice with an audit trail. There is no endpoint to modify a finalized invoice — issue a new one instead.

Supplying items in the body fully replaces all line items — there is no way to add, remove, or update individual lines via PATCH. To keep existing lines, read them first with GET /api/v1/invoices/:id, modify the array in your client, and send the complete updated array.

Response Fields

string

Unique public identifier for the invoice, prefixed in_.

string

Always "invoice".

null

Still null — the invoice remains a draft until finalized.

string

Always "draft" after a successful PATCH, confirming the invoice was editable.

string

ISO 8601 datetime of this update.

object

The complete, updated set of line items after the PATCH is applied.

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 `invoices:write` scope.
`404`	`not_found`	No invoice with that ID exists, or it belongs to a different account.
`409`	`invalid_state`	Invoice is not a draft. Finalized, paid, overdue, and voided invoices are immutable.
`422`	`validation`	Request body failed validation. The `errors` array lists each failing field path.
`429`	`rate_limited`	Per-credential rate limit exceeded. Check the `Retry-After` response header.

Overview

Invoices

Customers & Catalog

Webhooks

Update a Draft Invoice — 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