Quickstart
Create a key, mirror a customer and issue an invoice — in five minutes.
There is no test mode yet
An issued invoice is a real bookkeeping document: it has a number, a booking and, with send, reaches the
customer. It cannot be deleted, only cancelled. Try the API in a company you set up for testing — a second company
in your organization is enough.
Create a key
As an admin of your organization, open AlphaCount → Integrations → Connect AI assistants (MCP) → New access.
- Permissions: Choose individually, then
partner:customers:write,partner:invoices:writeandpartner:invoices:read. - Legal entities: Selected entities only, and exactly one company — the one the invoices are for.
Copy the key. It starts with ab_ and is shown only this once.
export ALPHACOUNT_API_KEY=ab_...Mirror a customer
Customers are kept by your own reference: source names your product, external_ref is your id for the customer.
Sending the same request again changes nothing.
curl -X PUT https://app.alphacount.ai/api/partner/v1/customers/by-ref/myapp/cust-42 \
-H "Authorization: Bearer $ALPHACOUNT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Musterschule gGmbH",
"email": "billing@musterschule.example",
"street": "Schulweg",
"house_number": "7a",
"zip": "50667",
"city": "Köln",
"country_code": "DE",
"customer_type": "business"
}'The answer is 201 with the customer and the customer number AlphaCount gave it.
Issue an invoice
issue: true gives the invoice its number, books it and renders the PDF. Leave out send for now; with
"send": true it would also be mailed to the customer.
curl -X POST https://app.alphacount.ai/api/partner/v1/invoices \
-H "Authorization: Bearer $ALPHACOUNT_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"customer": { "source": "myapp", "external_ref": "cust-42" },
"external_ref": "order-1001",
"lines": [
{ "description": "Licence, October 2026", "quantity": 1, "unit": "Monat",
"unit_price_net": "1000.00", "vat_rate": 19 }
],
"service_period": { "start": "2026-10-01", "end": "2026-10-31" },
"issue": true
}'The answer is 201 with the invoice: its number, status: "issued", the totals as decimal strings and the due
date. If the company's or customer's details are not complete enough for a valid invoice, the answer is 422 invoice_not_issuable with the reasons — and nothing was created.
Fetch the PDF
curl https://app.alphacount.ai/api/partner/v1/invoices/<id>/pdf \
-H "Authorization: Bearer $ALPHACOUNT_API_KEY" -o invoice.pdfLearn when it is paid
Set up a webhook for invoice.paid (Integrations → Webhooks → New webhook). When the payment shows up on
the bank statement, AlphaCount books it and calls your URL — see Webhooks.
Next
- Bill your customers from your product — sending, cancelling, keeping in sync.
- Contracts and usage — recurring billing per cycle.
- Errors — every code and what to do about it.