Kaiten

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.

GET
/instances/{instanceSlug}/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

Path Parameters

instanceSlug*string

Instance slug

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

Response Body

application/json

application/problem+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/instances/acme-prod/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"
}
{
  "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"
}

Preview an instance's upcoming invoice

The invoice the subscription's next boundary will issue, composed from its usage so far, without writing anything: lines carry the period they will bill, quantities what was measured until now. wouldHold lists the meters whose usage journal fails a check and would hold the invoice. Requires billing to be enabled for the organization.

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.