AlphaBill API

REST API for invoice automation • v1.0

Authentication
Current Key / Merchant
Invoices
Clients
Products
Statistics
Error Handling
Examples

🔑 Authentication

All API requests require an API key. Pass it via one of these methods:

Method	Example
Header (recommended)	`X-API-Key: your_key_here`
Bearer token	`Authorization: Bearer your_key_here`
Query parameter	`?api_key=your_key_here`

Base URL: https://api.alphabill.hu

Merchant Scoping: Each API key is tied to a specific merchant. You can only access invoices, clients, products, and statistics belonging to that merchant. If you have multiple merchants, create separate API keys for each. Manage your keys in Settings → API Keys.

🏪 Current Key / Merchant

API Key Info

GET /me

Returns information about the current API key, its owner, and associated merchant.

📄 Invoices

List Invoices

GET /invoices

Query parameters:

Param	Type	Description
`status`	string	optional Filter: draft, sent, paid, overdue, cancelled
`client_id`	int	optional Filter by client ID
`from`	date	optional Issue date from (YYYY-MM-DD)
`to`	date	optional Issue date to (YYYY-MM-DD)
`limit`	int	optional Max results (default 50, max 200)
`offset`	int	optional Pagination offset

Get Invoice

GET /invoices/{id}

Returns full invoice details including line items, share URL, and PDF URL.

Create Invoice

POST /invoices

Create a new invoice. Totals, tax amounts, and HUF conversions are calculated automatically.

Field	Type	Description
`client_id`	int	required* Existing client ID
`buyer_name`	string	required* Buyer name (alternative to client_id)
`buyer_company`	string	optional Override buyer company
`buyer_email`	string	optional Override buyer email
`buyer_address`	string	optional Override buyer address
`buyer_country`	string	optional Override buyer country
`buyer_city`	string	optional Override buyer city
`buyer_zipcode`	string	optional Override buyer zipcode
`buyer_tax`	string	optional Override buyer tax number
`items`	array	required Array of line items (see below)
`issue_date`	date	optional Default: today
`fulfillment_date`	date	optional Default: issue_date
`due_date`	date	optional Default: +30 days
`currency`	string	optional EUR, USD, GBP, HUF (default from settings)
`huf_rate`	float	optional Override HUF exchange rate (auto-fetched if omitted)
`payment_method`	string	optional Default from settings
`status`	string	optional draft (default), sent, or paid
`notes`	string	optional Invoice notes/comments

Line item fields:

Field	Type	Description
`description`	string	required* Item description (on invoice)
`product_id`	int	required* Load from product (fills defaults)
`quantity`	float	optional Default: 1 (or product default)
`unit_price`	float	optional Default: 0 (or product price)
`tax_rate`	float	optional Default: 27% (or product rate)
`comment`	string	optional Additional notes for this item

Note: Each item needs either description or product_id. When using product_id, the product's name, price, quantity, tax rate, and comment are used as defaults — you can still override any of them.

Update Invoice Status

PUT /invoices/{id}/status

Field	Type	Description
`status`	string	required draft, sent, paid, or cancelled

Setting to paid auto-records a payment. Setting to sent generates the PDF.

Download Invoice PDF

GET /invoices/{id}/pdf

Returns the PDF binary. Generates it on-the-fly if missing.

👥 Clients

List Clients

GET /clients

Param	Type	Description
`search`	string	optional Search in name, company, email
`limit`	int	optional Default 100, max 500
`offset`	int	optional Pagination offset

Get Client

GET /clients/{id}

Create Client

POST /clients

Field	Type	Description
`name`	string	required Client name
`company`	string	optional
`email`	string	optional
`phone`	string	optional
`address`	string	optional
`country`	string	optional
`city`	string	optional
`zipcode`	string	optional
`tax_number`	string	optional
`notes`	string	optional

📦 Products

List Products

GET /products

Param	Type	Description
`active`	int	optional Filter: 1 = active only, 0 = inactive only

Get Product

GET /products/{id}

📊 Statistics

GET /stats

Param	Type	Description
`year`	int	optional Default: current year

Returns total invoices, total clients, revenue by status, and payment totals.

⚠️ Error Handling

All errors return a consistent JSON format:

{
  "error": true,
  "message": "Description of what went wrong",
  "code": 422,
  "details": ["Field-level errors if applicable"]
}

Code	Meaning
`401`	Missing or invalid API key
`404`	Resource not found
`422`	Validation error (check details array)
`500`	Server error

🚀 Examples

Create an invoice from products

curl -X POST https://api.alphabill.hu/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "client_id": 1,
    "status": "sent",
    "items": [
      {"product_id": 1, "quantity": 2},
      {"product_id": 3}
    ]
  }'

Create an invoice with custom items

curl -X POST https://api.alphabill.hu/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "client_id": 1,
    "issue_date": "2026-03-25",
    "due_date": "2026-04-25",
    "currency": "EUR",
    "payment_method": "Átutalás",
    "status": "draft",
    "notes": "Thank you for your business",
    "items": [
      {
        "description": "Web Development - March 2026",
        "quantity": 1,
        "unit_price": 2500.00,
        "tax_rate": 27,
        "comment": "Frontend + backend work"
      },
      {
        "description": "Hosting",
        "quantity": 1,
        "unit_price": 50.00,
        "tax_rate": 27
      }
    ]
  }'

Create invoice for a new buyer (no client record)

curl -X POST https://api.alphabill.hu/invoices \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "buyer_name": "John Doe",
    "buyer_company": "ACME Corp",
    "buyer_address": "123 Main St",
    "buyer_city": "Budapest",
    "buyer_country": "Hungary",
    "buyer_tax": "12345678-1-42",
    "items": [
      {"description": "Consulting", "quantity": 10, "unit_price": 100, "tax_rate": 27}
    ]
  }'

Mark invoice as paid

curl -X PUT https://api.alphabill.hu/invoices/5/status \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"status": "paid"}'

List unpaid invoices

curl https://api.alphabill.hu/invoices?status=sent \
  -H "X-API-Key: YOUR_API_KEY"

Create a client

curl -X POST https://api.alphabill.hu/clients \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{
    "name": "Jane Smith",
    "company": "Smith & Co",
    "email": "jane@smith.co",
    "address": "456 Oak Ave",
    "city": "Vienna",
    "country": "Austria",
    "tax_number": "ATU12345678"
  }'

Download invoice PDF

curl https://api.alphabill.hu/invoices/5/pdf \
  -H "X-API-Key: YOUR_API_KEY" \
  -o invoice.pdf

AlphaBill API v1.0 • Back to Dashboard