Kaiten

Read the customer portal

Everything the customer's portal shows, in one read: the customer, and for a session bound to an instance its subscription, effective quotas with where they come from, add-ons, vouchers and next invoice; the payment method; and what the portal may offer. A session bound to the customer only gets the customer, its instances and the payment method.

GET
/public/session/portal

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

Response Body

application/json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

application/problem+json

curl -X GET "https://app.kaiten.sh/api/public/session/portal"
{
  "addOns": [
    {
      "addonSlug": "extra-seats-v1",
      "familySlug": "extra-seats",
      "maxQuantity": 0,
      "name": "Extra seats",
      "pendingQuantity": 0,
      "prices": [
        {
          "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"
        }
      ],
      "quantity": 3
    }
  ],
  "branding": {
    "poweredByRemovable": true
  },
  "capabilities": {
    "checkout": true,
    "invoices": true,
    "paymentMethods": true,
    "unsubscribe": true
  },
  "customer": {
    "billingEmail": "string",
    "name": "Acme",
    "slug": "acme"
  },
  "entitlements": [
    {
      "currentPeriodEnd": "2019-08-24T14:15:22Z",
      "currentPeriodStart": "2019-08-24T14:15:22Z",
      "currentValue": 0,
      "limitCapExceededOveragePercent": 0,
      "limitValue": {
        "event_count": 2,
        "type": "number",
        "value": 42.5
      },
      "maximumAllowedUsage": 0,
      "name": "Seats",
      "percentageUsed": 0,
      "provenance": {
        "addons": [
          {
            "addonEntitlementId": "string",
            "addonId": "string",
            "attachedAt": "2019-08-24T14:15:22Z",
            "instanceAddonId": "string",
            "limitCapExceededOveragePercent": 0,
            "overrideBehavior": "ADD",
            "quantity": 0,
            "value": {
              "event_count": 2,
              "type": "number",
              "value": 42.5
            }
          }
        ],
        "boosts": [
          {
            "effectiveExpiresAt": "2019-08-24T14:15:22Z",
            "effectiveStartsAt": "2019-08-24T14:15:22Z",
            "instanceVoucherId": "string",
            "modifierType": "SET",
            "modifierValue": 0,
            "redeemedAt": "2019-08-24T14:15:22Z",
            "value": {
              "event_count": 2,
              "type": "number",
              "value": 42.5
            },
            "voucherEntitlementGrantId": "string",
            "voucherId": "string"
          }
        ],
        "exception": {
          "endsAt": "2019-08-24T14:15:22Z",
          "instanceEntitlementExceptionId": "string",
          "kind": "SET",
          "startsAt": "2019-08-24T14:15:22Z",
          "value": {
            "event_count": 2,
            "type": "number",
            "value": 42.5
          }
        },
        "license": {
          "licenseEntitlementId": "string",
          "limitCapExceededOveragePercent": 0,
          "value": {
            "event_count": 2,
            "type": "number",
            "value": 42.5
          }
        },
        "number": {
          "afterAddons": 0.1,
          "afterBoosts": 0.1,
          "boostAdd": 0,
          "boostMultiply": 0,
          "boostSet": 0,
          "effective": 0.1,
          "license": 0,
          "unlimited": true
        }
      },
      "slug": "seats",
      "source": "license",
      "type": "NUMBER",
      "unlimited": true
    }
  ],
  "instance": {
    "licenseName": "Pro",
    "licenseSlug": "pro-v2",
    "name": "Acme prod",
    "slug": "acme-prod"
  },
  "instances": [
    {
      "billingStatus": "INCOMPLETE",
      "licenseSlug": "pro-v2",
      "name": "Acme prod",
      "slug": "acme-prod"
    }
  ],
  "paymentMethod": {
    "brand": "visa",
    "expMonth": 12,
    "expYear": 2030,
    "last4": "4242",
    "status": "ACTIVE"
  },
  "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"
  },
  "trial": {
    "charge": {
      "amount": 0,
      "billingPeriod": "MONTHLY",
      "currency": "EUR"
    },
    "endsAt": "2019-08-24T14:15:22Z",
    "paymentMethod": {
      "brand": "visa",
      "last4": "4242"
    },
    "reminderAt": "2019-08-24T14:15:22Z"
  },
  "upcomingInvoice": {
    "boundaryAt": "2019-08-24T14:15:22Z",
    "currency": "EUR",
    "discountTotal": 0,
    "subtotal": 0,
    "total": 0
  },
  "updatedAt": "2019-08-24T14:15:22Z",
  "vouchers": [
    {
      "applicationsCount": 0,
      "applicationsMax": 0,
      "appliesFromInvoice": "next",
      "effectiveExpiresAt": "2019-08-24T14:15:22Z",
      "effectiveStartsAt": "2019-08-24T14:15:22Z",
      "name": "Summer launch",
      "status": "ACTIVE",
      "voucherType": "PRICE"
    }
  ]
}
{
  "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"
}

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.

Redeem a voucher code

Redeems a code on the session's instance, whose subscription is TRIAL, ACTIVE or PAST_DUE: 201 with the redemption, never the code; dryRun answers 200 with the redemption it would make and writes nothing. A PRICE voucher discounts from the next invoice composed (appliesFromInvoice: next), never one already issued; a boost applies at once. Every refusal of the code is the same 422 .VoucherInvalid. 409 .SubscriptionIncomplete (a checkout waits for its payment), .NoLiveSubscription; 422 .InstanceRequired (a session bound to the customer only); 429 .RateLimited, with Retry-After, past 10 attempts per 10 minutes per session or 30 an hour per customer, validate's included.