Update a Draft Invoice — Invoice AI API Reference

Partially update a draft invoice’s header fields and line items. Only draft invoices can be modified; sending PATCH to a finalized invoice returns 409.

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

Authorization · string · required

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

Content-Type · string · required

Must be application/json.

---

Path Parameters

id · 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.

customer · string

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

currency · string

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

collection_method · string

"send_invoice" or "charge_automatically".

issue_date · string

ISO 8601 date (YYYY-MM-DD).

due_date · string

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

days_until_due · integer

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

description · string

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

footer · string

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

items · 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

items[].price · 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.

items[].description · string

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

items[].quantity · number

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

items[].unit · string

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

items[].unit_amount · integer

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

items[].discount_percent · number

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

items[].tax_rate · 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

data.id · string

Unique public identifier for the invoice, prefixed in_.

data.object · string

Always "invoice".

data.number · null

Still null — the invoice remains a draft until finalized.

data.status · string

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

data.updated · string

ISO 8601 datetime of this update.

data.lines · 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.