cURL
curl https://invoice.horizonpay.co/api/v1/customers \
-H "Authorization: Bearer $INVOICE_AI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Industries",
"tax_id": "US-EIN 12-3456789",
"email": "[email protected]",
"address": {
"line1": "4th Floor, Market Tower",
"city": "Austin",
"state": "TX",
"postal_code": "73301",
"country": "US"
}
}'import InvoiceAI from '@horizonpay/invoice-ai'
const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY
const customer = await invoiceai.customers.create({
name: 'Acme Industries',
tax_id: 'US-EIN 12-3456789',
email: '[email protected]',
address: {
line1: '4th Floor, Market Tower',
city: 'Austin',
state: 'TX',
postal_code: '73301',
country: 'US',
},
})
console.log(customer.id)from invoice_ai import InvoiceAI
client = InvoiceAI() # reads INVOICE_AI_API_KEY
customer = client.customers.create(
name="Acme Industries",
tax_id="US-EIN 12-3456789",
email="[email protected]",
address={
"line1": "4th Floor, Market Tower",
"city": "Austin",
"state": "TX",
"postal_code": "73301",
"country": "US",
},
)
print(customer.id){
"data": {
"id": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
"object": "customer",
"name": "Acme Industries",
"email": "[email protected]",
"phone": null,
"tax_id": "US-EIN 12-3456789",
"address": {
"line1": "4th Floor, Market Tower",
"line2": null,
"city": "Austin",
"state": "TX",
"postal_code": "73301",
"country": "US"
},
"deleted": false,
"created": "2026-09-22T09:30:00.000Z"
}
}Customers
Create a customer
Creates a customer to bill. Only name is required. Calls are not deduplicated: the same name twice makes two customers.
Scope: clients:write
Idempotency: Idempotency-Key optional. With one, 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
/
customers
cURL
curl https://invoice.horizonpay.co/api/v1/customers \
-H "Authorization: Bearer $INVOICE_AI_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Industries",
"tax_id": "US-EIN 12-3456789",
"email": "[email protected]",
"address": {
"line1": "4th Floor, Market Tower",
"city": "Austin",
"state": "TX",
"postal_code": "73301",
"country": "US"
}
}'import InvoiceAI from '@horizonpay/invoice-ai'
const invoiceai = new InvoiceAI() // reads INVOICE_AI_API_KEY
const customer = await invoiceai.customers.create({
name: 'Acme Industries',
tax_id: 'US-EIN 12-3456789',
email: '[email protected]',
address: {
line1: '4th Floor, Market Tower',
city: 'Austin',
state: 'TX',
postal_code: '73301',
country: 'US',
},
})
console.log(customer.id)from invoice_ai import InvoiceAI
client = InvoiceAI() # reads INVOICE_AI_API_KEY
customer = client.customers.create(
name="Acme Industries",
tax_id="US-EIN 12-3456789",
email="[email protected]",
address={
"line1": "4th Floor, Market Tower",
"city": "Austin",
"state": "TX",
"postal_code": "73301",
"country": "US",
},
)
print(customer.id){
"data": {
"id": "cus_Nf3kQ8pR2mX7vB1cT9wL4sZ6",
"object": "customer",
"name": "Acme Industries",
"email": "[email protected]",
"phone": null,
"tax_id": "US-EIN 12-3456789",
"address": {
"line1": "4th Floor, Market Tower",
"line2": null,
"city": "Austin",
"state": "TX",
"postal_code": "73301",
"country": "US"
},
"deleted": false,
"created": "2026-09-22T09:30:00.000Z"
}
}Authorizations
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 detailsclients:read— List and read your clientsclients:write— Create, update and archive clientsproducts:read— List and read products and pricesproducts:write— Create, update and archive products and pricesinvoices:read— List and read invoices, including PDFsinvoices:write— Create, edit and delete draftsinvoices:finalize— Finalize invoices and void theminvoices:send— Email invoices to your clientspayments:write— Mark invoices as paidwebhooks:manage— Manage webhook endpoints
Keys cannot be created or revoked through the API, so a leaked key cannot mint more keys.
Headers
Body
application/json
Billing email. POST /invoices/{id}/send delivers here unless you pass to. "" clears it.
Pattern:
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Example: