Credit Note

POST/v1/credit-note

Issue professional credit notes and refund documents as PDF with a single API call.

Headers

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

Request Body

json

{
  "credit_note_number": "CN-001",
  "date": "2026-03-09",
  "currency": "USD",
  "invoice_number": "INV-045",
  "reason": "Goods returned — defective items",
  "from": {
    "name": "Acme Digital Agency",
    "email": "billing@acme.agency",
    "address": "123 Creative Blvd\nSan Francisco, CA 94102"
  },
  "to": {
    "name": "TechStart Inc.",
    "email": "accounts@techstart.io",
    "address": "456 Innovation Drive\nAustin, TX 73301"
  },
  "items": [
    {
      "description": "Website Redesign — UX Phase (returned scope)",
      "quantity": 1,
      "unit_price": 3500
    },
    {
      "description": "Unused design assets",
      "quantity": 5,
      "unit_price": 200,
      "tax": { "rate": 10 }
    }
  ],
  "tax": { "rate": 8.25 },
  "notes": "This credit references INV-045. Amount will be applied to your next invoice."
}

Fields

Field	Type	Required	Description
`credit_note_number`	string	Yes	Unique credit note identifier (e.g. "CN-001")
`date`	string	Yes	Issue date (e.g. "2026-03-09")
`currency`	string	Yes	Currency code (e.g. "USD", "EUR", "AZN")
`from`	object	Yes	Your company info
`from.name`	string	Yes	Company name
`from.email`	string	No	Company email
`from.address`	string	No	Company address
`items`	array	Yes	Credited line items (at least 1)
`items[].description`	string	Yes	Item description
`items[].quantity`	number	Yes	Quantity (must be > 0)
`items[].unit_price`	number	Yes	Unit price (must be >= 0)
`items[].tax`	object	No	Item-level tax
`items[].tax.rate`	number	No	Tax rate % for this item
`invoice_number`	string	No	Reference to the original invoice (e.g. "INV-045")
`reason`	string	No	Reason for credit (e.g. "Goods returned", "Overcharge correction")
`to`	object	No	Client info
`to.name`	string	No	Client name
`to.email`	string	No	Client email
`to.address`	string	No	Client address
`tax`	object	No	Invoice-level tax
`tax.rate`	number	No	Tax rate % applied to all items
`direction`	string	No	Text direction: "ltr" (default) or "rtl" for Arabic/Hebrew
`language`	string	No	Language hint: "ar", "he", "fa", etc. Optional metadata
`notes`	string	No	Additional notes

Full Example

bash

curl -X POST https://api.kagyz.com/v1/credit-note \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credit_note_number": "CN-001",
    "date": "2026-03-09",
    "currency": "USD",
    "invoice_number": "INV-045",
    "reason": "Goods returned — defective items",
    "from": {
      "name": "Acme Digital Agency",
      "email": "billing@acme.agency",
      "address": "123 Creative Blvd\nSan Francisco, CA 94102"
    },
    "to": {
      "name": "TechStart Inc.",
      "email": "accounts@techstart.io",
      "address": "456 Innovation Drive\nAustin, TX 73301"
    },
    "items": [
      {
        "description": "Website Redesign — UX Phase (returned scope)",
        "quantity": 1,
        "unit_price": 3500
      },
      {
        "description": "Unused design assets",
        "quantity": 5,
        "unit_price": 200,
        "tax": { "rate": 10 }
      }
    ],
    "tax": { "rate": 8.25 },
    "notes": "This credit references INV-045. Amount will be applied to your next invoice."
  }' \
  --output credit-note.pdf

javascript

const response = await fetch('https://api.kagyz.com/v1/credit-note', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    credit_note_number: 'CN-001',
    date: '2026-03-09',
    currency: 'USD',
    invoice_number: 'INV-045',
    reason: 'Goods returned — defective items',
    from: {
      name: 'Acme Digital Agency',
      email: 'billing@acme.agency',
      address: '123 Creative Blvd\nSan Francisco, CA 94102'
    },
    to: {
      name: 'TechStart Inc.',
      email: 'accounts@techstart.io'
    },
    items: [
      { description: 'Website Redesign — UX Phase (returned scope)', quantity: 1, unit_price: 3500 },
      { description: 'Unused design assets', quantity: 5, unit_price: 200, tax: { rate: 10 } }
    ],
    tax: { rate: 8.25 },
    notes: 'This credit references INV-045. Amount will be applied to your next invoice.'
  })
});

const blob = await response.blob();
// Save or send the PDF

Invoice Reference

If you provide invoice_number, the credit note PDF will display it as a reference linking back to the original invoice. This is recommended for audit trails and proper accounting.

json

{
  "invoice_number": "INV-045",
  "credit_note_number": "CN-001",
  "date": "2026-03-09",
  "currency": "USD",
  "from": { "name": "Acme Corp" },
  "items": [
    { "description": "Refunded item", "quantity": 1, "unit_price": 500 }
  ]
}

The reference appears on the PDF as “Reference: INV-045”.

Reason

The reason field lets you specify why the credit note was issued. Common reasons include:

Goods returned
Overcharge correction
Order cancelled
Pricing error
Duplicate payment

json

{
  "reason": "Goods returned — defective items",
  "credit_note_number": "CN-001",
  "date": "2026-03-09",
  "currency": "USD",
  "from": { "name": "Acme Corp" },
  "items": [
    { "description": "Refunded item", "quantity": 1, "unit_price": 500 }
  ]
}

Minimal Example

Only required fields — no invoice reference, no reason, no tax, no client details:

bash

curl -X POST https://api.kagyz.com/v1/credit-note \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "credit_note_number": "CN-002",
    "date": "2026-03-09",
    "currency": "USD",
    "from": { "name": "Quick Services" },
    "items": [
      { "description": "Service credit", "quantity": 1, "unit_price": 150 }
    ]
  }' \
  --output credit-note.pdf

Tax Rates

Tax works the same as Invoice, Receipt, and Quote:

1. If an item has items[].tax — that rate is used
2. If an item has no items[].tax — the credit note-level tax is used
3. If neither is set — no tax (0%)

Item-level tax overrides credit note-level tax for that item.

Mixed Tax Rates Example

json

{
  "tax": { "rate": 10 },
  "items": [
    { "description": "Returned hardware", "quantity": 1, "unit_price": 3000, "tax": { "rate": 20 } },
    { "description": "Service credit", "quantity": 1, "unit_price": 800 },
    { "description": "Exempt adjustment", "quantity": 1, "unit_price": 500, "tax": { "rate": 0 } }
  ]
}

Item	Tax Rate	Reason
Returned hardware	20%	Uses item-level tax
Service credit	10%	Falls back to credit note-level tax
Exempt adjustment	0%	Uses item-level tax (explicitly 0)

Response

Success (200)

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

Errors

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

All Five Endpoints

Document	Endpoint	Key Fields
Invoice	`POST /v1/invoice`	`invoice_number`, `issue_date`, `due_date`
Receipt	`POST /v1/receipt`	`receipt_number`, `date`, `payment_method`, `transaction_id`
Quote	`POST /v1/quote`	`quote_number`, `date`, `expiry_date`, `title`
Credit Note	`POST /v1/credit-note`	`credit_note_number`, `date`, `invoice_number`, `reason`
Packing Slip	`POST /v1/packing-slip`	`packing_slip_number`, `date`, `order_number`, `shipping_method`, `tracking_number`

Credit notes reference original invoices. See the Invoice API docs →

Send this document via email → See Email Delivery

Supports Arabic & RTL → See docs

Every generated PDF is automatically stored and gets a shareable URL. Check the X-Kagyz-Document-URL response header. Learn more →