What is the Kigo Cloud API

The Kigo Cloud API is a programming interface (REST, JSON format) that lets external systems connect to your Kigo Cloud account. It is most often used by webshops and other business software for automatic data exchange: synchronizing items and stock, transferring clients, and creating and fiscalizing invoices directly from orders, without manual retyping.

Basic information

You can also reach the interactive documentation from the application: Options → Integrations → API Documentation.

Authentication

Every call sends two headers:

• X-USERNAME: the username you use to sign in to Kigo Cloud.
• X-PASSWORD: the password of the same user as an MD5 hash (32 characters), never as plain text.

The user account must be active. Example call that fetches the item list:

curl -H "X-USERNAME: your-username" -H "X-PASSWORD: md5-hash-of-password" https://app.kigo.cloud/en/api/v1/item/list

All available calls

Item groups

Items

Clients

Invoices and offers

Payment methods and statuses

Creating an invoice through the API

The most important call for webshops is POST invoice/create. Key fields:

• pin: PIN of an active employee; the document gets that operator. Mandatory.
• pos_type: 1 invoice, 2 offer (default), 3 service offer, 4 purchase offer. For a real invoice always send 1.
• payment: G cash, T bank transfer (default), K card, O other. For card also send id_payment_card, for other id_payment_other: the IDs come from paymentCard/list and paymentOther/list, an unknown ID returns an error. Cash, card and other are marked as paid immediately; a bank-transfer invoice stays unpaid until you record the payment. Only documents with T can later be sent as an eInvoice.
• items: invoice lines, at most 200 per document. The item is looked up by reference; when no reference is sent, by name (item_name). When nothing is found, a new item is created automatically in your item list: with the sent or an assigned reference, the VAT from vat_percent or 25%, and the general group. The same reference sent twice adds up the quantities on one line. All prices are sent with VAT included; without a sent price the retail price of the item applies. item_name on an existing item changes the label only on that invoice line, not in the item list.
• Discounts: when you send discount_percent, exactly that percentage applies (0 means no discount). When you send no discount but the sent price is lower than the retail price of the item, the difference is automatically shown as a discount on the invoice. A price of 0 makes the line free of charge (100% discount). With apply_client_discounts, lines still without a discount get the client discount, or the item group discount when the client has none.
• client: processed only when it contains oib; the buyer is matched by it, and if none exists it is created automatically from the sent data (name, address, contact, e-mail). Without it the invoice is issued without a buyer, which is fine for a retail B2C invoice. A new buyer is a company by default; the client_vat_type field changes that: 0 company, 1 private person, 2 public institution, 3 EU company, 4 company outside the EU. The buyer type determines fiscalization of bank-transfer invoices, see f1 and F2 below.
• internal_number: the order number from your system. Unique per document type: if a document with the same number already exists, the API returns error 400 and creates no duplicate. Retrying a call after a connection failure is therefore safe.

Example 1: retail cash invoice (f1), no buyer. Fiscalized immediately (jir and zki in the response), marked as paid and entered into the cash register:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "G",
  "items": [ { "reference": "ART-001", "quantity": 2 } ]
}

Example 2: bank-transfer invoice to a company (F2, eInvoice). No jir/zki in the response, the invoice stays unpaid until you record the payment, and on the issued invoices list it waits to be sent as an eInvoice. The example sends no client_vat_type, so the new buyer is saved as a company (default value 0), and that is exactly why the invoice goes as F2; for a private person you would send client_vat_type 1 and the invoice would be f1. The VAT number in the example passes the checksum: with an invalid one the buyer would be saved as a private person and the invoice would also go as f1, with fiscalization:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "T",
  "internal_number": "WEB-1001",
  "due_date": "2026-09-15",
  "client": { "oib": "12345678903", "company_name": "Company Ltd", "street": "Ilica", "house_number": "1", "city": "Zagreb", "zip": "10000" },
  "items": [ { "reference": "ART-001", "quantity": 2, "price": 25.00 } ]
}

Example 3: per-line discounts. The first line gets exactly 10%, the second gets a discount computed from the lowered price against the item retail price, the third is free of charge (100%), and the fourth, with nothing sent, gets the item group discount because apply_client_discounts is enabled; when the invoice also has a buyer with a discount, the buyer discount takes priority over the group one:

{
  "pin": "1234",
  "pos_type": 1,
  "payment": "G",
  "apply_client_discounts": true,
  "items": [
    { "reference": "ART-001", "quantity": 1, "discount_percent": 10 },
    { "reference": "ART-002", "quantity": 1, "price": 80.00 },
    { "reference": "ART-003", "quantity": 1, "price": 0 },
    { "reference": "ART-004", "quantity": 1 }
  ]
}

The result of this request, assuming the items have a retail price of 100.00 (ART-003 50.00) and the group of ART-004 has a 5% discount:

• ART-001: exactly 10% discount, 90.00 is charged.
• ART-002: sent price 80.00 against a retail price of 100.00, so a 20% discount is automatically shown on the line and 80.00 is charged.
• ART-003: price 0 makes the line free of charge: 100% discount, 0.00 is charged.
• ART-004: nothing sent, so apply_client_discounts applies the 5% group discount and 95.00 is charged.

The response: the data field contains id_pos, pos_number, the amounts (price, tax_pdv), payment method and status, and the fiscal data jir and zki with a QR code link (qrcode_link). A filled jir field means the invoice was fiscalized successfully.

PDF and sending to the buyer: the response contains no ready PDF URL. Fetch the PDF with a separate call GET invoice/getAsPdf/{id}, where {id} is the id_pos value from the response (not pos_number); the response of that call is the PDF file itself. The API does not e-mail the invoice to the buyer (the email from the client block is only stored on the client record), so your system sends the invoice to the buyer using the fetched PDF.

Fiscalization: which invoice is f1, which F2, and which NF

Every invoice (pos_type 1) automatically receives a fiscalization mark at closing, based on the payment method and the buyer type; offers are never fiscalized. The same marks appear on the issued invoices list.

• f1 (classic fiscalization): invoices paid by cash, card or other methods, regardless of the buyer, plus bank-transfer invoices issued to a private person or without a buyer. The invoice is fiscalized immediately and receives a ZKI and JIR: the zki and jir fields in the response are filled. This requires a fiscal certificate loaded in the application.
• F2 (Fiscalization 2.0, eInvoice obligation): a bank-transfer invoice (payment T) issued to a domestic company or public institution with a valid VAT number. It receives no JIR at issue time (jir and zki stay empty in the response); instead it is sent as an eInvoice: on the issued invoices list it carries the F2 mark, red until the eInvoice is sent, green after sending.
• NF (not fiscalized): an invoice subject to neither, for example a bank-transfer invoice to a foreign company, or a cash invoice whose lines are all under reverse charge.

Cancelling an invoice

The call POST invoice/cancel with the employee pin and id_pos (document ID) creates a cancellation document, the same as cancelling in the application, and returns it in the response. The original invoice then moves to status 3 (cancelled), the new cancellation document carries status 2, and the stock taken by the original invoice is returned.

Limits and errors

Lists are paginated, by default 200 records per page; choose the page and size with the page and pageSize parameters. The number of calls per minute per user is limited by your plan: Starter 5, Standard 15, Business 30, Premium 60. Above that, list calls return error 429; wait a minute and continue.

Trying out calls

In the interactive documentation every call can be tried with the Try it out button: pick your address from the server dropdown, enter the headers and parameters and immediately see the real response.

Need help?

If you have questions about connecting, or a call you need is missing, contact us at [email protected].