API Overview

The Shop API is a REST API over HTTPS. It is what an e-commerce platform or POS calls to award points, look up cards, handle coupons and run loyalty games.

The SMS API (/{locale}/sms/...) is a separate, smaller surface for sending transactional SMS; it uses the same credentials and the same response envelope.

Everything else on api.loyalty.lt — the admin dashboard, the Partners Portal backend, the marketing site feeds — is internal and not part of this documentation.

Base URL and locale

Environment	Base URL
Production	`https://api.loyalty.lt`
Staging	`https://staging-api.loyalty.lt`

Every path carries a locale segment, lt or en, which selects the language of message strings and any localised content in the response:

https://api.loyalty.lt/{locale}/shop/...
https://api.loyalty.lt/lt/shop/transactions/create

Authentication

Server-to-server calls use two headers:

X-API-Key: lty_xxxxxxxxxxxxxxxx
X-API-Secret: your_api_secret

A handful of customer-scoped endpoints use a JWT instead. See Authentication.

Response format

Every Shop and SMS API response uses the same envelope, and every response carries a request_id — successes included. Quote it when contacting support.

Success

{
  "success": true,
  "code": 200,
  "request_id": "9a3368ab-e969-4e84-8589-76cc7b74474e",
  "message": "Categories retrieved successfully",
  "data": []
}

message and data are only present when there is something to put in them, so treat both as optional. code here mirrors the HTTP status.

Paginated endpoints add meta between message and data:

{
  "success": true,
  "code": 200,
  "request_id": "9a3368ab-e969-4e84-8589-76cc7b74474e",
  "message": "Partners retrieved successfully",
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 2,
    "total": 5,
    "from": 1,
    "to": 2
  },
  "data": []
}

Error

{
  "success": false,
  "code": 1004,
  "message": "API key and secret are required.",
  "request_id": "9eb5d278-2a64-44d1-a436-abb5ea7f668e"
}

On an error, code is not the HTTP status — it is a numeric application code that says precisely what went wrong. Branch your control flow on the HTTP status, and use code when you need to tell two failures with the same status apart.

Range	Meaning
`1000`–`1009`	Authentication — invalid credentials, expired or blacklisted token
`1010`–`1029`	API credentials — missing, malformed, unknown key, wrong secret, expired
`1100`–`1199`	Validation
`1200`–`1299`	Resource — not found, already exists, conflict, gone, expired
`1300`–`1399`	Business rules — card blocked, insufficient points, limit exceeded

1004 (missing or invalid credentials) and 1100 (validation failed) are the two you will meet while wiring up an integration.

Validation errors

HTTP 422 carries code: 1100 and an errors object keyed by field name:

{
  "success": false,
  "code": 1100,
  "message": "The given data was invalid.",
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "errors": {
    "order_id": ["The order id field is required."],
    "points": ["The points must be at least 0."]
  }
}

Note

GET /{locale}/shop/system/health is the one exception — it answers with a bare status object (status, version, environment, services) and no envelope, so it stays readable from an uptime monitor.

HTTP status codes

Code	Meaning	What to do
`200` / `201`	Success	—
`401`	Missing or invalid credentials	Check the key/secret pair and the environment
`403`	Authenticated but not allowed	Credential lacks access, IP not allowlisted, or API not in plan
`404`	Not found	—
`422`	Validation failed	Read `errors` and fix the request
`429`	Throttled	Retry with exponential backoff
`5xx`	Server error	Retry with exponential backoff

Retry only 429 and 5xx. Never retry other 4xx responses — they will fail the same way. The official SDKs already do this for you, with exponential backoff.

Realtime

Not everything arrives as a reply. A QR code being scanned, a till updating the basket the customer is watching — those reach you over a WebSocket channel, not a response body. See Realtime.

Authentication

API credentials, JWT and QR login

Realtime

Channels, events and payloads

Staging

Test environment and demo data

Endpoints

Full reference, testable in the browser