Generate Receipt

POST/v1/receipt

Generate a professional receipt PDF for completed payments.

Headers

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

Request Body

json

{
  "receipt_number": "REC-001",
  "date": "2026-02-26",
  "currency": "USD",
  "from": {
    "name": "Acme Corporation",
    "email": "billing@acme.com",
    "address": "123 Main Street\nBaku, Azerbaijan"
  },
  "to": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "items": [
    {
      "description": "Pro Plan - Monthly",
      "quantity": 1,
      "unit_price": 29.99
    }
  ],
  "tax": { "rate": 18 },
  "payment_method": "Visa ending in 4242",
  "payment_date": "2026-02-26",
  "transaction_id": "txn_abc123xyz",
  "notes": "Thank you for your purchase!"
}

Fields

Field	Type	Required	Description
`receipt_number`	string	Yes	Unique receipt identifier
`date`	string	Yes	Date of the receipt
`currency`	string	Yes	Currency code (e.g. 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	No	Customer details
`to.name`	string	No	Customer name
`to.email`	string	No	Customer email
`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[].tax`	object	No	Item-level tax. Overrides receipt-level tax for this item
`items[].tax.rate`	number	No	Item-level tax percentage
`tax`	object	No	Receipt-level tax applied to items without item-level tax
`tax.rate`	number	No	Tax percentage (default: 0)
`payment_method`	string	No	Payment method used (e.g. Visa ending in 4242)
`payment_date`	string	No	Date payment was made
`transaction_id`	string	No	Transaction reference ID
`notes`	string	No	Additional notes

Response

Success (200)

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

Errors

Status	Body
`400`	`{ "error": "receipt_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 items[].tax — that rate is used
2. If an item has no items[].tax — the receipt-level tax is used
3. If neither is set — no tax (0%)

Item-level tax overrides receipt-level tax for that item.

Mixed Tax Rates Example

json

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

Item	Tax Rate	Reason
Electronics	20%	Uses item-level tax
Software	10%	Falls back to receipt-level tax
Exempt Service	0%	Uses item-level tax (explicitly 0)

Example

bash

curl -X POST https://api.kagyz.com/v1/receipt \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "receipt_number": "REC-001",
    "date": "2026-02-26",
    "currency": "USD",
    "from": {
      "name": "Acme Corporation",
      "email": "billing@acme.com",
      "address": "123 Main Street\nBaku, Azerbaijan"
    },
    "to": {
      "name": "John Doe",
      "email": "john@example.com"
    },
    "items": [
      {
        "description": "Pro Plan - Monthly",
        "quantity": 1,
        "unit_price": 29.99
      }
    ],
    "tax": { "rate": 18 },
    "payment_method": "Visa ending in 4242",
    "payment_date": "2026-02-26",
    "transaction_id": "txn_abc123xyz",
    "notes": "Thank you for your purchase!"
  }' \
  --output receipt.pdf