Kaiten

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.

GET
/instances/{instanceSlug}/billing/upcoming-invoice

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

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/billing/upcoming-invoice"
{
  "asOf": "2019-08-24T14:15:22Z",
  "boundaryAt": "2019-08-24T14:15:22Z",
  "currency": "EUR",
  "discountTotal": 0,
  "kind": "ACTIVATION",
  "licenseSlug": "string",
  "lines": [
    {
      "addonId": "string",
      "addonPriceId": "string",
      "amount": 2440,
      "billingModel": "FLAT_FEE",
      "billingTiming": "ADVANCE",
      "capped": true,
      "description": "3.05 × 8.00 EUR (per 10k tokens); 130,500 used; 30,500 above the applied limit (100,000)",
      "discount": {
        "allocations": [
          {
            "amount": 0,
            "targetSeq": 0
          }
        ],
        "application": 0,
        "applicationsMax": 0,
        "appliesTo": "LICENSE_BASE",
        "base": "string",
        "currency": "string",
        "discountType": "PERCENTAGE",
        "discountValue": "string",
        "targetSeqs": [
          0
        ]
      },
      "entitlementId": "string",
      "entitlementSlug": "string",
      "id": "string",
      "instanceAddonId": "string",
      "instanceVoucherId": "string",
      "label": "Tokens — overage",
      "licensePriceId": "string",
      "metering": {
        "ledger": {
          "firstSeq": 0,
          "instanceId": "string",
          "lastSeq": 0,
          "rows": 0,
          "sumDelta": "string",
          "sumOverage": "string"
        },
        "measuredQuantity": "30500",
        "negativeSegmentsFloored": 0,
        "saleUnitFactor": "10000",
        "windows": 1
      },
      "overage": {
        "limits": [
          {
            "limitValue": "100000",
            "overagePercent": 50,
            "rows": 0
          }
        ],
        "overageMeasured": "30500",
        "usageMeasured": "130500"
      },
      "provider": {
        "amount": 0,
        "couponIds": [
          "string"
        ],
        "externalLineId": "string"
      },
      "quantity": "3.05",
      "seq": 0,
      "serviceFrom": "2019-08-24T14:15:22Z",
      "serviceTo": "2019-08-24T14:15:22Z",
      "trueUp": {
        "billedQuantity": 0,
        "maxQuantity": 0
      },
      "type": "BASE",
      "unitAmountDecimal": "800",
      "voucherId": "string"
    }
  ],
  "serviceFrom": "2019-08-24T14:15:22Z",
  "serviceTo": "2019-08-24T14:15:22Z",
  "status": "PREVIEW",
  "subtotal": 0,
  "total": 0,
  "wouldHold": [
    {
      "entitlementId": "string",
      "invariant": "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"
}

Schedule a plan change

Schedules a move to another FLAT_FEE price, of any PUBLISHED licence version in the subscription's currency, for the next boundary. That boundary's RENEWAL bills the old plan's arrears and the new plan's advance, and moves the instance to the new version; there is no proration. Scheduling another target replaces the change, the same one changes nothing. A scheduled target's price cannot be deprecated, nor its version archived. Requires billing to be enabled for the organization.

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.