Create a New Draft Invoice — Invoice AI REST API

Create a new draft invoice with line items. Drafts have no invoice number and can be freely edited or deleted before you finalize them.

Creates a new invoice in draft status. A draft does not yet have an invoice number (number is null), is not visible to your customer, and can be modified or deleted at any time. To make the invoice official and send it to the customer, call POST /api/v1/invoices/:id/finalize after creation.

Line items can be ad-hoc (supply description and unit_amount directly) or catalog-based (supply a price ID to inherit description, rate, and tax rate from a saved price).

POST /api/v1/invoices

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.

Idempotency-Key · string · required

A unique key (UUID or any string up to 255 characters) you generate per logical create operation. If the request is retried with the same key, the original response is replayed and no second draft is created. The replayed response includes the header Idempotent-Replayed: true.

Content-Type · string · required

Must be application/json.

---

Body Parameters

customer · string · required

The cus_… public ID (or UUID) of an existing customer to attach to this invoice. The customer’s address and contact details are snapshotted onto the invoice when it is finalized.

currency · string

Three-letter ISO 4217 currency code (e.g. "USD", "EUR", "INR"). Defaults to your account’s configured currency. All unit_amount values in items must be expressed in the minor units of this currency.

collection_method · string

How you intend to collect payment. One of "send_invoice" (default) or "charge_automatically".

issue_date · string

ISO 8601 date the invoice is issued (YYYY-MM-DD). Defaults to today if omitted.

due_date · string

ISO 8601 date payment is due (YYYY-MM-DD). Pass an empty string "" to clear a previously set date.

days_until_due · integer

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

description · string

Notes displayed on the invoice body. Pass null or omit to leave blank.

footer · string

Footer text shown at the bottom of the invoice, typically used for payment terms. Pass null or omit to leave blank.

items · array

One or more line items to add to the invoice. At least one line item is required. Each element is an object with the fields below.

Show Line item fields

items[].price · string

The price_… public ID of a catalog price. When supplied, description, unit_amount, and tax_rate are inherited from the price and its parent product — you do not need to repeat them. The price’s currency must match the invoice currency.

items[].description · string · required

What you are billing for. Required for ad-hoc lines (those without a price). Optional when price is provided — the product name is used as the fallback.

items[].quantity · number

Number of units billed. 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. Defaults to NOS.

items[].unit_amount · integer · required

Price per unit in integer minor units (e.g. 5000 = $50.00 USD). Required for ad-hoc lines. Omit when price is supplied — the price’s unit_amount is used instead.

items[].discount_percent · number

Percentage discount applied to 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. Inherited from the catalog price when price is supplied.

---

Request Example

curl -X POST https://invoice.horizonpay.co/api/v1/invoices \
  -H "Authorization: Bearer inv_live_sk_1234abcd5678efgh" \
  -H "Idempotency-Key: 018e4c70-3f2a-7b8d-9c12-a1b2c3d4e5f6" \
  -H "Content-Type: application/json" \
  -d '{
    "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.",
    "items": [
      {
        "description": "UI/UX Design",
        "quantity": 40,
        "unit": "HRS",
        "unit_amount": 15000,
        "discount_percent": 0,
        "tax_rate": 18
      },
      {
        "price": "price_01J9ZXMQR7P4KBN2VWTF3D6HXX",
        "quantity": 1,
        "discount_percent": 10
      }
    ]
  }'

---

Response Example

HTTP 201 Created

{
  "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-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": 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-01T08:00:00.000Z",
    "lines": {
      "data": [
        {
          "id": "ii_01JABCDEFGHIJKLMNOPQRSTU02",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "UI/UX Design",
          "quantity": 40,
          "unit": "HRS",
          "unit_amount": 15000,
          "amount": 600000,
          "discount_percent": 0,
          "tax_rate": 18,
          "tax_amount": 108000
        },
        {
          "id": "ii_01JABCDEFGHIJKLMNOPQRSTU03",
          "object": "invoiceitem",
          "price": "price_01J9ZXMQR7P4KBN2VWTF3D6HXX",
          "product": "prod_01J9ZXMQR7P4KBN2VWTF3D6HYY",
          "description": "Domain Registration (1 year)",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 10000,
          "amount": 10000,
          "discount_percent": 10,
          "tax_rate": 0,
          "tax_amount": 0
        }
      ]
    }
  }
}

number is always null on a newly created invoice. An invoice number is permanently assigned only when you call POST /api/v1/invoices/:id/finalize. This means you can create and discard drafts without gaps in your invoice number series.

Always send an Idempotency-Key. A network timeout after the server commits but before the response reaches you would, without a key, leave you unable to tell whether the invoice was created. On retry without a key, a second identical draft is created — you then cannot determine which one to finalize, and finalizing both burns two invoice numbers. Use a UUID generated once per logical operation.

---

Response Fields

data.id · string

Unique public identifier for the new invoice, prefixed in_.

data.object · string

Always "invoice".

data.number · null

Always null for a newly created draft. Assigned on finalization.

data.status · string

Always "draft" on creation.

data.customer · string

The cus_… public ID of the attached customer.

data.currency · string

Three-letter ISO 4217 currency code.

data.subtotal · integer

Sum of all line.amount values before tax, in minor units.

data.discount · integer

Total discount amount across all lines, in minor units.

data.taxable · integer

Taxable base amount (subtotal minus discount), in minor units.

data.tax · integer

Total tax amount, in minor units.

data.total · integer

Grand total (taxable + tax), in minor units.

data.amount_due · integer

Always 0 for a draft — no payment is owed until the invoice is finalized.

data.lines · object

Object containing a data array of the invoice’s line items, each with its computed amounts.

data.lines.data[].id · string

Unique identifier for the line item, prefixed ii_.

data.lines.data[].object · string

Always "invoiceitem".

data.lines.data[].price · string | null

The price_… ID of the catalog price, or null for ad-hoc lines.

data.lines.data[].product · string | null

The prod_… ID of the parent product, or null for ad-hoc lines.

data.lines.data[].unit_amount · integer

Price per unit in minor units.

data.lines.data[].amount · integer

Line total (quantity × unit_amount, after discount), in minor units.

data.lines.data[].tax_amount · integer

Tax charged on this line, in minor units.

---

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	The customer ID does not exist or does not belong to your account.
422	validation	Request body failed validation. The errors array lists each failing field path.
428	idempotency_key_required	Idempotency-Key header was not sent.
429	rate_limited	Per-credential rate limit exceeded. Check the Retry-After response header.