Kaiten

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.

PUT
/instances/{instanceSlug}/billing/scheduled-change

Authorization

bearerAuth write: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: write:billing

Path Parameters

instanceSlug*string

Instance slug

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

licensePriceId*string

An ACTIVE FLAT_FEE price of a PUBLISHED licence version, in the subscription's currency

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

application/problem+json

curl -X PUT "https://app.kaiten.sh/api/instances/acme-prod/billing/scheduled-change" \  -H "Content-Type: application/json" \  -d '{    "licensePriceId": "string"  }'
{
  "anchorAt": "2019-08-24T14:15:22Z",
  "basePrice": {
    "billingModel": "FLAT_FEE",
    "billingPeriod": "MONTHLY",
    "billingTiming": "ADVANCE",
    "createdAt": "2019-08-24T14:15:22Z",
    "currency": "EUR",
    "deprecatedAt": "2019-08-24T14:15:22Z",
    "displayLabel": "Pro plan",
    "displayOrder": 0,
    "id": "string",
    "isDefault": true,
    "metered": {
      "entitlementSlug": "tokens",
      "saleUnitFactor": "10000",
      "saleUnitPlural": "10k tokens",
      "saleUnitSingular": "10k tokens"
    },
    "status": "ACTIVE",
    "unitAmount": 2900,
    "unitAmountDecimal": "2900",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "billingPeriod": "MONTHLY",
  "cancelAtPeriodEnd": true,
  "cancelRequestedAt": "2019-08-24T14:15:22Z",
  "canceledAt": "2019-08-24T14:15:22Z",
  "cancellationReason": "string",
  "collectionMethod": "SEND_INVOICE",
  "collectionMethodOverride": "string",
  "createdAt": "2019-08-24T14:15:22Z",
  "currency": "EUR",
  "currentPeriodEnd": "2019-08-24T14:15:22Z",
  "currentPeriodStart": "2019-08-24T14:15:22Z",
  "customerName": "string",
  "customerSlug": "string",
  "daysUntilDue": 0,
  "daysUntilDueOverride": 0,
  "id": "string",
  "incompleteExpiresAt": "2019-08-24T14:15:22Z",
  "instanceName": "string",
  "instanceSlug": "string",
  "pastDueSince": "2019-08-24T14:15:22Z",
  "pendingLicenseSlug": "string",
  "providerKind": "NOOP",
  "reminderAt": "2019-08-24T14:15:22Z",
  "scheduledChange": {
    "effectiveAt": "2019-08-24T14:15:22Z",
    "licenseSlug": "string",
    "price": {
      "billingModel": "FLAT_FEE",
      "billingPeriod": "MONTHLY",
      "billingTiming": "ADVANCE",
      "createdAt": "2019-08-24T14:15:22Z",
      "currency": "EUR",
      "deprecatedAt": "2019-08-24T14:15:22Z",
      "displayLabel": "Pro plan",
      "displayOrder": 0,
      "id": "string",
      "isDefault": true,
      "metered": {
        "entitlementSlug": "tokens",
        "saleUnitFactor": "10000",
        "saleUnitPlural": "10k tokens",
        "saleUnitSingular": "10k tokens"
      },
      "status": "ACTIVE",
      "unitAmount": 2900,
      "unitAmountDecimal": "2900",
      "updatedAt": "2019-08-24T14:15:22Z"
    },
    "scheduledAt": "2019-08-24T14:15:22Z"
  },
  "startedAt": "2019-08-24T14:15:22Z",
  "status": "INCOMPLETE",
  "trialEndsAt": "2019-08-24T14:15:22Z",
  "updatedAt": "2019-08-24T14:15:22Z"
}
{
  "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"
}
{
  "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"
}

Cancel a scheduled plan change

Drops the plan change scheduled for the next boundary. Requires billing to be enabled for the organization.

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.