Set how many of an add-on the instance holds
Attaches the add-on to the session's instance, changes its quantity, or removes it with 0. An attach or an increase changes the entitlements at once. With a live subscription a lower quantity, or 0, is scheduled for the next renewal: pendingQuantity shows it, and the quantity held, its entitlements and its billing stay until then; the quantity held cancels it, and so does an increase. Without a live subscription every change applies at once. The subscription bills the quantity held at each renewal, with no proration. Setting the quantity held, with nothing scheduled, changes nothing. 409 .OtherVersionAttached when another version of the same add-on is held, .BoundaryPending while the period that ended is being closed (Retry-After); 422 .AddonNotPublic, .Incompatible, .QuantityExceedsMax, .CurrencyMismatch, .InstanceRequired.
Authorization
customerSession 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
Path Parameters
An add-on version: the public one, or the one the instance holds
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 PUT "https://app.kaiten.sh/api/public/session/addons/extra-seats-v1" \ -H "Content-Type: application/json" \ -d '{ "quantity": 3 }'{
"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
}{
"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"
}Confirm an anonymous checkout
Completes the session when nothing has to be captured -- a FREE plan, a trial on a plan that needs no payment method, nothing due -- creating the customer, the instance and the subscription in one transaction: status=completed. Otherwise answers status=requires_payment_method with a hosted setup page, keeps the ksc_ across its redirect, and completes on the next confirm: awaiting_payment while the first invoice is charged, completed once paid. No body. 403 .AnonymousCheckoutDisabled; 409 .SessionClosed (errors[0].value.status), .DueTodayChanged, .EntitlementLimitReached; 422 .PriceNotPublic, .AddonNotPublic, .FallbackRequired, .ProviderCannotCapturePayment, .VoucherInvalid; 429 .RateLimited (Retry-After): 30 confirms per 10 minutes per visitor address, 1,000 an hour per key; 503 .ProviderUnavailable (Retry-After), Entitlement.VerificationUnavailable.
Cancel the subscription at the period's end
Cancels the subscription of the session's instance at the end of the period paid for: it keeps billing and granting until then, and reactivating before then keeps it. A trial ends at once, with nothing to pay. Repeating it changes nothing. 409 .NotActive when there is no live subscription, .BoundaryPending while the period that ended is being closed (Retry-After); 422 .InstanceRequired for a session bound to no instance.