Kaiten

Check out

Subscribes the session's instance to a price of the public catalogue, with add-ons and a voucher, in one call. With dryRun, answers 200 status=preview and what would be billed today, changing nothing. When a payment method has to be saved first, answers 200 status=requires_payment_method with a setup page: send the customer there, then call again with its setupSessionId. Otherwise answers 201 status=subscribed: the invoice of the first period has been pushed and charged, and payment.status says how that went -- poll GET /public/session/invoices on processing or requires_action. Needs a session bound to an instance. An instance whose live subscription is free (a FREE licence family, no add-on price above 0) is checked out too: that subscription is canceled at once, with no invoice, in the same transaction. 409 .AlreadySubscribed (any other live subscription), .SetupSessionIncomplete (no payment method was saved on the setup page); 422 .InstanceRequired, .NotSelfServe, .PriceNotPublic, .PriceNotFlatFee, .BillingEmailRequired, .InvalidReturnUrl, .ProviderCannotCapturePayment, .VoucherInvalid, .AddonInvalid, .AddonNotPublic, .QuantityExceedsMax, .CurrencyMismatch, .QuotaExceeded (the instance uses more than the plan allows: errors[0].value.entitlementSlugs, location body.licensePriceId); 503 .ProviderUnavailable (Retry-After).

POST
/public/session/checkout

Authorization

customerSession
AuthorizationBearer <token>

A customer session (kst_...), minted by the vendor's backend with POST /customer-sessions and sent as Authorization: Bearer kst_.... It acts for one customer -- and one of its instances, when bound -- on the /public/session routes and nowhere else. A browser request must come from an origin one of the organization's publishable keys allows.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

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/public/session/checkout" \  -H "Content-Type: application/json" \  -d '{    "licensePriceId": "string"  }'
{
  "activationInvoice": {
    "currency": "EUR",
    "discountTotal": 0,
    "dueAt": "2019-08-24T14:15:22Z",
    "externalReference": "string",
    "hostedInvoiceUrl": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "invoicePdfUrl": "string",
    "issuedAt": "2019-08-24T14:15:22Z",
    "kind": "ACTIVATION",
    "lines": [
      {
        "amount": 0,
        "description": "string",
        "label": "string",
        "quantity": "string",
        "seq": 0,
        "serviceFrom": "2019-08-24T14:15:22Z",
        "serviceTo": "2019-08-24T14:15:22Z",
        "type": "BASE",
        "unitAmountDecimal": "string"
      }
    ],
    "paidAt": "2019-08-24T14:15:22Z",
    "providerInvoiceNumber": "string",
    "serviceFrom": "2019-08-24T14:15:22Z",
    "serviceTo": "2019-08-24T14:15:22Z",
    "status": "MANUAL",
    "subtotal": 0,
    "total": 0
  },
  "dueToday": {
    "currency": "EUR",
    "discountTotal": 0,
    "lines": [
      {
        "amount": 0,
        "description": "string",
        "label": "string",
        "quantity": "string",
        "seq": 0,
        "serviceFrom": "2019-08-24T14:15:22Z",
        "serviceTo": "2019-08-24T14:15:22Z",
        "type": "BASE",
        "unitAmountDecimal": "string"
      }
    ],
    "subtotal": 0,
    "total": 0
  },
  "expiresAt": "2019-08-24T14:15:22Z",
  "payment": {
    "hostedInvoiceUrl": "string",
    "status": "paid"
  },
  "setupSessionId": "string",
  "setupUrl": "string",
  "status": "preview",
  "subscription": {
    "basePrice": {
      "billingModel": "FLAT_FEE",
      "billingPeriod": "MONTHLY",
      "billingTiming": "ADVANCE",
      "currency": "EUR",
      "displayLabel": "Pro plan",
      "displayOrder": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "isDefault": true,
      "metered": {
        "entitlementSlug": "tokens",
        "saleUnitFactor": "10000",
        "saleUnitPlural": "10k tokens",
        "saleUnitSingular": "10k tokens"
      },
      "unitAmount": 2900,
      "unitAmountDecimal": "2900"
    },
    "billingPeriod": "MONTHLY",
    "cancelAtPeriodEnd": true,
    "canceledAt": "2019-08-24T14:15:22Z",
    "cancellationReason": "TRIAL_ENDED_WITHOUT_PAYMENT_METHOD",
    "collectionMethod": "SEND_INVOICE",
    "currency": "EUR",
    "currentPeriodEnd": "2019-08-24T14:15:22Z",
    "currentPeriodStart": "2019-08-24T14:15:22Z",
    "incompleteExpiresAt": "2019-08-24T14:15:22Z",
    "providerKind": "NOOP",
    "scheduledChange": {
      "effectiveAt": "2019-08-24T14:15:22Z",
      "price": {
        "billingModel": "FLAT_FEE",
        "billingPeriod": "MONTHLY",
        "billingTiming": "ADVANCE",
        "currency": "EUR",
        "displayLabel": "Pro plan",
        "displayOrder": 0,
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "isDefault": true,
        "metered": {
          "entitlementSlug": "tokens",
          "saleUnitFactor": "10000",
          "saleUnitPlural": "10k tokens",
          "saleUnitSingular": "10k tokens"
        },
        "unitAmount": 2900,
        "unitAmountDecimal": "2900"
      }
    },
    "status": "INCOMPLETE",
    "trialEndsAt": "2019-08-24T14:15:22Z"
  },
  "trialEndsAt": "2019-08-24T14:15:22Z"
}
{
  "activationInvoice": {
    "currency": "EUR",
    "discountTotal": 0,
    "dueAt": "2019-08-24T14:15:22Z",
    "externalReference": "string",
    "hostedInvoiceUrl": "string",
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "invoicePdfUrl": "string",
    "issuedAt": "2019-08-24T14:15:22Z",
    "kind": "ACTIVATION",
    "lines": [
      {
        "amount": 0,
        "description": "string",
        "label": "string",
        "quantity": "string",
        "seq": 0,
        "serviceFrom": "2019-08-24T14:15:22Z",
        "serviceTo": "2019-08-24T14:15:22Z",
        "type": "BASE",
        "unitAmountDecimal": "string"
      }
    ],
    "paidAt": "2019-08-24T14:15:22Z",
    "providerInvoiceNumber": "string",
    "serviceFrom": "2019-08-24T14:15:22Z",
    "serviceTo": "2019-08-24T14:15:22Z",
    "status": "MANUAL",
    "subtotal": 0,
    "total": 0
  },
  "dueToday": {
    "currency": "EUR",
    "discountTotal": 0,
    "lines": [
      {
        "amount": 0,
        "description": "string",
        "label": "string",
        "quantity": "string",
        "seq": 0,
        "serviceFrom": "2019-08-24T14:15:22Z",
        "serviceTo": "2019-08-24T14:15:22Z",
        "type": "BASE",
        "unitAmountDecimal": "string"
      }
    ],
    "subtotal": 0,
    "total": 0
  },
  "expiresAt": "2019-08-24T14:15:22Z",
  "payment": {
    "hostedInvoiceUrl": "string",
    "status": "paid"
  },
  "setupSessionId": "string",
  "setupUrl": "string",
  "status": "preview",
  "subscription": {
    "basePrice": {
      "billingModel": "FLAT_FEE",
      "billingPeriod": "MONTHLY",
      "billingTiming": "ADVANCE",
      "currency": "EUR",
      "displayLabel": "Pro plan",
      "displayOrder": 0,
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "isDefault": true,
      "metered": {
        "entitlementSlug": "tokens",
        "saleUnitFactor": "10000",
        "saleUnitPlural": "10k tokens",
        "saleUnitSingular": "10k tokens"
      },
      "unitAmount": 2900,
      "unitAmountDecimal": "2900"
    },
    "billingPeriod": "MONTHLY",
    "cancelAtPeriodEnd": true,
    "canceledAt": "2019-08-24T14:15:22Z",
    "cancellationReason": "TRIAL_ENDED_WITHOUT_PAYMENT_METHOD",
    "collectionMethod": "SEND_INVOICE",
    "currency": "EUR",
    "currentPeriodEnd": "2019-08-24T14:15:22Z",
    "currentPeriodStart": "2019-08-24T14:15:22Z",
    "incompleteExpiresAt": "2019-08-24T14:15:22Z",
    "providerKind": "NOOP",
    "scheduledChange": {
      "effectiveAt": "2019-08-24T14:15:22Z",
      "price": {
        "billingModel": "FLAT_FEE",
        "billingPeriod": "MONTHLY",
        "billingTiming": "ADVANCE",
        "currency": "EUR",
        "displayLabel": "Pro plan",
        "displayOrder": 0,
        "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
        "isDefault": true,
        "metered": {
          "entitlementSlug": "tokens",
          "saleUnitFactor": "10000",
          "saleUnitPlural": "10k tokens",
          "saleUnitSingular": "10k tokens"
        },
        "unitAmount": 2900,
        "unitAmountDecimal": "2900"
      }
    },
    "status": "INCOMPLETE",
    "trialEndsAt": "2019-08-24T14:15:22Z"
  },
  "trialEndsAt": "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"
}

Keep a subscription scheduled for cancellation

Takes back a cancellation scheduled for the period's end, before it: the subscription renews as before. 409 .NotScheduledForCancellation when none is scheduled (or the subscription has already ended), .BoundaryPending while the period that ended is being closed (Retry-After); 422 .InstanceRequired for a session bound to no instance.

List the customer's invoices

The session's customer's issued invoices -- its instance's, for a session bound to one -- newest first, with how to pay each. An invoice still awaiting the outcome of its payment is read from the payment provider first, at most every 30 seconds: poll this after a checkout answered processing or requires_action.