Kaiten

List the handoff queue

The invoices waiting for the organization's accounting system (PENDING), or already acknowledged by it, oldest issue first. Reading never leases: claim to take invoices. Requires billing to be enabled for the organization.

GET
/billing/handoff

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?string

PENDING (the default) or ACKNOWLEDGED; .InvalidStatus otherwise

Value in"PENDING" | "ACKNOWLEDGED"
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

curl -X GET "https://app.kaiten.sh/api/billing/handoff"
{
  "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",
      "handoff": {
        "acknowledgedAt": "2019-08-24T14:15:22Z",
        "claimCount": 0,
        "externalReference": "string",
        "leaseId": "string",
        "leasedUntil": "2019-08-24T14:15:22Z",
        "status": "NOT_REQUIRED"
      },
      "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"
}

Close due billing periods

Closes the subscriptions whose period has ended now, rather than at the period-close job's next pass: each one's RENEWAL invoice is composed and issued (or held, when its usage journal fails a check) and its period advances. A subscription several periods behind closes one period at a time until it is current. Only what is due closes, at most the configured batch size per call. Requires billing to be enabled for the organization.

Claim invoices from the handoff queue

Leases the oldest invoices waiting for the organization's accounting system, under one lease. Two consumers claiming at once get different invoices. An invoice not acknowledged before its lease expires is claimed again: the queue delivers at least once, so a consumer deduplicates on the invoice id. A claim is not idempotent: a lost response leaves its invoices leased until leasedUntil. Requires billing to be enabled for the organization.