cURL

curl https://invoice.horizonpay.co/api/v1/invoices \
  -H "Authorization: Bearer $INVOICE_AI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
    "currency": "USD",
    "due_date": "2026-10-22",
    "description": "Consulting retainer.",
    "items": [
      { "price": "price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7", "quantity": 1 },
      {
        "description": "Onboarding workshop",
        "quantity": 1,
        "unit": "NOS",
        "unit_amount": 50000,
        "tax_rate": 0
      }
    ]
  }'

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.invoices.create({
  customer: 'cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6',
  currency: 'USD',
  due_date: '2026-10-22',
  description: 'Consulting retainer.',
  items: [
    { price: 'price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7', quantity: 1 },
    {
      description: 'Onboarding workshop',
      quantity: 1,
      unit: 'NOS',
      unit_amount: 50000,
      tax_rate: 0,
    },
  ],
})
console.log(invoice.id, invoice.status)

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.invoices.create(
    customer="cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
    currency="USD",
    due_date="2026-10-22",
    description="Consulting retainer.",
    items=[
        {"price": "price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7", "quantity": 1},
        {
            "description": "Onboarding workshop",
            "quantity": 1,
            "unit": "NOS",
            "unit_amount": 50000,
            "tax_rate": 0,
        },
    ],
)
print(invoice.id, invoice.status)

{
  "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": 2550000,
    "discount": 0,
    "taxable": 2550000,
    "tax": 0,
    "total": 2550000,
    "amount_due": 0,
    "amount_in_words": "Twenty Five Thousand Five 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:30: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
        }
      ]
    }
  }
}

Invoices

Create a draft invoice

Creates a draft invoice for an existing customer. Each line is either a catalog price (its name, amount and tax rate fill in) or an ad-hoc description + unit_amount. Totals are computed server-side; currency defaults to your business currency.

A draft has no number until you finalize or send it. Emits invoice.created.

Scope: invoices:write + business:read + clients:read

Idempotency: Idempotency-Key required (428 without it). A retry with the same key and body replays the first response (Idempotent-Replayed: true); the same key with a different body is a 422 idempotency_mismatch.

POST

invoices

cURL

curl https://invoice.horizonpay.co/api/v1/invoices \
  -H "Authorization: Bearer $INVOICE_AI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
    "currency": "USD",
    "due_date": "2026-10-22",
    "description": "Consulting retainer.",
    "items": [
      { "price": "price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7", "quantity": 1 },
      {
        "description": "Onboarding workshop",
        "quantity": 1,
        "unit": "NOS",
        "unit_amount": 50000,
        "tax_rate": 0
      }
    ]
  }'

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.invoices.create({
  customer: 'cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6',
  currency: 'USD',
  due_date: '2026-10-22',
  description: 'Consulting retainer.',
  items: [
    { price: 'price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7', quantity: 1 },
    {
      description: 'Onboarding workshop',
      quantity: 1,
      unit: 'NOS',
      unit_amount: 50000,
      tax_rate: 0,
    },
  ],
})
console.log(invoice.id, invoice.status)

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.invoices.create(
    customer="cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
    currency="USD",
    due_date="2026-10-22",
    description="Consulting retainer.",
    items=[
        {"price": "price_Jc5Tn8Wq1Ze6Ra3Ym9Ub2Gs7", "quantity": 1},
        {
            "description": "Onboarding workshop",
            "quantity": 1,
            "unit": "NOS",
            "unit_amount": 50000,
            "tax_rate": 0,
        },
    ],
)
print(invoice.id, invoice.status)

{
  "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": 2550000,
    "discount": 0,
    "taxable": 2550000,
    "tax": 0,
    "total": 2550000,
    "amount_due": 0,
    "amount_in_words": "Twenty Five Thousand Five 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:30: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
        }
      ]
    }
  }
}

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

customer

string

required

The customer to bill, cus_… or UUID. Must already exist (POST /customers).

Minimum string length: 1

Example:

"cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6"

currency

string

ISO 4217 code. Defaults to your business currency.

Required string length: 3

Pattern: ^[A-Z]{3}$

Example:

"USD"

collection_method

enum<string>

Defaults to send_invoice. Informational today.

Available options:

charge_automatically,

send_invoice

Example:

"send_invoice"

due_date

Due date, YYYY-MM-DD. "" clears it.

Pattern:

^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$

Example:

"2026-10-22"

days_until_due

integer

Alternative to due_date on create only: issue date + N days (0–365). Ignored on update.

Required range: 0 <= x <= 365

Example:

30

description

string

Notes printed on the invoice.

footer

string

Terms printed at the foot of the invoice.

items

object[]

The lines, at least one. On update, replaces every existing line; omit to keep them.

Minimum array length: 1

Show child attributes

Response

The created draft, with lines.

data

object

required

The created draft.

Show child attributes

Overview

Endpoints

Create a draft invoice

Authorizations

Headers

Body

Response