Kaiten

List invoices

The organization's invoices, newest first; with updatedSince, the ones changed since an instant, oldest change first, for incremental sync. Invoices outlive their instance and customer. Requires billing to be enabled for the organization.

GET
/invoices

Authorization

bearerAuth read:billing
AuthorizationBearer <token>

A JWT verified by the proxy in front of this API, or a Kaiten access token (ksh_...) — send either as Authorization: Bearer <token>. The scopes listed on each operation are checked server-side against current stored user assignments or stored service-token permissions, never JWT claims; write:<module> implies read:<module>, and read:* / write:* are wildcards over every module. x-kaiten-scopes lists every scope such a token can carry, including those enforced by a service in front of this API rather than by one of its operations.

In: header

Scope: read:billing

Query Parameters

status?array<>|

Only invoices in these statuses; repeat the parameter for several

kind?string
Value in"ACTIVATION" | "RENEWAL" | "FINAL"
providerKind?string
Value in"NOOP" | "STRIPE"
customerSlug?string

Only this customer's invoices: composed under this slug, or of the customer that has it now

overdue?boolean

Only issued invoices still unpaid past their due date

held?boolean

Only DRAFTs held for their usage journal

handoffStatus?string
Value in"NOT_REQUIRED" | "PENDING" | "ACKNOWLEDGED"
issuedFrom?string

Issued at or after this instant (RFC 3339)

Formatdate-time
issuedTo?string

Issued before this instant (RFC 3339)

Formatdate-time
boundaryFrom?string

Billing a boundary at or after this instant

Formatdate-time
boundaryTo?string

Billing a boundary before this instant

Formatdate-time
updatedSince?string

Only invoices changed at or after this instant, oldest change first instead of newest invoice first: store the last updatedAt read and pass it next time to miss no change

Formatdate-time
cursor?string

Opaque cursor from the previous page's nextCursor

limit?integer

Page size, 50 by default, 200 at most

Formatint32
Range0 <= value <= 200
instanceSlug?string

Only this instance's invoices: composed under this slug, or of the instance that has it now

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://app.kaiten.sh/api/invoices"
{
  "hasMore": true,
  "items": [
    {
      "boundaryAt": "2019-08-24T14:15:22Z",
      "collectionMethod": "SEND_INVOICE",
      "createdAt": "2019-08-24T14:15:22Z",
      "currency": "EUR",
      "customerName": "string",
      "customerSlug": "string",
      "daysUntilDue": 0,
      "discountTotal": 0,
      "dueAt": "2019-08-24T14:15:22Z",
      "handoffStatus": "NOT_REQUIRED",
      "holdReason": "LEDGER_SEQUENCE_GAP",
      "id": "string",
      "instanceName": "string",
      "instanceSlug": "string",
      "issuedAt": "2019-08-24T14:15:22Z",
      "kind": "ACTIVATION",
      "licenseSlug": "string",
      "overdue": true,
      "paidAt": "2019-08-24T14:15:22Z",
      "providerKind": "NOOP",
      "serviceFrom": "2019-08-24T14:15:22Z",
      "serviceTo": "2019-08-24T14:15:22Z",
      "status": "DRAFT",
      "subtotal": 0,
      "total": 0,
      "updatedAt": "2019-08-24T14:15:22Z"
    }
  ],
  "nextCursor": "string"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}
{
  "code": "License.NotFound",
  "detail": "license not found",
  "errorId": "3f6b1a2c-7c1e-4d0b-9d5f-2b0a1c4e8d31",
  "errors": [
    {
      "location": "string",
      "message": "string",
      "value": null
    }
  ],
  "instance": "/api/licenses/enterprise",
  "status": 404,
  "title": "Not Found",
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4"
}

List an instance's invoices

The invoices of one instance's subscription, across every time it was subscribed, with the filters of listInvoices. Requires billing to be enabled for the organization.

Export invoices

Streams the invoices the filters of listInvoices select, as CSV or NDJSON. Amounts are integer minor units with the currency's exponent beside them, so a spreadsheet never sees a float. The export carries billing e-mails: it is an authenticated read for the organization's accounting. Requires billing to be enabled for the organization.