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)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.
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)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
A unique key per distinct operation (a UUID works), reused only when retrying that same request. Up to 255 characters; stored for 24 hours.
255"6f1c2d9e-8a4b-4c3f-9e7d-2b5a1c8f4e30"
Body
Full name or legal business name.
1"Acme Industries"
Billing email. POST /invoices/{id}/send delivers here unless you pass to. "" clears it.
^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$Phone number, free text.
Tax registration number (VAT, EIN, GSTIN…), free text — no format check.
Billing address. Every field is optional.
Show child attributes
Show child attributes
Response
The created customer.
The created customer.
Show child attributes
Show child attributes