Kaiten

Cancel a subscription

Cancels an instance's subscription: a trial at once with no invoice; otherwise at the period's end (repeating it changes nothing), or immediately with a FINAL invoice. Cancellation changes billing only: entitlements and licence dates stay the vendor's to change. Requires billing to be enabled for the organization.

POST
/instances/{instanceSlug}/billing/cancel

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.

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 POST "https://app.kaiten.sh/api/instances/acme-prod/billing/cancel" \  -H "Content-Type: application/json" \  -d '{}'
{
  "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,
  "finalInvoice": {
    "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"
  },
  "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"
}

Change a subscription's terms or provider

Changes the subscription's payment provider, collection method and payment terms from its next invoice on; null restores the organization's default. Invoices already composed keep their own, and keep routing to the provider that issued them. Moving to a provider that pushes invoices registers the customer with it first (503 UpdateInstanceBilling.ProviderUnavailable when it cannot be reached). A provider change emits INSTANCE_BILLING_PROVIDER_CHANGED. Requires billing to be enabled for the organization.

Reactivate a subscription

Reverts a cancellation scheduled for the period end, before it. A canceled subscription is subscribed again instead. Requires billing to be enabled for the organization.