Integration guide

The references describe the shared Customer and Staff API contracts. Documentation is public; API access requires the business's enabled features and access grants. Ask the platform team to arrange access for the intended business and environment.

Business-specific setup

Before development, obtain the business name, environment (test or production), hosted API base URL, enabled features and test account details. For a customer app, also obtain that business app's X-App-Id and confirm whether phone, email or both sign-in methods are enabled. Agree how the developer will receive test verification codes.

For a staff app, obtain a personal test staff username, a password shared through a secure channel, the account's role and its authorized branch assignments. Discover branch IDs using the staff /branches endpoint. Customer branch path parameters use public ULIDs; staff branch_id parameters use the returned integer IDs. IDs and app IDs from one database/environment must not be assumed valid in another.

API documentation access does not activate a business or grant API permissions. Never send platform administrator credentials or provider secrets to an app developer. Customer and staff bearer tokens are obtained through their respective sign-in flows.

Customer app workflow

1. Obtain the business app's X-App-Id from the platform team. It identifies the app and does not authenticate a customer.
2. Send X-App-Id on every customer request. Load GET /config for enabled sign-in methods and app settings, and GET /branches for the paginated branch list.
3. Call POST /auth/start with an allowed email or phone identifier and the installation's stable device_id. Call POST /auth/verify with the returned challenge, delivered code and device details.
4. Store the returned token securely and send Authorization: Bearer YOUR_TOKEN on authenticated requests. Use GET /me for the customer's profile and membership. Loyalty endpoints require Loyalty access.
5. Use POST /auth/logout to revoke the current device token. A 401 requires sign-in again. If an endpoint returns 426 upgrade_required, follow its minimum app version requirement.

Phone sign-in must be enabled and have usable SMS configuration, or explicit per-app test OTP eligibility. Generated codes normally have six digits; only listed test phone numbers in an app with test mode enabled use 112233, without sending SMS. This exception never applies to email, identifier-linking or account-deletion codes. A phone option advertised in config does not make unlisted numbers eligible for a test code.

If sign-in returns app_verification_required, obtain a verification proof through the platform team's configured trusted issuer. Never embed server secrets in an app.

For an otherwise valid customer token, 403 account_unavailable with error.reason: suspended means the account is on hold: show the suspension screen and stop automatic retries. The same reason is returned by auth/verify or auth/complete after a correct verification code. auth/start does not reveal suspension. Missing, expired, revoked and wrong-business tokens remain 401 unauthenticated; do not interpret every 401 or 403 as suspension. A suspended profile cannot be fetched through /me, so use the error envelope rather than waiting for customer.status.

Using the Swagger explorer

Open the additional Swagger UI from the Customer or Staff detailed reference (or the documentation overview). Choose Customer Swagger or Staff Swagger, filter by path/keyword, and expand an operation to see its parameters, request body, examples and response schemas. In request/response examples, use the schema/model tab to inspect individual field descriptions and constraints. Use Download OpenAPI to import the same contract into your API client.

Select Authorize to enter the customer app ID and/or the token for the relevant API. Enter bearer tokens without the Bearer prefix; Swagger adds that header prefix. Customer app IDs identify the business app and do not sign a customer in. Staff requests need a staff token rather than an app ID. Authorization values are cleared on refresh and are never embedded in the public page.

Try it out sends real requests to the displayed server, using the credentials you enter. Interactive GET, POST, PUT, PATCH and DELETE operations are enabled in every environment, including the hosted development installation. You can sign in through the documented authentication endpoints, then enter the returned token in Authorize. Use dedicated test accounts in the agreed test environment: writes can create accounts, send verification codes and change business records. Existing API permissions and rate limits apply to every executed request.

Staff app workflow

1. Obtain a personal staff account from the business administrator.
2. Call POST /login with the username, password and device name. Staff requests use the Staff API base URL and do not send X-App-Id.
3. Store the returned bearer token securely. Fetch GET /config, GET /me and GET /branches to initialize the app. Re-fetch config after branch changes or authorization errors; cached capabilities do not authorize operations.
4. Assigned staff act within their own branch. Authorized business admins supply branch_id for operations that require a branch. Use only branches returned for the authenticated account.
5. Follow the documented customer lookup, purchase, points and voucher workflows. Use the customer's member code to buy a reward and the reward's code to redeem it. End the device session with POST /logout.

Staff access requires Internal App API Access. Loyalty operations additionally require Loyalty. Staff access is independent of a branded customer app and does not require an external POS API key.

Required fields when awarding points

Business managers control Require a bill amount and Require a bill reference under Loyalty Settings → Store App bill fields. Both settings default to on and can be changed independently. Changes are audited and apply to that business.

After sign-in, call GET /api/staff/v1/config. Show the award form only when capabilities contains points.award. Read the saved requirements from loyalty:

{
  "loyalty": {
    "points_label": "points",
    "redemption_model": "catalogue",
    "bill_amount_required": false,
    "bill_reference_required": false
  }
}

This example is a response excerpt for a business that made both fields optional; configuration schema_version remains 1. When awarding is unavailable or no branch is selected, loyalty is null.

Mark and validate each input according to its own flag. For an AED bill of 25.50, send amount: 2550; the server calculates the points. amount_paid_minor is prohibited on points/award; use that name for purchases and purchases/preview. Those staff endpoints apply the same amount requirement, with minimum 0 when a value is supplied. Staff purchases apply the same reference requirement; previews always allow an omitted reference. External POS requirements are unchanged.

When both flags are false, an award can be submitted with only the customer:

{ "customer": { "member_code": "48213906574" } }

The request still needs the staff bearer token and a stable Idempotency-Key. An omitted amount counts as zero spend. Existing per-visit rules, eligible fixed bonuses and zero-spend bands can still award points. Spend-based rules do not invent spending, and minimum-spend conditions still apply. If no earning rule qualifies, the accepted award earns zero points and still consumes one staff admission. A missing bill reference stays null; reference-based refunds and duplicate-bill detection need a reference recorded at submission. Idempotency, permissions and staff limits apply even when both fields are omitted.

Missing required fields return HTTP 422, error.code: invalid, with messages in error.fields.amount or error.fields.bill_reference. Show them beside the inputs. The server reads the current saved policy for every new submission; request flags cannot override it. Refresh config after branch or policy changes and validation/authorization errors. If config cannot load, show a retry state before enabling the form. Retry an uncertain award with the same key and payload; a successful historical retry returns the original result without awarding again.

In Staff Swagger, expand GET /config and select Awarding available, Optional bill fields, Branch selection required or Awarding unavailable. Expand POST /points/award for request examples and its 422 examples for field and amount errors. The detailed reference and Postman show the same responses.

Current capabilities and authorization

Use /config.capabilities or staff.permissions for operation aliases, not role labels. Legacy/shadow businesses keep legacy admission rules; enforced businesses apply current branch-scoped grants and denies. Staff can receive delegated actions and managers can lose actions. Neither a grant nor a cached capability widens branch scope or activates a missing feature/add-on. Refresh after branch changes or 403 errors.

For reversal, transactions.reverse can mean only one permitted target kind: earn/adjust reversal, points-purchased reward revocation, or voucher-use voiding. The server checks the exact target permission again, including before an idempotent replay. Bulk notifications additionally need current bulk permission; branch-bound staff remain limited to their branch's recipients.

A 503 authorization_unavailable with Retry-After: 3 means access settings could not be resolved; it does not grant legacy access. Retry with bounded backoff, keeping the same key/payload for writes. Do not fall back to cached role checks or issue a new key for an uncertain write.

Earning, corrections and queued notifications

Staff/POS purchases always record source pos; the compatibility channel input cannot select app-only rules. occurred_at, if supplied, must be within the preceding 24 hours and not in the future. Point holds and expiry use server processing time; current-day limits use the current business day.

API and dashboard till awards share each account's daily allowance, including zero-point bills. Identical retries do not consume another allowance. In enforced mode the separate loyalty.points.award_unlimited permission controls staff-limit exemption, independently of role; a supported-purchase maximum still applies. Treat amount/daily refusals as authoritative server decisions.

Use the bill refund workflow for milestone corrections. A refunded earn cannot also be reversed, and a reversed earn cannot subsequently be refunded; double correction returns 422 loyalty_action_not_allowed. A milestone-moving earn reversal returns 422 refund_required.

Manual notifications are reauthorized during queued audience work and before delivery. Revoking the actor's access blocks/skips later unsent unauthorized work; a 202 queued response is not a delivery guarantee. Revocation cannot recall provider requests already sent, and marketing push never falls back to SMS/WhatsApp.

Separate POS integrations

The Staff OpenAPI contract documents /api/staff/v1. External POS integrations use /api/loyalty/v1, a business API key and separate external POS access. Do not substitute a POS key for a staff token or assume all staff routes exist on the POS surface. Ask the platform team for the POS integration contract.

Requests, retries and data handling

• Send Accept: application/json and Content-Type: application/json for JSON bodies. All example identifiers, codes and credentials are fictional placeholders.
• Amounts use integer currency minor units. Use the documented public IDs and preserve their types. Dates and timestamps follow the endpoint schema.
• Follow pagination metadata and documented page-size limits. Honor Retry-After on 429 responses and use bounded backoff.
• Save one Idempotency-Key for each intended mutation where required. Retry the identical request with the same key after a connection failure. A changed payload with that key returns 409 idempotency_conflict; creating a new key can duplicate an uncertain operation.
• Handle HTTP status and error.code; do not parse display messages. Validation details are in error.fields where provided.
• Keep tokens, customer details, reward codes and wallet links private. Never put credentials in query strings or public logs. Use test accounts in the agreed test environment before issuing writes against production.

The endpoint reference and downloadable OpenAPI contracts contain request fields, response schemas, examples and endpoint-specific errors. Deployment, server configuration and credential provisioning remain platform-managed.