Subscriptions API: Plans, Access, and Limits for Your SaaS

How to describe plans in the dashboard and check access, trials, and limit usage through /v2/subscriptions with an xsub_… key.

Why xpayment has subscriptions

If you run a SaaS, an app, a club, or a school and users pay for access by plans, you need to store three things: what each plan includes, until when it is paid, and how much of a limit has been used. The “Подписки” (Subscriptions) section takes this on. You describe plans in the dashboard, and your service asks through the API: “what is available to this user?”.

xpayment keeps track of:

This is not the same as a payment through the API: a payment accepts money once, while a subscription answers the question “does the user have access right now”. The two are connected: an invoice for a subscription is an ordinary Kaspi phone invoice.

How it is organized

"Подписки" dashboard      Your service                       xpayment
 plans, limits    <--->   PUT  /v2/subscriptions/accounts/{id}   (create a user)
 grants, payment          GET  .../{id}/check?capability=...     (is there access?)
                          POST .../{id}/usage                    (record usage)

For this API you have your own key: xsub_…. It is issued together with a subscriptions project and works only on /v2/subscriptions. Payment keys xapi_… and subscription keys xsub_… are not interchangeable: a key of one kind on the endpoints of the other gives 401.

Subscriptions are in beta for now. Terms and fields may be refined; the current reference is in the documentation.

Setting up in the dashboard

1. A project and a key

Open Подписки (Subscriptions) and create a project (“Новый проект”, New project). Together with it an xsub_… key is created: it is shown once, afterwards only the prefix is visible. Keep the key on the server, like the xapi_… key.

The key can be rotated: the new key works at once, while the old one keeps working for another 24 hours so you have time to update your service. You can end the old key earlier in the project settings.

2. The catalog

On the dashboard tabs you describe what you sell:

What What it is for Example
Capability An access flag catalog — “Product catalog”
Limit A counter with a unit and a reset period (none, day, month) orders_m — “Orders” per month
Plan A set of capabilities and limits, assembled from blocks (groups) “Start” in the “Catalog” block
Add-on What can be bought on top of a plan seat_extra — “Extra employee”

Every entity has a code that your service uses in the API, so choose short, stable codes. A plan can be a draft, active, or archived; only active plans can make up a subscription.

3. Accounts and granting subscriptions

An account is a user or company of your product. A subscription can be:

The dashboard tabs show the overview, the list of subscriptions and accounts, payments, trials, limit usage, and analytics.

4. The register and payment

Subscriptions are paid with a Kaspi invoice issued to the account’s phone from the project’s register. For that the account must have a phone number (otherwise the API answers 409 PHONE_REQUIRED), and the project must have a register chosen: Connecting a cash register and getting an API v2 key.

How the auto-invoice works: a few days before the end of the period xpayment issues a Kaspi invoice and keeps retrying until it is paid; payment extends the period. If the register is broken or not chosen, the invoice is not sent until you fix it. The money goes straight to your Kaspi account.

The API for your service

Base: https://api.xpayment.kz/v2/subscriptions. Header: Authorization: Bearer xsub_…. Responses come with the header Cache-Control: no-store. Error texts in this API are in English.

Method Path What it does
PUT /accounts/{externalID} Create or update an account
GET /accounts/{externalID} The account’s entitlements (entitlements)
GET /accounts/{externalID}/check Check one capability or limit
POST /accounts/{externalID}/trial Start a trial
POST /accounts/{externalID}/usage Record usage of a limit

externalID is your user identifier: 1–100 characters from A–Z a–z 0–9 . _ : @ + -. In the address it must be URL-encoded (user@mail.kz → user%40mail.kz).

Create an account

curl -X PUT "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040" \
  -H "Authorization: Bearer xsub_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Kazmart.kz", "phone": "+7 701 200 10 30", "email": "admin@kazmart.kz"}'

All fields are optional: a missing field is left unchanged, and null clears it. The phone is normalized to the form +7XXXXXXXXXX. The answer 201 (created) or 200 (updated) contains the account’s entitlements.

Entitlements

GET /accounts/{externalID} returns:

{
  "external_id": "shop_1040",
  "name": "Kazmart.kz",
  "status": "active",
  "access": true,
  "until": "2026-12-01",
  "access_ends_at": "2026-12-01T19:00:00Z",
  "period": "month",
  "plans": [{"code": "cat_start", "name": "Start", "block": "Catalog"}],
  "capabilities": [
    {"code": "catalog", "name": "Product catalog",
     "source": {"type": "plan", "code": "cat_start", "name": "Start", "block": "Catalog"}}
  ],
  "limits": [
    {"limit": "orders_m", "name": "Orders", "limit_value": 300, "unlimited": false,
     "used": 121, "remaining": 179, "resets_at": "2026-11-30T19:00:00Z"}
  ]
}

status: none (no subscription), trial, active, canceling (cancelled, access until the end of the period), expired. The capabilities and limits fields are filled only when access: true. You can cache the response for no longer than a minute: changes from the dashboard are visible from the next request.

Checking access

For a single check, check is handier: specify exactly one of capability or limit.

# is a capability available
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?capability=catalog" \
  -H "Authorization: Bearer xsub_YOUR_KEY"

# is there enough limit for 5 units
curl "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/check?limit=orders_m&need=5" \
  -H "Authorization: Bearer xsub_YOUR_KEY"

The answer is always 200 (even for an unknown account): {"allowed": true, "reason": null, "status": "active", ...}. If allowed: false, reason explains why:

reason Meaning
account_not_found There is no such account
no_subscription The account has no subscription
expired The term has ended
not_in_plan The capability is not in the account’s plans
limit_not_set The plans have no such limit
limit_exhausted The remainder is less than need

An unknown capability or limit code gives 404 UNKNOWN_CODE.

Trial

curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/trial" \
  -H "Authorization: Bearer xsub_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plans": ["cat_start"], "addons": [], "period": "month"}'

The account must exist (PUT first) and have no access. The trial lasts as long as the longest trial of the chosen plans, and period (month or year) sets the period after it. The 201 response contains the entitlements. Typical errors: 404 ACCOUNT_NOT_FOUND, 409 TRIAL_NOT_ALLOWED (access already exists), 409 TRIAL_ALREADY_USED, 409 NO_TRIAL (none of the plans has a trial).

Recording usage

curl -X POST "https://api.xpayment.kz/v2/subscriptions/accounts/shop_1040/usage" \
  -H "Authorization: Bearer xsub_YOUR_KEY" \
  -H "X-Idempotency-Key: order-8812-created" \
  -H "Content-Type: application/json" \
  -d '{"limit": "orders_m", "delta": 1}'

Rules:

Limits reset by the Kazakhstan calendar: daily, monthly, or never.

Common errors and request limits

HTTP Code Cause
401 UNAUTHORIZED The header is missing, the key is wrong or revoked, or it is not an xsub_ key
429 RATE_LIMITED Too many requests; see the Retry-After header
500 INTERNAL_ERROR An unexpected error

Subscriptions have no outgoing webhooks: your service polls GET /accounts/{id} or check when it needs to.

A typical rollout

  1. Describe the plans in the dashboard: capabilities, limits, plans, and add-ons. Choose short, stable codes.
  2. Create an account when a user registers: PUT /accounts/{id} with a name, phone, and email.
  3. Start a trial, if you have one: POST …/trial with plan codes.
  4. Check access where it matters: check?capability=… before an action, or GET /accounts/{id} if you need all entitlements at once. Cache the answer for no more than a minute.
  5. Record usage: POST …/usage with X-Idempotency-Key, for example order-8812-created. That way a retry after a timeout does not count the usage twice.
  6. xpayment handles renewal: the Kaspi auto-invoice extends the period after payment, and your service sees the new term on its next check.

Practical tips

Where to look