Generate Invoice

POST/v1/invoice

Generate a professionally formatted PDF invoice.

Headers

Header	Value	Required
`Authorization`	Bearer YOUR_API_KEY	Yes
`Content-Type`	application/json	Yes

Request Body

json

{
  "invoice_number": "INV-001",
  "issue_date": "Feb 18, 2026",
  "due_date": "Mar 18, 2026",
  "currency": "USD",
  "from": {
    "name": "Your Company",
    "email": "billing@company.com",
    "address": "123 Business St, City, Country"
  },
  "to": {
    "name": "Client Name",
    "email": "client@example.com",
    "address": "456 Client Ave, City, Country"
  },
  "items": [
    {
      "description": "Web Development",
      "quantity": 40,
      "unit_price": 150,
      "item_tax_rate": 20
    },
    {
      "description": "Design Services",
      "quantity": 10,
      "unit_price": 200
    }
  ],
  "invoice_tax_rate": 10,
  "notes": "Payment due within 30 days. Thank you for your business!"
}

Fields

Field	Type	Required	Description
`invoice_number`	string	Yes	Unique invoice identifier
`issue_date`	string	Yes	Date invoice was issued
`due_date`	string	No	Payment due date
`currency`	string	No	Currency code (default: USD)
`from`	object	Yes	Your company details
`from.name`	string	Yes	Company name
`from.email`	string	No	Company email
`from.address`	string	No	Company address
`to`	object	Yes	Client details
`to.name`	string	Yes	Client name
`to.email`	string	No	Client email
`to.address`	string	No	Client address
`items`	array	Yes	Line items (min 1)
`items[].description`	string	Yes	Item description
`items[].quantity`	number	Yes	Quantity
`items[].unit_price`	number	Yes	Price per unit
`items[].item_tax_rate`	number	No	Item-level tax %. Overrides invoice_tax_rate for this item
`invoice_tax_rate`	number	No	Invoice-level tax % applied to items without item_tax_rate (default: 0). Also accepts tax_rate as alias
`notes`	string	No	Additional notes

Response

Success (200)

Content-Type: application/pdf
Body: PDF binary data

Errors

Status	Body
`400`	`{ "error": "invoice_number is required" }`
`401`	`{ "error": "Invalid API key" }`
`429`	`{ "error": "Monthly limit reached. Please upgrade." }`

Tax Rates

Kagyz supports flexible tax calculation with fallback logic:

1. If an item has item_tax_rate — that rate is used
2. If an item has no item_tax_rate — invoice_tax_rate is used
3. If neither is set — no tax (0%)

Mixed Tax Rates Example

json

{
  "invoice_tax_rate": 10,
  "items": [
    { "description": "Electronics", "quantity": 1, "unit_price": 1000, "item_tax_rate": 20 },
    { "description": "Software", "quantity": 1, "unit_price": 500 },
    { "description": "Exempt Service", "quantity": 1, "unit_price": 300, "item_tax_rate": 0 }
  ]
}

Item	Tax Rate	Reason
Electronics	20%	Uses item_tax_rate
Software	10%	Falls back to invoice_tax_rate
Exempt Service	0%	Uses item_tax_rate (explicitly 0)

For backward compatibility, tax_rate is accepted as an alias for invoice_tax_rate.

Example

bash

curl -X POST https://api.kagyz.com/v1/invoice \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "invoice_number": "INV-001",
    "issue_date": "Feb 18, 2026",
    "from": { "name": "Acme Inc" },
    "to": { "name": "Client Corp" },
    "items": [{ "description": "Services", "quantity": 1, "unit_price": 500 }]
  }' \
  --output invoice.pdf