Katixo/API DocumentationBeta

Purchase Bills

Record purchase bills from vendors, track payables, and manage the bill lifecycle from draft to posted. Purchase bills automatically create journal entries and update inventory when posted.

Endpoints

GET/api/v1/bills

GET/api/v1/bills/{id}

POST/api/v1/bills

PUT/api/v1/bills/{id}

POST/api/v1/bills/{id}/post

POST/api/v1/bills/{id}/void

GET/api/v1/bills/{id}/pdf

DELETE/api/v1/bills/{id}

List purchase bills

GET/api/v1/bills

Returns a paginated list of purchase bills with optional filters.

Query parameters

Parameter	Type	Description
`status`	string	Filter by bill status (DRAFT, POSTED, VOIDED).
`contact_id`	UUID	Filter by vendor contact.
`date_from`	date	Bill date on or after (YYYY-MM-DD).
`date_to`	date	Bill date on or before.
`page`, `size`, `sort`	int / string	Pagination (0-indexed, default size: 20).

Roles: OWNER, ADMIN, ACCOUNTANT, VIEWER.

Create a purchase bill

POST/api/v1/bills

Creates a new purchase bill in DRAFT status. Returns 201 Created.

curl -X POST https://api.katixo.com/api/v1/bills \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "vendorBillNumber": "VB-2026-0142",
    "billDate": "2026-06-10",
    "dueDate": "2026-07-10",
    "placeOfSupply": "27",
    "lines": [
      {
        "description": "Toor Dal 1kg",
        "hsnCode": "07139090",
        "itemId": "550e8400-e29b-41d4-a716-446655440000",
        "quantity": 100,
        "unitPrice": 110.00,
        "gstRate": 5.00
      },
      {
        "description": "Basmati Rice 5kg",
        "hsnCode": "10063020",
        "itemId": "661f9500-f3ac-52e5-b827-557766551111",
        "quantity": 50,
        "unitPrice": 220.00,
        "gstRate": 5.00
      }
    ],
    "notes": "Monthly stock purchase"
  }'

Request body

Field	Type	Required	Description
`contactId`	UUID	Yes	Vendor contact ID.
`billDate`	date	Yes	Date of the bill (YYYY-MM-DD).
`lines`	array	Yes	At least one line item required.
`vendorBillNumber`	string	No	Vendor's own bill/invoice number.
`dueDate`	date	No	Payment due date.
`placeOfSupply`	string	No	2-digit state code for GST calculation.
`reverseCharge`	boolean	No	Whether reverse charge is applicable.

Post a bill

POST/api/v1/bills/{id}/post

Finalizes a draft bill — creates accounting journal entries, updates vendor payable balance, and (if items are linked) adjusts inventory quantities. A posted bill cannot be edited; use void instead.

Void a bill

POST/api/v1/bills/{id}/void

Voids a posted bill. Reverses the journal entry and inventory changes. Optionally pass a reason in the request body.

curl -X POST https://api.katixo.com/api/v1/bills/{id}/void \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Duplicate entry" }'

The PurchaseBill object

{
  "id": "c3d4e5f6-a7b8-9012-3456-789abcdef012",
  "contactId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "vendorName": "Sharma Wholesale",
  "billNumber": "BILL-2026-0087",
  "vendorBillNumber": "VB-2026-0142",
  "billDate": "2026-06-10",
  "dueDate": "2026-07-10",
  "status": "POSTED",
  "subtotal": 22000.00,
  "taxAmount": 1100.00,
  "totalAmount": 23100.00,
  "amountPaid": 0.00,
  "balanceDue": 23100.00,
  "tdsAmount": 0.00,
  "currency": "INR",
  "placeOfSupply": "27",
  "reverseCharge": false,
  "notes": "Monthly stock purchase",
  "lines": [
    {
      "id": "f1e2d3c4-b5a6-9876-5432-10fedcba9876",
      "lineNumber": 1,
      "description": "Toor Dal 1kg",
      "hsnCode": "07139090",
      "itemId": "550e8400-e29b-41d4-a716-446655440000",
      "quantity": 100,
      "unitPrice": 110.00,
      "discountPercent": 0.00,
      "discountAmount": 0.00,
      "taxableAmount": 11000.00,
      "gstRate": 5.00,
      "taxAmount": 550.00,
      "lineTotal": 11550.00
    }
  ],
  "createdAt": "2026-06-10T09:30:00Z"
}

Authorization

Create, update, post, void, and delete operations require OWNER, ADMIN, or ACCOUNTANT role. Read operations (list, get, PDF) additionally allow VIEWER and OPERATOR.