Add an invoice item

cURL

curl https://invoice.horizonpay.co/api/v1/invoice-items \
  -H "Authorization: Bearer $INVOICE_AI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    "description": "Extra review round",
    "quantity": 1,
    "unit_amount": 10000
  }'

import InvoiceAI from '@horizonpay/invoice-ai'

const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY

// Retries reuse one Idempotency-Key; pass { idempotencyKey } to set your own.
const invoice = await invoiceai.invoiceItems.create({
  invoice: 'in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8',
  description: 'Extra review round',
  quantity: 1,
  unit_amount: 10000,
})
console.log(invoice.total)

from invoice_ai import InvoiceAI

client = InvoiceAI()  # reads INVOICE_AI_API_KEY

# Retries reuse one Idempotency-Key; pass idempotency_key=... to set your own.
invoice = client.invoice_items.create(
    invoice="in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    description="Extra review round",
    quantity=1,
    unit_amount=10000,
)
print(invoice.total)

{
  "data": {
    "id": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    "object": "invoice",
    "number": null,
    "status": "draft",
    "customer": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
    "currency": "USD",
    "collection_method": "send_invoice",
    "issue_date": "2026-09-22",
    "due_date": "2026-10-22",
    "description": "Consulting retainer.",
    "footer": null,
    "subtotal": 2560000,
    "discount": 0,
    "taxable": 2560000,
    "tax": 0,
    "total": 2560000,
    "amount_due": 0,
    "amount_in_words": "Twenty Five Thousand Six Hundred USD Only",
    "public_url_token": "2b7e4c1a-9f3d-4e68-8a5b-0d1c7f3e9a46",
    "finalized_at": null,
    "paid_at": null,
    "voided_at": null,
    "void_reason": null,
    "created": "2026-09-22T09:30:00.000Z",
    "updated": "2026-09-22T09:45:00.000Z",
    "lines": {
      "data": [
        {
          "id": "ii_Da4Vq9Ns2Kx7Bm3Yt8Rc1Lp6",
          "object": "invoiceitem",
          "price": "price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7",
          "product": "prod_Hy7Rq2Lm9Xc4Vb8Nt3Kd6Pw1",
          "description": "Consulting retainer",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 2500000,
          "amount": 2500000,
          "discount_percent": 0,
          "tax_rate": 0,
          "tax_amount": 0
        },
        {
          "id": "ii_Ew8Hz3Jc6Tq1Ms5Nv9Kb2Xr4",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "Onboarding workshop",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 50000,
          "amount": 50000,
          "discount_percent": 0,
          "tax_rate": 0,
          "tax_amount": 0
        },
        {
          "id": "ii_Gk2Rw7Lq4Zt9Xn1Vb6Mc3Hs8",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "Extra review round",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 10000,
          "amount": 10000,
          "discount_percent": 0,
          "tax_rate": 0,
          "tax_amount": 0
        }
      ]
    }
  }
}

POST

invoice-items

cURL

curl https://invoice.horizonpay.co/api/v1/invoice-items \
  -H "Authorization: Bearer $INVOICE_AI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    "description": "Extra review round",
    "quantity": 1,
    "unit_amount": 10000
  }'

import InvoiceAI from '@horizonpay/invoice-ai'

const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY

// Retries reuse one Idempotency-Key; pass { idempotencyKey } to set your own.
const invoice = await invoiceai.invoiceItems.create({
  invoice: 'in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8',
  description: 'Extra review round',
  quantity: 1,
  unit_amount: 10000,
})
console.log(invoice.total)

from invoice_ai import InvoiceAI

client = InvoiceAI()  # reads INVOICE_AI_API_KEY

# Retries reuse one Idempotency-Key; pass idempotency_key=... to set your own.
invoice = client.invoice_items.create(
    invoice="in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    description="Extra review round",
    quantity=1,
    unit_amount=10000,
)
print(invoice.total)

{
  "data": {
    "id": "in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8",
    "object": "invoice",
    "number": null,
    "status": "draft",
    "customer": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
    "currency": "USD",
    "collection_method": "send_invoice",
    "issue_date": "2026-09-22",
    "due_date": "2026-10-22",
    "description": "Consulting retainer.",
    "footer": null,
    "subtotal": 2560000,
    "discount": 0,
    "taxable": 2560000,
    "tax": 0,
    "total": 2560000,
    "amount_due": 0,
    "amount_in_words": "Twenty Five Thousand Six Hundred USD Only",
    "public_url_token": "2b7e4c1a-9f3d-4e68-8a5b-0d1c7f3e9a46",
    "finalized_at": null,
    "paid_at": null,
    "voided_at": null,
    "void_reason": null,
    "created": "2026-09-22T09:30:00.000Z",
    "updated": "2026-09-22T09:45:00.000Z",
    "lines": {
      "data": [
        {
          "id": "ii_Da4Vq9Ns2Kx7Bm3Yt8Rc1Lp6",
          "object": "invoiceitem",
          "price": "price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7",
          "product": "prod_Hy7Rq2Lm9Xc4Vb8Nt3Kd6Pw1",
          "description": "Consulting retainer",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 2500000,
          "amount": 2500000,
          "discount_percent": 0,
          "tax_rate": 0,
          "tax_amount": 0
        },
        {
          "id": "ii_Ew8Hz3Jc6Tq1Ms5Nv9Kb2Xr4",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "Onboarding workshop",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 50000,
          "amount": 50000,
          "discount_percent": 0,
          "tax_rate": 0,
          "tax_amount": 0
        },
        {
          "id": "ii_Gk2Rw7Lq4Zt9Xn1Vb6Mc3Hs8",
          "object": "invoiceitem",
          "price": null,
          "product": null,
          "description": "Extra review round",
          "quantity": 1,
          "unit": "NOS",
          "unit_amount": 10000,
          "amount": 10000,
          "discount_percent": 0,
          "tax_rate": 0,
          "tax_amount": 0
        }
      ]
    }
  }
}

Authorizations

Authorization

string

header

required

An Invoice-AI API key sent as Authorization: Bearer inv_live_….

Create keys in Settings → API keys; the secret is shown once. Each key carries scopes, and every operation lists the scope it needs (x-required-scope):

business:read — Read your business profile, tax ID and bank details
clients:read — List and read your clients
clients:write — Create, update and archive clients
products:read — List and read products and prices
products:write — Create, update and archive products and prices
invoices:read — List and read invoices, including PDFs
invoices:write — Create, edit and delete drafts
invoices:finalize — Finalize invoices and void them
invoices:send — Email invoices to your clients
payments:write — Mark invoices as paid
webhooks:manage — Manage webhook endpoints

Keys cannot be created or revoked through the API, so a leaked key cannot mint more keys.

Headers

Idempotency-Key

string

required

A unique key per distinct operation (a UUID works), reused only when retrying that same request. Up to 255 characters; stored for 24 hours.

Maximum string length: 255

Example:

"6f1c2d9e-8a4b-4c3f-9e7d-2b5a1c8f4e30"

Body

application/json

Either price, or description + unit_amount.

invoice

string

required

The draft to append to, in_… or UUID.

Minimum string length: 1

Example:

"in_Pb2Xk7Mv4Qs9Lr1Wd6Tn3Fh8"

price

string

A catalog price, price_… or UUID. Its product name, unit amount and tax rate fill any of description, unit_amount, tax_rate you omit. Its currency must match the invoice.

Example:

"price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7"

description

string

default:""

What you are billing for. Required unless price is given.

Example:

"Onboarding workshop"

quantity

number

default:1

Quantity, greater than zero. Defaults to 1.

Example:

1

unit

enum<string>

default:NOS

Unit of measure. Defaults to NOS (numbers).

Available options:

NOS,

PCS,

KGS,

GMS,

LTR,

MTR,

SQF,

SQM,

HRS,

DAY,

MON,

BOX,

SET,

OTH

Example:

"NOS"

unit_amount

integer

Price per unit in integer minor units of the invoice currency. Required unless price is given.

Required range: 0 <= x <= 9007199254740991

Example:

50000

discount_percent

number

default:0

Discount percentage, 0–100, applied before tax. Defaults to 0.

Required range: 0 <= x <= 100

Example:

0

tax_rate

number

Tax percentage, 0–100, added on top. Defaults to the price’s rate, or 0 on ad-hoc lines.

Required range: 0 <= x <= 100

Example:

0

Response

The whole draft, with the new line last.

data

object

required

The updated draft.

Show child attributes

Overview

Endpoints

Authorizations

Headers

Body

Response