OPT Retention
For developers

API & Webhooks

Connect your POS, store or in-house system to OPT Retention: customers and sales recorded automatically, an instant webhook on every event. A key per integration, a request log, and replay on failure.

5-minute start

The API lets your POS, e-commerce store or any in-house system register customers and sales automatically in your account, and receive an instant webhook on every meaningful event: a sign-up, a sale, a redeemed reward, a review, an appointment — and keep your products and services catalog in sync, pictures as links, instead of retyping it (details).

  1. In the console: Admin → API & Webhooks. Included in the Pro plan, or as the "API access" add-on on other plans.
  2. Click + API key, name it (e.g. "Main branch POS") and choose scopes. The secret is shown once — copy it right away.
  3. Make your first call:
curl https://retention.aimenu.me/api/v1/customers?limit=5 \
  -H "Authorization: Bearer grs_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
Base URL: https://retention.aimenu.me/api/v1 · JSON in and out, UTF-8 · dates in ISO 8601 (2026-09-22T14:05:00Z) · amounts as integer minor units (amount_minor, halalas/piastres) or as a decimal (amount).

Authentication & scopes

Send the key as Authorization: Bearer <key> (or X-Api-Key). A key belongs to one business and can never see another.

ScopeAllows
customers:readList and search customers
customers:writeCreate a customer
transactions:writeRecord a sale (points are earned immediately)
catalog:readRead the stored products and services (catalog sync)
catalog:writePush / update / archive products and services from an external system
messages:writeSend a service message to a customer (e.g. "your order is ready")
branches:readList branches (customers:read also works)
customers:* / *Every scope of the group / everything

A key stops working automatically when the subscription lapses or the business moves to a plan without API access (403).

Customers

GET /api/v1/customers

Cursor-paginated list.

ParameterTypeDescription
limit1–100Page size (default 50)
cursorstringmeta.next_cursor from the previous page
searchstringMatches name or phone
lifecycle_statestringnew · active · at_risk · churned
{
  "ok": true,
  "data": [
    { "id": "cust_8f2…", "name": "Sarah Alotaibi", "phone": "+9665xxxxxxxx",
      "lifecycle_state": "active", "visit_count": 12, "points": 340,
      "last_visit_at": "2026-09-18T16:20:00Z", "return_due_at": "2026-10-02T16:20:00Z" }
  ],
  "meta": { "limit": 50, "count": 1, "next_cursor": null, "has_more": false }
}

GET /api/v1/customers/{id}

One customer, same shape. Unknown id → 404.

POST /api/v1/customers

FieldRequiredRules
nameyesup to 120 characters
phoneyesmobile number; normalised with the business's country code (05xxxxxxxx becomes +9665xxxxxxxx). Duplicate phone → 422
expected_return_daysno1–3650 (default 30) — this customer's expected return cycle
branch_idnoone of your branch ids
coupon_code / redemption_code / reward_idnoOne discount on the bill: a coupon, a reward voucher already issued to the customer, or a reward paid with points now. amount is the bill before the discount; points are earned on what was paid.
preferred_localenodefaults to ar-SA
curl -X POST https://retention.aimenu.me/api/v1/customers \
  -H "Authorization: Bearer grs_…" -H "Content-Type: application/json" \
  -d '{"name":"Sarah Alotaibi","phone":"0551234567"}'
# 201 → { "ok": true, "data": { "id": "cust_…", … } }

Bulk import

To move customers or past invoices from an old system in one go you do not need the API: the Data import page in the business console takes a CSV file or a paste from Excel up to 5,000 rows, shows a preview before applying, records invoices at their real date with no points and no messages, and gives every import an undo button. Use POST /customers and POST /transactions below for ongoing integration (a customer or a sale as it happens), and the import for the first batch.

Record a sale

POST /api/v1/transactions

Records a sale for the customer and immediately applies points, tier and referral rewards, then triggers the automations (post-visit thank-you, review request).

The Idempotency-Key header is required (8–128 characters, e.g. your invoice number or a UUID). Resending the same request with the same key never records the sale twice — it returns the original with "duplicate": true. Same key with different data → 409.
FieldRequiredRules
customer_idyesa customer id of your business
amount or amount_minoryes47.50 or 4750 (minor units) — greater than zero
currencyno3 letters; defaults to the business currency (SAR)
occurred_atnoISO 8601; defaults to now
external_transaction_idnoyour invoice number — stored, and also prevents duplicates
branch_idnodefaults to the customer's preferred branch
curl -X POST https://retention.aimenu.me/api/v1/transactions \
  -H "Authorization: Bearer grs_…" -H "Content-Type: application/json" \
  -H "Idempotency-Key: INV-2026-000123" \
  -d '{"customer_id":"cust_8f2…","amount":180.00,"external_transaction_id":"INV-2026-000123"}'
# 200 → { "ok": true, "data": { "transaction": { "id": "…", "amount_minor": 18000, "currency": "SAR", "status": "completed" }, "duplicate": false } }

POS tip: send the sale after the invoice is closed and use the invoice number as the idempotency key — retries after a network drop are then safe.

Point-of-sale integration

What an external POS needs on every bill: identify the customer from the card, see what can be taken off, apply one discount, and void the bill if it is cancelled. All examples use Authorization: Bearer grs_….

GET /api/v1/customers/lookup?qr=… or ?phone=…

The QR on the customer card is a link like https://retention.aimenu.me/scan?token=…. Send it as scanned, the bare token, or a local phone number. Returns the customer object; 404 when unknown. Scope customers:read.

GET /api/v1/customers/{id}/redeemables

Points balance, rewards (with affordable), active coupons, and reward vouchers already issued (vouchers with redemption_code).

POST /api/v1/discounts/check

{"customer_id":"…","amount":100.00,"coupon_code":"MISSU"}
# → {"kind":"coupon","label":"…","gross_minor":10000,"discount_minor":1500,"final_minor":8500,"points_cost":0,"points_balance":500}

Writes nothing. An invalid discount returns 422 with a cashier-readable reason. Then send POST /api/v1/transactions with the same field to apply it inside the sale. Scope transactions:write.

POST /api/v1/transactions/{id}/void

{id} is our transaction id or the external_transaction_id you sent. Gives back earned and spent points, the coupon and the reward, and emits transaction.voided. A second void changes nothing (duplicate: true). Only transactions recorded through the API.

POST /api/v1/notifications

Idempotency-Key: ORDER-A17-READY
{"customer_id":"…","type":"order_ready","order_number":"A-17","branch_id":"…"}
# 201 → {"duplicate":false,"channel":"whatsapp","status":"…","text":"…"}

A WhatsApp service message from the platform number. The same key never sends twice. Scope messages:write.

GET /api/v1/branches

The business branches: [{"id","name","status"}] — use id as branch_id.

Catalog sync (products & services)

Your system — a POS, a digital menu, a booking tool, an ERP — owns the master list of products and services, and nobody should retype it here. Sync makes the list on our side a follower copy of yours: name, description, category, price, SKU/barcode, duration (services), status, and the picture link. Pictures are never copied to our servers; we store the link and the customer's browser loads it from your host.

Two ways, one data format:
① Push — your system calls PUT /api/v1/catalog/sync with the whole list (or POST /api/v1/catalog/items for one item) whenever something changes, or on a schedule.
② Pull — you publish a JSON file at a stable HTTPS URL; the business owner registers it under Integrations → Catalog sync and we fetch it every 1–168 hours. No API key is needed on your side in this mode.

Scopes: catalog:write for pushing and archiving, catalog:read for reading. The capability follows the API feature; product items additionally need “Products & inventory” on the business plan and service items need “Bookings” — otherwise that item alone is refused with feature_not_available and the rest proceed.

Item identity: source + external_id

Every item is identified by its external_id — the stable identifier in your system (number, UUID, SKU), up to 64 characters — under one source: your system's identifier (e.g. main-pos; lowercase letters, digits, -/_; default api). The pair (source, external_id) is what we update later; never change external_id when the name or price changes. Two sources never overlap.

Smart linking (link_by_name, on by default): if the owner typed items by hand before connecting, the first sync adopts the hand-typed item that matches by name (or by SKU/barcode for products) instead of duplicating it, and tags it with your source. Send "link_by_name": false to disable.

Item fields

FieldTypeRequiredRules
external_idstringyesstable in your system, up to 64 chars
kindstringyesproduct or service
namestringyes2–80 chars for a product, 2–120 for a service
descriptionstringnoup to 300 chars
categorystringnocategory name, up to 40 chars. For services the category is created automatically when missing (no duplicates)
price or price_minordecimal / integerproducts: yes45.00 or 4500 (minor units). A service without a price is 0 with price_type: free
currencystringnoif sent it must equal the business currency, otherwise the item is refused
image_urlURLnohttps only, publicly reachable, no credentials, up to 600 chars. Stored as a link, never downloaded. null or absent = no picture (the business default shows)
statusstringnoactive (default) or archived — archiving hides the item from the POS and booking page without deleting its history
sortintegernodisplay order
updated_atISO 8601nokept for reference only
Products only: sku (letters/digits up to 32, unique per business) · barcode (4–32) · cost/cost_minor · vat_rate (15 or 0) · track_stock (defaults to false for synced items — stock stays in your system)
Services only: duration_min (5–600, default 30) · price_type (fixed · from · free) · bookable_online (default true)

What sync never touches (local fields the owner controls): stock tracking, low-stock threshold and stock movements, the staff who perform a service and its branches, the points multiplier, the buffer after a service, and a manually uploaded picture. Re-sending an unchanged item writes nothing (we compare a fingerprint of the synced fields).

PUT /api/v1/catalog/sync — push the list, whole or partial

curl -X PUT https://retention.aimenu.me/api/v1/catalog/sync \
  -H "Authorization: Bearer grs_…" -H "Content-Type: application/json" \
  -d '{
    "source": "main-pos",
    "mode": "replace",
    "items": [
      { "external_id": "P-1001", "kind": "product", "name": "Moisturising shampoo 250 ml",
        "category": "Hair care", "price": 45.00, "sku": "SH-250", "barcode": "6281000101011",
        "image_url": "https://cdn.your-pos.com/img/sh-250.jpg", "status": "active", "sort": 1 },
      { "external_id": "S-77", "kind": "service", "name": "Cut & style",
        "category": "Hair", "price": 80, "duration_min": 45, "price_type": "fixed",
        "image_url": "https://cdn.your-pos.com/img/cut.jpg" }
    ]
  }'
# 200 → { "ok": true, "data": { "source": "main-pos", "mode": "replace", "received": 2,
#         "created": 1, "updated": 1, "unchanged": 0, "archived": 3, "failed": 0, "errors": [] } }
ParameterDescription
sourceyour system's identifier (default api). Use one stable identifier per system
modemerge (default): adds and updates only what you sent. replace: additionally archives every item of the same source missing from this batch — use it when you send the full list. Never touches hand-typed items or other sources, never deletes
itemsup to 500 items per request. Split bigger lists into merge batches, or keep every batch merge and send removals explicitly with status: archived
link_by_namesmart linking, see above (default true)

The response is always 200 when the request itself is valid: refused items are counted in failed and detailed in errors (up to 50) with their position and reason, and the rest is saved. The whole request is refused with 422 only when items is not a list, exceeds 500, or mode/source is invalid.

"errors": [
  { "index": 3, "external_id": "P-9", "field": "image_url", "code": "invalid",
    "message": "The image link must start with https://" },
  { "index": 7, "external_id": "S-2", "field": "kind", "code": "feature_not_available",
    "message": "Services and booking are not available on the current plan" }
]

POST /api/v1/catalog/items — a single item

Same item fields, with an optional source in the body. Returns the item as stored: 201 when created, 200 when updated or unchanged, 422 with the field name on error, 403 feature_not_available when the kind is outside the plan.

curl -X POST https://retention.aimenu.me/api/v1/catalog/items \
  -H "Authorization: Bearer grs_…" -H "Content-Type: application/json" \
  -d '{"source":"main-pos","external_id":"P-1001","kind":"product","name":"Moisturising shampoo 250 ml","price":49.5,"sku":"SH-250"}'
# 200 → { "ok": true, "data": { "result": "updated", "item": { "id": "…", "kind": "product", "external_id": "P-1001", "price_minor": 4950, … } } }

DELETE /api/v1/catalog/items/{external_id}?source=main-pos

Archives the item (never deletes): it disappears from the POS and booking page and stays in past reports. Sending it again with status: active brings it back. Unknown for this source → 404.

GET /api/v1/catalog — read what is stored here

ParameterDescription
kindproduct · service (both by default)
sourceitems of one source only. Hand-typed items have "source": null
statusactive (default) · archived · all
updated_sinceISO 8601 — what changed after this time
limit · cursor1–200 (default 100) and cursor pagination as for customers
{ "ok": true,
  "data": [ { "id": "…", "kind": "product", "source": "main-pos", "external_id": "P-1001",
              "name": "Moisturising shampoo 250 ml", "description": "", "category": "Hair care",
              "price": "45.00", "price_minor": 4500, "currency": "SAR", "sku": "SH-250", "barcode": "6281000101011",
              "image_url": "https://cdn.your-pos.com/img/sh-250.jpg", "status": "active", "sort": 1,
              "cost_minor": 2000, "vat_rate": 15, "track_stock": false,
              "updated_at": "2026-09-22T10:00:00Z", "last_synced_at": "2026-09-22T10:00:00Z" } ],
  "meta": { "limit": 100, "count": 1, "next_cursor": null, "has_more": false } }

image_url in a read is the effective picture: the external link when present, otherwise the manually uploaded picture, otherwise null (apply your own default).

Pull: a catalog file we fetch

Publish, at a stable public HTTPS URL (optionally protected by a header such as Authorization: Bearer …, stored encrypted on our side), a document of this shape — the same item fields as above, either inside items or as a bare array:

GET https://pos.example.com/retention/catalog.json
Content-Type: application/json

{ "version": "1", "generated_at": "2026-09-22T10:00:00Z",
  "items": [
    { "external_id": "P-1001", "kind": "product", "name": "Moisturising shampoo 250 ml", "price": 45.00,
      "category": "Hair care", "sku": "SH-250", "image_url": "https://cdn.your-pos.com/img/sh-250.jpg" },
    { "external_id": "S-77", "kind": "service", "name": "Cut & style", "price": 80, "duration_min": 45 }
  ] }
  • Limits: 5 MB and 500 items per file; localhost and internal addresses are refused and redirects are not followed.
  • The owner picks, in the console: the source identifier, the mode (merge/replace) and the interval (every 1/3/6/12/24/48 hours or weekly), and can press “Sync now” at any time.
  • Failures (non-2xx, invalid JSON, missing items) are logged on the source card with the last 20 runs and never touch stored items.
  • Best practice: generate the file from your database on demand or by a scheduled job, and serve ETag/Cache-Control when you can.

Picture rules

  • A direct link to an image file (jpg/png/webp) over https, openable from any browser without a login, and stable across requests (no short-lived signed URLs).
  • Recommended: square, 600×600 or larger, under 300 KB. We neither resize nor copy; the picture shows as-is in the console, the POS screen, the booking page and the partner page.
  • Pictures show only when the owner enables Settings → Catalog display → “With pictures”; in text mode the links are stored but hidden. An item without a picture gets the business default picture.
  • If a link breaks later the browser falls back to the default picture automatically; send the new link on the next sync.

What happens after a sync

  • The item appears at once under Products/Services with a “Synced: source” tag, on the POS screen, on the booking page (services that are bookable online) and on the partner page.
  • A manual edit by the owner to a synced field (name, price…) is replaced on the next sync — local fields stay. Better to edit in your system, then sync.
  • Every batch records a catalog.synced event (delivered to webhooks subscribed to it) with the counts.
  • Stock is deliberately not part of sync: it stays in your system, and your items arrive with track_stock: false unless you send otherwise.

Catalog provider go-live checklist

  • external_id is stable and does not change with the name or price; one fixed source per system.
  • You send the full list with replace (or publish the complete pull file) so discontinued items leave the POS automatically.
  • Retries are safe: the same request twice never duplicates (the fingerprint skips what did not change).
  • Picture links are direct, stable https URLs, tested from a browser outside your network.
  • You watch failed/errors in the response (or the source card in the console) and fix refused items at the source.
  • Each item's currency is the business currency (or you do not send it at all).

Errors & limits

{ "error": { "code": "validation_failed", "message": "…",
             "request_id": "req_…", "fields": { "phone": ["must be a valid phone number"] } } }
HTTPcodeMeaning
401invalid_api_keyKey invalid or revoked
403insufficient_scope · feature_not_available · subscription_inactiveScope too narrow / plan without API (or a catalog item kind outside the plan) / subscription inactive
400idempotency_key_requiredHeader missing
404not_foundUnknown route or customer
409idempotency_conflictSame key, different data
422validation_failedInvalid fields — details in fields
429rate_limitedMore than 240 requests/minute for the key — back off and retry

Quote the request_id when contacting support.

Webhooks (outbound notifications)

On the same page click + Webhook: an HTTPS URL on your side plus the events you want (empty = all). The secret whsec_… is shown once — keep it to verify signatures.

Every event is delivered as a POST:

POST https://your-system.example/hooks/retention
Content-Type: application/json
User-Agent: RetentionOS-Webhook/1.0
X-Retention-Event: transaction.completed
X-Retention-Event-Id: evt_…
X-Retention-Signature: sha256=3f1a…

{ "event": "transaction.completed", "timestamp": "2026-09-22T14:05:00Z",
  "data": { "transaction_id": "…", "customer_id": "cust_…", "amount_minor": 18000, "gross_minor": 18000, "discount_minor": 0, "currency": "SAR" },
  "meta": { "event_id": "evt_…", "correlation_id": null } }
  • Answer 2xx within seconds, then process in the background. Anything else is retried automatically after 1 min, 5 min, 15 min, 1 h, 6 h (5 attempts).
  • A 4xx (other than 408/429) means your system rejected the event: no retry; it shows as "failed" in the console with a Replay button.
  • Events can arrive more than once — make handling idempotent using event_id.
  • The URL must be public HTTPS (no localhost or private addresses).

Event catalogue

EventWhenMain data fields
customer.createdCustomer sign-up (QR, Wi-Fi, POS, API)customer_id, display_name
customer.mergedTwo customers mergedsource_customer_id, target_customer_id
transaction.completedSale recorded (POS/manual/API)transaction_id, customer_id, amount_minor, gross_minor, discount_minor, currency
transaction.voidedSale voidedtransaction_id, customer_id
sale.paid / sale.refundedPlatform POS sale / refundnumber, total_minor, customer_id, invoice_id / amount_minor, full
reward.redeemedReward redeemedcustomer_id, reward_id, transaction_id
loyalty.adjustedManual points adjustmentcustomer_id, delta
tier.changedCustomer tier changedcustomer_id, to, direction
coupon.issued / coupon.usedCoupon issued / usedcustomer_id, coupon_id, code / transaction_id, discount_minor
referral.joined / referral.qualified / referral.rewardedFriend joined / bought / referrer rewardedreferrer_customer_id, referee_customer_id / transaction_id / grant_type
review.ratedPost-visit ratingcustomer_id, rating, positive
appointment.created / appointment.rescheduled / appointment.canceledBookingsappointment_id, customer_id, starts_at, source / by
catalog.syncedA catalog sync batch (push or pull)source, mode, received, created, updated, unchanged, archived, failed
game.wonSpin-the-wheel prizecustomer_id, prize, kind

Verify the signature

Signature = sha256= + HMAC-SHA256 of the raw request body with your whsec_… secret. Verify before doing anything else:

// PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_RETENTION_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($raw, true);
http_response_code(200); // then process $event in the background
// Node.js (Express — use the raw body, not the parsed one)
app.post('/hooks/retention', express.raw({ type: '*/*' }), (req, res) => {
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET).update(req.body).digest('hex');
  const given = req.get('X-Retention-Signature') || '';
  if (expected.length !== given.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(given))) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  res.sendStatus(200); // then process event
});

Go-live checklist

  • One API key per system (POS, store, ERP) with the narrowest scopes; any key can be revoked from the console without touching the others.
  • The invoice number is both the Idempotency-Key and external_transaction_id.
  • Create the customer first (or look them up by phone), then send the sale with their id.
  • The catalog comes from your system via PUT /catalog/sync or a pull file, with stable external_ids and https picture links — no double data entry.
  • The webhook handler answers 2xx immediately and ignores duplicates by event_id.
  • Watch the "API & Webhooks" page: last use per key, delivery health per webhook, and replay on failure.

Integration support: contact us with the request_id or event_id.