API reference

Every call, three contracts, OpenAPI files

The back office is a client of the same API that integrators use. Three contracts cover the platform, the till and point-of-sale terminals; each one is published as an OpenAPI 3 file you can load into Postman, Swagger UI or a code generator.

Platform API/api/v1 · 301 calls · JWT bearer token with refresh; roles and store scope per user Till API/v2 · 41 calls · bearer key per till or shop, bound to a location POS API/pos/v1 · 16 calls · API key header per terminal

Authentication

Platform API: sign in with e-mail and password, receive a JWT and a refresh token; two-factor codes for super admins. Till API: a bearer key created in the back office, shown once, rotatable. POS API: an X-POS-Api-Key header.

Conventions

JSON in and out. Lists are paginated. Errors carry a machine-readable code and, for validation, the list of violated fields. Money in the till API is in major units of the tenant's currency; ids are UUIDs.

Limits and safety

Rate limits per key and per login; idempotent purchase commits by external receipt id; webhook signatures on both directions; every write recorded in the audit log.

Platform API /api/v1

Back office, member portal and super-admin: everything the web application does, available to integrators.

301 calls · Download the OpenAPI file

Auth 13 Members 12 Wallets 9 Transactions 3 Tiers 5 Rules 9 Segments 7 Campaigns 8 Bonus Packages 10 Date Triggers 5 Scenarios 9 Message Templates 5 Locations 5 Users 8 Tenants 2 Pos Keys 4 Integrations 7 Webhooks 8 Catalog 11 Catalog Sources 5 Catalog Payment/Delivery 10 Catalog Discounts 4 Orders 5 Import 5 Analytics 11 Dashboard 1 Audit 1 Consents 7 Referrals 1 Passes 3 Company Settings 4 Loyalty Settings 2 Referral Settings 2 Notification Settings 9 Backup 4 Member Portal 12 SuperAdmin Auth 11 SuperAdmin Tenants 6 SuperAdmin Admins 4 SuperAdmin Platform 3 SuperAdmin Settings 4 SuperAdmin Notifications 13 SuperAdmin Coalitions 5 SuperAdmin Translations 7 SuperAdmin Backup 6 Platform Info 1 Translations 3 Health 1 Metrics 1 Webhooks Bitrix24 5 Redemption 5

Auth

Method	Path	What it does
POST	/auth/register	Register a new company
POST	/auth/login	User login
GET	/auth/me	Current user profile
PUT	/auth/profile	Update own profile
POST	/auth/password	Change password
POST	/auth/refresh	Refresh JWT using refresh_token
POST	/auth/forgot-password	Request a password reset link
POST	/auth/reset-password	Set a new password using a token
POST	/auth/2fa/setup	Start 2FA setup
POST	/auth/2fa/confirm	Confirm 2FA setup
POST	/auth/2fa/disable	Disable 2FA
POST	/auth/2fa/verify	Verify 2FA at login
POST	/auth/logout	Log out and revoke refresh token

Members

Method	Path	What it does
GET	/members	List members
POST	/members	Register a new member
GET	/members/export	Export all members to CSV
POST	/members/bulk	Bulk create members (up to 500)
GET	/members/{memberId}	Member details
PUT	/members/{memberId}	Update member
POST	/members/{memberId}/activate	Activate member
POST	/members/{memberId}/deactivate	Deactivate member
GET	/members/{memberId}/card	Loyalty card (JSON with base64 QR code and barcode)
GET	/members/{memberId}/card/qr	Card QR code (PNG)
GET	/members/{memberId}/card/barcode	Code128 barcode (PNG)
GET	/members/{memberId}/referral-qr	QR code linking to the referral registration portal

Wallets

Method	Path	What it does
POST	/wallets/bulk/earn	Bulk point accrual (up to 100 operations)
POST	/wallets/bulk/redeem	Bulk point redemption
GET	/wallets/{walletId}/balance	Current wallet balance
POST	/wallets/{walletId}/earn	Accrue points
POST	/wallets/{walletId}/redeem	Redeem points
GET	/wallets/member/{memberId}	Wallet by memberId
POST	/wallets/member/{memberId}/earn	Accrue points by memberId
POST	/wallets/member/{memberId}/redeem	Redeem points by memberId
POST	/wallets/member/{memberId}/gift	Gift points to a member (admin gift)

Transactions

Method	Path	What it does
GET	/wallets/{walletId}/transactions	Wallet operation history
GET	/wallets/member/{memberId}/transactions	Member operation history
GET	/transactions	List all tenant transactions with filters

Tiers

Method	Path	What it does
GET	/tiers	All tenant tiers
POST	/tiers	Create tier
GET	/tiers/{id}	Tier details
PUT	/tiers/{id}	Update tier
DELETE	/tiers/{id}	Delete tier

Rules

Method	Path	What it does
GET	/rules	List rules
POST	/rules	Create rule
GET	/rules/{id}	Rule details
PUT	/rules/{id}	Update rule
DELETE	/rules/{id}	Archive rule
POST	/rules/{id}/activate	Activate rule
POST	/rules/{id}/deactivate	Deactivate rule
POST	/rules/dry-run	Dry-run a rule without saving
POST	/rules/{id}/simulate	Simulate an existing rule

Segments

Method	Path	What it does
GET	/segments	List segments
POST	/segments	Create segment
GET	/segments/{id}	Segment details
PUT	/segments/{id}	Update segment
DELETE	/segments/{id}	Delete segment
POST	/segments/{id}/recalculate	Recalculate segment membership
GET	/segments/{id}/members	Segment members

Campaigns

Method	Path	What it does
GET	/campaigns	List campaigns
POST	/campaigns	Create campaign
GET	/campaigns/{id}	Get campaign
PUT	/campaigns/{id}	Update campaign
DELETE	/campaigns/{id}	Delete campaign
POST	/campaigns/{id}/activate	Activate campaign
POST	/campaigns/{id}/pause	Pause campaign
POST	/campaigns/{id}/send	Schedule/launch a campaign send

Bonus Packages

Method	Path	What it does
GET	/bonus-packages	List bonus packages
POST	/bonus-packages	Create bonus package
GET	/bonus-packages/{id}	Get bonus package
PUT	/bonus-packages/{id}	Update bonus package
DELETE	/bonus-packages/{id}	Archive bonus package
POST	/bonus-packages/{id}/activate	Activate bonus package
POST	/bonus-packages/{id}/deactivate	Deactivate bonus package
POST	/bonus-packages/{id}/grant	Grant bonus package
POST	/bonus-packages/{id}/bulk-grant	Bulk grant bonus package
GET	/bonus-packages/{id}/grants	List bonus package grants

Date Triggers

Method	Path	What it does
GET	/date-triggers	List date triggers
GET	/date-triggers/{type}	Get date trigger
PUT	/date-triggers/{type}	Update date trigger
GET	/date-triggers/{type}/log	Get date trigger log
POST	/date-triggers/{type}/test	Test date trigger

Scenarios

Method	Path	What it does
GET	/scenarios	List scenarios
POST	/scenarios	Create scenario
GET	/scenarios/{id}	Get scenario
PUT	/scenarios/{id}	Update scenario
DELETE	/scenarios/{id}	Archive scenario
POST	/scenarios/{id}/activate	Activate scenario
POST	/scenarios/{id}/pause	Pause scenario
POST	/scenarios/{id}/start	Start scenario for member
GET	/scenarios/{id}/executions	List scenario executions

Message Templates

Method	Path	What it does
GET	/message-templates	List message templates
POST	/message-templates	Create message template
GET	/message-templates/{id}	Get message template
PUT	/message-templates/{id}	Update message template
DELETE	/message-templates/{id}	Archive message template

Locations

Method	Path	What it does
GET	/locations	List locations
POST	/locations	Create location
GET	/locations/{id}	Get location
PUT	/locations/{id}	Update location
DELETE	/locations/{id}	Delete location

Users

Method	Path	What it does
GET	/users	List users
POST	/users	Create user
GET	/users/{id}	Get user
PUT	/users/{id}	Update user
DELETE	/users/{id}	Delete user
POST	/users/{id}/roles	Assign role
DELETE	/users/{id}/roles/{roleId}	Remove role
GET	/roles	List roles

Tenants

Method	Path	What it does
POST	/tenants	Create a tenant (available to an authenticated user in self-service)
GET	/tenants/{id}	Get tenant

Pos Keys

Method	Path	What it does
GET	/pos-keys	List pos keys
POST	/pos-keys	Create a new POS key
DELETE	/pos-keys/{id}	Revoke key
POST	/pos-keys/{id}/rotate	Rotate key (new secret value)

Integrations

Method	Path	What it does
GET	/integrations	List integrations
POST	/integrations	Create integration
GET	/integrations/{id}	Get integration
PUT	/integrations/{id}	Update integration
DELETE	/integrations/{id}	Delete integration
POST	/integrations/{id}/test	Test connection
POST	/integrations/{id}/sync	Start synchronization

Webhooks

Method	Path	What it does
GET	/webhooks	List webhooks
POST	/webhooks	Create webhook
GET	/webhooks/{id}	Get webhook
PUT	/webhooks/{id}	Update webhook
DELETE	/webhooks/{id}	Delete webhook
POST	/webhooks/{id}/test	Test webhook
GET	/webhooks/{id}/logs	Webhook logs
POST	/webhooks/{webhookId}/logs/{logId}/retry	Retry webhook log

Catalog

Method	Path	What it does
GET	/catalog/products	List products
POST	/catalog/products/bulk	Bulk upload/update products
GET	/catalog/categories	List categories
POST	/catalog/categories	Create category
PUT	/catalog/categories/{id}	Update category
DELETE	/catalog/categories/{id}	Delete category
GET	/catalog/properties	List product properties
POST	/catalog/properties	Create product property
PUT	/catalog/properties/{id}	Update product property
DELETE	/catalog/properties/{id}	Delete product property
POST	/catalog/properties/bulk	Bulk product properties

Catalog Sources

Method	Path	What it does
GET	/catalog/sources	List catalog sources
POST	/catalog/sources	Create catalog source
PUT	/catalog/sources/{id}	Update catalog source
DELETE	/catalog/sources/{id}	Delete catalog source
POST	/catalog/sources/{id}/sync	Start source synchronization

Catalog Payment/Delivery

Method	Path	What it does
GET	/catalog/payment-types	List payment types
POST	/catalog/payment-types	Create payment type
PUT	/catalog/payment-types/{id}	Update payment type
DELETE	/catalog/payment-types/{id}	Delete payment type
POST	/catalog/payment-types/bulk	Bulk payment types
GET	/catalog/delivery-types	List delivery types
POST	/catalog/delivery-types	Create delivery type
PUT	/catalog/delivery-types/{id}	Update delivery type
DELETE	/catalog/delivery-types/{id}	Delete delivery type
POST	/catalog/delivery-types/bulk	Bulk delivery types

Catalog Discounts

Method	Path	What it does
GET	/catalog/products/{productId}/discounts	List product discounts
POST	/catalog/products/{productId}/discounts	Create product discount
PUT	/catalog/products/{productId}/discounts/{discountId}	Update product discount
DELETE	/catalog/products/{productId}/discounts/{discountId}	Delete product discount

Orders

Method	Path	What it does
GET	/catalog/orders/{id}	Order details
GET	/orders	List orders
POST	/orders/{id}/approve	Approve order
POST	/orders/{id}/cancel	Cancel order
POST	/orders/{id}/refund	Refund order

Import

Method	Path	What it does
POST	/import/upload	Upload a CSV for import
GET	/import/jobs	List import jobs
GET	/import/jobs/{id}	Get import job
POST	/import/header	Read headers of the uploaded CSV
POST	/import/mapping-preview	Preview column mapping

Analytics

Method	Path	What it does
GET	/analytics/rfm	Analytics rfm
GET	/analytics/dashboard	Analytics dashboard
GET	/analytics/revenue	Analytics revenue
GET	/analytics/members/growth	Analytics members growth
GET	/analytics/points/flow	Analytics points flow
GET	/analytics/cohorts	Analytics cohorts
GET	/analytics/ltv	Analytics ltv
GET	/analytics/churn	Analytics churn
GET	/analytics/rfm/members	Analytics rfm members
GET	/analytics/locations	Analytics locations
GET	/analytics/locations/{locationId}/transactions	Analytics location transactions

Dashboard

Method	Path	What it does
GET	/dashboard/stats	Dashboard stats

Audit

Method	Path	What it does
GET	/audit	List audit log

Consents

Method	Path	What it does
GET	/members/{memberId}/consents	Member consents
POST	/members/{memberId}/consents	Grant consent
DELETE	/members/{memberId}/consents/{type}	Revoke consent
GET	/members/{memberId}/consents/history	Consent change history
GET	/settings/consents	Tenant consent texts
POST	/settings/consents	Create a consent text version
PUT	/settings/consents/{id}	Update consent text

Referrals

Method	Path	What it does
GET	/referrals/stats	Referral stats

Passes

Method	Path	What it does
GET	/passes/types	List pass types
GET	/passes/member/{memberId}/apple	Apple Wallet .pkpass
GET	/passes/member/{memberId}/google	Google Pay save-link

Company Settings

Method	Path	What it does
GET	/settings/company	Get company settings
PUT	/settings/company	Update company settings
GET	/settings/privacy-jurisdiction	Get privacy jurisdiction
PUT	/settings/privacy-jurisdiction	Update privacy jurisdiction

Loyalty Settings

Method	Path	What it does
GET	/settings/loyalty	Get loyalty settings
PUT	/settings/loyalty	Update loyalty settings

Referral Settings

Method	Path	What it does
GET	/settings/referrals	Get referral settings
PUT	/settings/referrals	Update referral settings

Notification Settings

Method	Path	What it does
GET	/notifications/templates	List tenant notification templates
GET	/notifications/templates/{id}	Get tenant notification template
PUT	/notifications/templates/{id}	Customize tenant notification template
POST	/notifications/templates/{id}/reset	Reset tenant notification template
PUT	/notifications/templates/{id}/toggle	Toggle tenant notification template
POST	/notifications/templates/{id}/preview	Preview tenant notification template
GET	/notifications/channels	List tenant channels
PUT	/notifications/channels/{channel}	Update tenant channel
POST	/notifications/channels/{channel}/test	Test tenant channel

Backup

Method	Path	What it does
GET	/backup	List tenant backups
POST	/backup	Create tenant backup
GET	/backup/{date}	Download tenant backup
POST	/backup/{date}/restore	Restore tenant backup

Member Portal

Method	Path	What it does
POST	/portal/request-code	Request an SMS code to log in to the member portal
POST	/portal/verify-code	Verify the SMS code and get a portal_token
POST	/portal/register	Register a new member via the portal
GET	/portal/referrer-info	Referrer information by memberId
GET	/portal/member/{token}	Portal data by portal_token (token in path — legacy)
GET	/portal/member/{token}/transactions	Portal member transactions
GET	/portal/member/{token}/profile	Portal get profile
PUT	/portal/member/{token}/profile	Portal update profile
GET	/portal/me	Portal data by X-Portal-Token header
GET	/portal/me/transactions	Portal me transactions
GET	/portal/me/profile	Portal me get profile
PUT	/portal/me/profile	Portal me update profile

SuperAdmin Auth

Method	Path	What it does
POST	/super-admin/auth/login	Super admin login
POST	/super-admin/auth/verify-2fa	Super admin verify2fa
GET	/super-admin/auth/me	Super admin me
POST	/super-admin/auth/change-password	Super admin change password
GET	/super-admin/2fa/status	Super admin2fa status
POST	/super-admin/2fa/setup	Super admin2fa setup
GET	/super-admin/2fa/qr	Super admin2fa qr
POST	/super-admin/2fa/confirm	Super admin2fa confirm
PUT	/super-admin/2fa/method	Super admin2fa method
POST	/super-admin/2fa/resend	Super admin2fa resend
POST	/super-admin/2fa/disable	Super admin2fa disable

SuperAdmin Tenants

Method	Path	What it does
GET	/super-admin/tenants	Super admin list tenants
POST	/super-admin/tenants	Super admin create tenant
GET	/super-admin/tenants/{id}	Super admin get tenant
PUT	/super-admin/tenants/{id}	Super admin update tenant
POST	/super-admin/tenants/{id}/activate	Super admin activate tenant
POST	/super-admin/tenants/{id}/suspend	Super admin suspend tenant

SuperAdmin Admins

Method	Path	What it does
GET	/super-admin/admins	Super admin list admins
POST	/super-admin/admins	Super admin create admin
PUT	/super-admin/admins/{id}	Super admin update admin
DELETE	/super-admin/admins/{id}	Super admin delete admin

SuperAdmin Platform

Method	Path	What it does
GET	/super-admin/platform/stats	Super admin platform stats
GET	/super-admin/platform/health	Super admin platform health
GET	/super-admin/platform/logs	Super admin platform logs

SuperAdmin Settings

Method	Path	What it does
GET	/super-admin/settings	Super admin list settings
GET	/super-admin/settings/{key}	Super admin get setting
PUT	/super-admin/settings/{key}	Super admin update setting
POST	/super-admin/settings/smtp/test	Super admin test smtp

SuperAdmin Notifications

Method	Path	What it does
GET	/super-admin/notifications/channels	Super admin list notification channels
PUT	/super-admin/notifications/channels/{id}	Super admin update notification channel
GET	/super-admin/notifications/platform-templates	Super admin list platform templates
GET	/super-admin/notifications/platform-templates/grouped	Super admin platform templates grouped
GET	/super-admin/notifications/platform-templates/{id}	Super admin get platform template
PUT	/super-admin/notifications/platform-templates/{id}	Super admin update platform template
POST	/super-admin/notifications/platform-templates/{id}/preview	Super admin preview platform template
GET	/super-admin/notifications/default-templates	Super admin list default templates
GET	/super-admin/notifications/default-templates/grouped	Super admin default templates grouped
GET	/super-admin/notifications/default-templates/{id}	Super admin get default template
PUT	/super-admin/notifications/default-templates/{id}	Super admin update default template
POST	/super-admin/notifications/default-templates/{id}/preview	Super admin preview default template
GET	/super-admin/notifications/stats	Super admin notification stats

SuperAdmin Coalitions

Method	Path	What it does
GET	/super-admin/coalitions	Super admin list coalitions
POST	/super-admin/coalitions	Super admin create coalition
GET	/super-admin/coalitions/{id}	Super admin get coalition
POST	/super-admin/coalitions/{id}/tenants	Super admin add coalition tenant
DELETE	/super-admin/coalitions/{id}/tenants/{tenantId}	Super admin remove coalition tenant

SuperAdmin Translations

Method	Path	What it does
GET	/super-admin/translations/languages	Super admin list languages
GET	/super-admin/translations/{locale}	Super admin get translations
DELETE	/super-admin/translations/{locale}	Super admin delete locale
POST	/super-admin/translations/{locale}/upload	Super admin upload translations
GET	/super-admin/translations/{locale}/export	Super admin export translations
POST	/super-admin/translations/languages/{locale}/activate	Super admin activate language
POST	/super-admin/translations/languages/{locale}/deactivate	Super admin deactivate language

SuperAdmin Backup

Method	Path	What it does
GET	/super-admin/backup	Super admin list global backups
POST	/super-admin/backup	Super admin create global backup
POST	/super-admin/backup/{date}/restore	Super admin restore global backup
GET	/super-admin/backup/tenant/{tenantId}	Super admin list tenant backups
POST	/super-admin/backup/tenant/{tenantId}	Super admin create tenant backup
POST	/super-admin/backup/tenant/{tenantId}/{date}/restore	Super admin restore tenant backup

Platform Info

Method	Path	What it does
GET	/platform/info	Public platform information

Translations

Method	Path	What it does
GET	/translations/languages	List active languages
GET	/translations/{locale}	Translation dictionary for a locale
GET	/translations	Dictionaries for all languages

Health

Method	Path	What it does
GET	/health	Health check

Metrics

Method	Path	What it does
GET	/metrics	Prometheus metrics

Webhooks Bitrix24

Method	Path	What it does
POST	/webhooks/bitrix24/contact	Contact created/updated
POST	/webhooks/bitrix24/deal	Deal created/closed (generates a purchase)
GET	/webhooks/bitrix24/ping	Webhook bitrix24 ping
POST	/webhooks/bitrix24/contact/{tenantId}	Webhook bitrix24 contact tenant
POST	/webhooks/bitrix24/deal/{tenantId}	Webhook bitrix24 deal tenant

Redemption

Method	Path	What it does
POST	/redeem/request	Request an OTP code for bonus redemption
POST	/redeem/confirm	Confirm OTP code
POST	/redeem/commit	Finalize redemption (after order confirmation)
POST	/redeem/cancel	Release hold (order did not go through)
GET	/redeem/status/{redemption_id}	Redemption status

Till API /v2

What cash registers, shop sites and apps call: identify a buyer, quote a receipt, earn and redeem points, cancel and refund, promo codes and gift cards.

41 calls · Download the OpenAPI file

Customer 14 Purchase 10 Confirmation codes 5 Mobile app 3 Gift certificates 4 Additional 4 Service 1

Customer

Method	Path	What it does
POST	/buyer-register	Register a customer
POST	/buyer-info	Customer info
POST	/buyer-info-detail	Detailed customer info
POST	/buyer-info-messages	Customer message list
POST	/buyer-invite-code	Get MLM invitation code
POST	/buyer-edit	Update a customer
POST	/buyer/status-transition-info	Customer dynamic status info
POST	/buyer/purchase-list	Detailed customer purchase info
POST	/generate-order-code	Generate a customer code
POST	/card-activate	Activate a card
POST	/card-get-info	Get the customer's digital card
POST	/buyer-bonus	Customer bonus packages
POST	/buyer-groups	Get customer group list
POST	/present-bonus	Gift bonuses to a friend

Purchase

Method	Path	What it does
POST	/write-off-request	Get maximum available benefit (discounts + bonuses)
POST	/purchase-dry-run	Simulate a purchase
POST	/purchase-request	Get customer info + maximum available benefit (discounts + bonuses)
POST	/purchase	Create a purchase
POST	/purchase-set-external-id	Set or change the purchase external ID
POST	/edit-purchase	Update a purchase
POST	/cancel-purchase	Cancel a purchase
POST	/change-purchase-status	Change purchase status
POST	/reserve-info	Reserve info
POST	/purchase-info	Purchase info

Confirmation codes

Method	Path	What it does
POST	/send-register-code	Send a registration confirmation code
POST	/send-write-off-confirmation-code	Send a redemption confirmation code
POST	/verify-confirmation-code	Verify a registration or redemption confirmation code
POST	/send-custom-code	Send a custom confirmation code
POST	/verify-custom-code	Verify a custom confirmation code

Mobile app

Method	Path	What it does
POST	/get-orders	Get order list
POST	/change-order-status	Change order external status
POST	/send-push	Send a push notification to the customer's mobile app

Gift certificates

Method	Path	What it does
POST	/info	Get certificate info
POST	/pin-check	Verify PIN code
POST	/debit	Pay with certificate (redemption)
POST	/active	Sell a certificate (activation)

Additional

Method	Path	What it does
POST	/trigger	Fire a trigger
POST	/cashbox-list	Get point of sale list
POST	/city-list	Get cities and their IDs
POST	/promocode/activate-promocode	Activate a promo code for a customer

Service

Method	Path	What it does
GET	/health	Public liveness/readiness probe

POS API /pos/v1

A compact protocol for point-of-sale terminals: register a purchase, look up a member, hold and confirm a redemption.

16 calls · Download the OpenAPI file

(none) 11 Redemption 5

(none)

Method	Path	What it does
GET	/ping	Health check
POST	/balance	Get card balance
POST	/discounts	Calculate receipt discounts
POST	/purchase	Register a purchase
POST	/earn	Accrue bonuses
POST	/redeem	Redeem bonuses
POST	/reversal	Reverse an operation
GET	/members/search	Find a member by phone or card number
POST	/referral/lookup	Find a referrer by card QR/barcode
POST	/referral/register	Register a member linked to a referrer
POST	/register	Register a member

Redemption

Method	Path	What it does
POST	/redeem/request	Request an OTP code for bonus redemption
POST	/redeem/confirm	Confirm OTP code
POST	/redeem/commit	Finalize redemption after the receipt is closed
POST	/redeem/cancel	Release hold (customer declined / receipt cancelled)
GET	/redeem/status/{redemption_id}	Redemption status (diagnostics)