API reference

Events

Events about final states of invoices and corrections. Webhooks deliver the same objects; the list is for reconciling when something did not arrive.

GET/v1/events
GET/v1/events/{id}

The Event object

An event about a document reaching its final state. Webhooks deliver the same objects that /v1/events lists.

Attributes

idstringrequired
Event id (the same as the KSeF-Event-Id header).
Prefix evt_
objectstringrequired
Object type.
Always event
typestringrequired
Event type. Types
One of: invoice.accepted, invoice.rejected, invoice.skipped, correction.accepted, correction.rejected, correction.skipped
livemodebooleanrequired
The document's mode.
createdintegerrequired
When the event happened (Unix seconds).
dataobjectrequired
Event data.
Show fields
- objectInvoice | Correctionrequired
  The invoice or correction as it was at the time of the event.

Object Event

{
  "id": "evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8",
  "object": "event",
  "type": "invoice.accepted",
  "livemode": false,
  "created": 1760865214,
  "data": {
    "object": {
      "id": "inv_4fJ2kP9xQwErTy7uI0oPaSdF",
      "object": "invoice",
      "livemode": false,
      "status": "accepted",
      "order": {
        "external_id": "SO-1001",
        "number": "1001"
      },
      "number": "FV/2026/10/1",
      "ksef_number": "4235405606-20261019-0E7570400000-57",
      "ksef_environment": "test",
      "issue_date": "2026-10-19",
      "currency": "PLN",
      "total_gross": "163.99",
      "buyer_nip": "5260250274",
      "pdf_url": "https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w",
      "last_error": null,
      "created": 1760865185,
      "updated": 1760865214,
      "corrections": []
    }
  }
}

List events

GET /v1/events

The same events webhooks deliver, newest first. Useful for reconciling when your server missed webhooks. type narrows the list to one event type.

Parameters

limitquery · integer
How many objects per page.
Default 10 · 1-100
starting_afterquery · string
Id of the last object of the previous page.
typequery · string
Only events of this type.
One of: invoice.accepted, invoice.rejected, invoice.skipped, correction.accepted, correction.rejected, correction.skipped

Responses

200A page of events.
400Invalid request, e.g. parameter_invalid buyer_nip_invalid vat_rate_unsupported
401Missing or invalid key: api_key_missing api_key_invalid
404No such object (or it belongs to another account or mode): resource_missing

GET /v1/events

curl "https://app.ksefshop.pl/v1/events?limit=10" \
  -H "Authorization: Bearer $KSEF_API_KEY"

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/events?limit=10');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo count($data['data']), ' objects', PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/events?limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.data.length, data.has_more);

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/events?limit=10",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(len(data["data"]), data["has_more"])

Response

{
  "object": "list",
  "url": "/v1/events",
  "has_more": false,
  "data": []
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "buyer_nip_invalid",
    "message": "buyer.nip is not a valid Polish NIP (checksum).",
    "param": "order.buyer.nip",
    "doc_url": "https://ksefshop.pl/api/errors#buyer_nip_invalid"
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is wrong, revoked, or the account is disabled.",
    "doc_url": "https://ksefshop.pl/api/errors#api_key_invalid"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'",
    "doc_url": "https://ksefshop.pl/api/errors#resource_missing"
  }
}

Retrieve an event

GET /v1/events/{id}

One event by its evt_... id (the same id arrives in the KSeF-Event-Id header).

Parameters

idpath · stringrequired
The object's id.
Prefix evt_

Responses

200The event.
401Missing or invalid key: api_key_missing api_key_invalid
404No such object (or it belongs to another account or mode): resource_missing

GET /v1/events/{id}

curl https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8 \
  -H "Authorization: Bearer $KSEF_API_KEY"

<?php
$ch = curl_init('https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('KSEF_API_KEY'),
    ],
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);
if ($status >= 400) {
    throw new RuntimeException($data['error']['code'] . ': ' . $data['error']['message']);
}
echo var_export($data['type'], true), ' ', var_export($data['id'], true), PHP_EOL;

const res = await fetch("https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8", {
  headers: {
    Authorization: `Bearer ${process.env.KSEF_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
console.log(data.type, data.id);

import os
import requests

resp = requests.get(
    "https://app.ksefshop.pl/v1/events/evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8",
    headers={
        "Authorization": f"Bearer {os.environ['KSEF_API_KEY']}",
    },
    timeout=30,
)
data = resp.json()
if not resp.ok:
    raise RuntimeError(f"{data['error']['code']}: {data['error']['message']}")
print(data["type"], data["id"])

Response

{
  "id": "evt_Qa1Ws2Ed3Rf4Tg5Yh6Uj7Ik8",
  "object": "event",
  "type": "invoice.accepted",
  "livemode": false,
  "created": 1760865214,
  "data": {
    "object": {
      "id": "inv_4fJ2kP9xQwErTy7uI0oPaSdF",
      "object": "invoice",
      "livemode": false,
      "status": "accepted",
      "order": {
        "external_id": "SO-1001",
        "number": "1001"
      },
      "number": "FV/2026/10/1",
      "ksef_number": "4235405606-20261019-0E7570400000-57",
      "ksef_environment": "test",
      "issue_date": "2026-10-19",
      "currency": "PLN",
      "total_gross": "163.99",
      "buyer_nip": "5260250274",
      "pdf_url": "https://app.ksefshop.pl/pdf/cmgxa1b2c0000/Qk9tZ2FsX3ZhbGlkX3Rva2VuX2V4YW1w",
      "last_error": null,
      "created": 1760865185,
      "updated": 1760865214,
      "corrections": []
    }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "api_key_invalid",
    "message": "The API key is wrong, revoked, or the account is disabled.",
    "doc_url": "https://ksefshop.pl/api/errors#api_key_invalid"
  }
}

{
  "error": {
    "type": "not_found_error",
    "code": "resource_missing",
    "message": "No such invoice: 'inv_4fJ2kP9xQwErTy7uI0oPaSdF'",
    "doc_url": "https://ksefshop.pl/api/errors#resource_missing"
  }
}

Events

The Event object

Attributes

List events

Parameters

Responses

Retrieve an event

Parameters

Responses

API early access

Thank you!