NuqtaPass loyalty program API
A REST API for your loyalty program. Add stamps and points, look up cards, give rewards and connect your till. JSON over HTTPS, with an API key.
Base URL: https://sipcard-production-b91a.up.railway.app
Authentication
Send an API key with every request, in the Authorization header: Authorization: Bearer sip_…. Personal API Keys come with the Business plan. On Starter or Growth a key gets 403 PLAN_UPGRADE_REQUIRED, and when the shop's plan has ended it gets 403 PLAN_ENDED. A key used outside its scope gets 403 KEY_SCOPE. Clinics with the Solver HMIS add-on can make Solver keys on any plan; a Solver key only reaches /api/solver/*. On Starter and Growth, dashboard sign-in tokens only work from the NuqtaPass apps, so from a script they get 403 PLAN_UPGRADE_REQUIRED. Integrations must use API keys.
- Make a key: the shop owner or an admin opens API keys in the NuqtaPass dashboard (in the menu, and under Settings → Security). Name the key, choose when it expires (never, 30 or 90 days, 1 or 5 years) and copy it. It is shown once: NuqtaPass keeps only a hash of it.
- Scope full: every call on this page. The API keys page makes these keys.
- Scope pos: only the till API, /api/pos/*. Settings → Integrations → Odoo makes this key. It can't read your customer list or change your settings.
- Scope solver: only /api/solver/*, for Solver HMIS bills.
- Plans: full and pos keys need the Business plan. Shops that joined before plans keep them. If a shop moves to a smaller plan, its keys stop working until it is back on Business.
- A key acts as the person who made it, in their own shop only. It can't make more keys, change a password or two-step sign-in, or reset data.
- Revoke a key with Revoke on the API keys page (the Odoo key on its Odoo page). It stops at once: the next request gets 401. An expired key, or one whose owner's account is switched off, gets 401 too.
Loyalty cards
A loyalty card belongs to one shop and one phone number. A shop runs stamp cards (STAMPS) or points cards (POINTS, shown to customers as cashback). Prepaid credit and service packs are used on the till. A card's id is what its Wallet QR code holds (older passes hold the phone number). Every change updates the customer's Apple Wallet and Google Wallet pass within seconds.
- Phone numbers are E.164: a + and the country code, e.g. +96891234567.
- branchId is optional on the stamp, points and reward calls. Without it, the action is recorded at the key owner's branch, or at Main.
POST /api/join: Join a shop's loyalty program
The call the shop's join page makes when a customer signs up. It makes the customer's card, or returns the card they already have. It needs no key, but it needs the secret part of the shop's join link. An existing card only comes back to the device that made it (the same deviceId), or after a phone code.
- Auth: Public, no key
- Plan: Any plan that is still running
- shopId (body): string, required. The shop's id (uuid) or its slug.
- joinKey (body): string, required. The secret part of the shop's join link: /join/<slug>/<joinKey>.
- phone (body): string, required. The customer's number in E.164, e.g. +96891234567.
- deviceId (body): string, required. The device the card belongs to: "r1_" and 32 to 64 letters, digits, - or _.
- verifyToken (body): string, optional. From the phone or email code check, when the shop asks for a code.
- email (body): string, optional. With verifyToken, when the shop sends its code by email.
- branch (body): string, optional. The branch code from the join link (?b=).
- birthday (body): object, optional. { "day": 1-31, "month": 1-12 }.
- ref (body): string, optional. The code of the friend who shared the link.
- Error 400: phone is not E.164, deviceId or shopId is missing, or the shop has loyalty switched off
- Error 403 LINK_OUTDATED: the joinKey is wrong
- Error 403 SHOP_PAUSED: the shop's plan has ended or the shop is paused
- Error 403 VERIFY_NEEDED: the shop asks for a phone or email code first
- Error 403 HAS_CARD: the number already has a card here, on another device
- Error 404: no such shop
- Error 429 TOO_MANY_TRIES: too many numbers tried from this connection
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/join -H "Content-Type: application/json" -d '{"shopId":"nuqtapass-coffee","joinKey":"<joinKey>","phone":"+96891234567","deviceId":"r1_<32 to 64 characters>"}'
- Example response: { "success": true, "data": { "id": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "shopId": "…", "stamps": 0, "points": 0, "status": "ACTIVE", "issuedAt": "2026-11-15T09:30:00.000Z", "expiresAt": "2027-05-15T09:30:00.000Z", … } }
POST /api/stamp: Add a stamp
Adds one stamp to a stamp card. When the card is full, give the reward with POST /api/redeem/:cardId.
- Auth: API key in the header Authorization: Bearer sip_…, scope full
- Plan: Business
- cardId (body): string (uuid), required. The card id from the Wallet QR code.
- branchId (body): string, optional. One of your open branch ids. Without it: the key owner's branch, else Main.
- Error 400: cardId is not a card id
- Error 400 CARD_FULL: the card is full; give the reward first
- Error 400 CARD_INACTIVE: the card is used up or expired
- Error 400 WRONG_CARD_TYPE: not a stamp card
- Error 400 BRANCH_INVALID: branchId is not one of your open branches
- Error 403 OTHER_SHOP: the card belongs to another shop
- Error 403 SHOP_PAUSED: the shop's plan has ended or the shop is paused
- Error 404 CARD_NOT_FOUND: no such card
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/stamp -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"cardId":"5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10"}'
- Example response: { "success": true, "data": { "id": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "shopId": "…", "stamps": 4, "timesRedeemed": 1, "status": "ACTIVE", "expiresAt": "2027-05-15T09:30:00.000Z", …, "branch": { "id": "…", "name": "Main" } } }
POST /api/points: Add points for a purchase (cashback)
For points cards. Send the bill amount: the points follow the shop's rate and the card's tier. The customer must already hold a card at this shop. A number with no card here gets CARD_NOT_FOUND, and no card is made. tier is null when the shop's plan has no tiers.
- Auth: API key in the header Authorization: Bearer sip_…, scope full
- Plan: Business
- phone (body): string, required. The customer's number in E.164, e.g. +96891234567.
- amount (body): number, required. The bill in the shop's currency, above 0 and at most 100000.
- branchId (body): string, optional. One of your open branch ids. Without it: the key owner's branch, else Main.
- Error 400: phone or amount is missing, or amount is out of range
- Error 400 CARD_NOT_FOUND: no card for this number at this shop
- Error 400 WRONG_CARD_TYPE: the shop uses stamps, not points
- Error 400 POINTS_TOO_SMALL: the amount is too small for one point
- Error 403 SHOP_PAUSED: the shop's plan has ended or the shop is paused
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/points -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"phone":"+96891234567","amount":7.5}'
- Example response: { "success": true, "data": { "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "pointsAdded": 35, "totalPoints": 410, "totalPointsEarned": 1260, "tier": "Silver", "cashbackPct": 5, "branch": { "id": "…", "name": "Main" } } }
GET /api/points/balance/:phone: Look up a points card by phone
The customer's points, their points card id and how a purchase earns now. A customer of this shop with no points card gets points 0, cardId null and earn null.
- Auth: API key in the header Authorization: Bearer sip_…, scope full
- Plan: Business
- phone (path): The customer's number in E.164, with the +.
- Error 404: no card for this number at this shop
- Example request: curl -H "Authorization: Bearer $NUQTAPASS_API_KEY" https://sipcard-production-b91a.up.railway.app/api/points/balance/+96891234567
- Example response: { "success": true, "data": { "points": 410, "totalPointsEarned": 1260, "phone": "+96891234567", "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "earn": { "tier": "Silver", "pct": 5, "cashbackPct": 5, "pointsRate": 1, "pointsRedemptionRate": 0.01 } } }
POST /api/points/redeem: Spend points (give cashback)
Takes points off the customer's points card. omrValue is what they were worth, in the shop's currency. The shop's per-visit cap applies to counter staff only, so a key made by the owner or an admin is not capped.
- Auth: API key in the header Authorization: Bearer sip_…, scope full
- Plan: Business
- phone (body): string, required. The customer's number in E.164, e.g. +96891234567.
- pointsToRedeem (body): number, required. A whole number of points above 0.
- branchId (body): string, optional. One of your open branch ids. Without it: the key owner's branch, else Main.
- Error 400: phone or pointsToRedeem is missing, or not a whole number
- Error 400 CARD_NOT_FOUND: no points card for this number at this shop
- Error 400 WRONG_CARD_TYPE: the shop uses stamps, not points
- Error 400: not enough points, or over the per-visit cap (the error says which)
- Error 403 SHOP_PAUSED: the shop's plan has ended or the shop is paused
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/points/redeem -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"phone":"+96891234567","pointsToRedeem":200}'
- Example response: { "success": true, "data": { "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "pointsRedeemed": 200, "omrValue": 2, "remainingPoints": 210, "branch": { "id": "…", "name": "Main" } } }
POST /api/redeem/:cardId: Give a reward or use a voucher
On a full stamp card it gives the reward, and the stamps start again from 0. On a voucher card it uses the voucher once; the last use ends it. For points cards, use POST /api/points/redeem.
- Auth: API key in the header Authorization: Bearer sip_…, scope full
- Plan: Business
- cardId (path): The card id (uuid).
- branchId (body): string, optional. One of your open branch ids. Without it: the key owner's branch, else Main.
- Error 400: the card is not full yet ("Need 6 stamps to redeem")
- Error 400 CARD_INACTIVE: the card is used up or expired
- Error 400 WRONG_CARD_TYPE: a points, prepaid or pack card
- Error 403 OTHER_SHOP: the card belongs to another shop
- Error 403 SHOP_PAUSED: the shop's plan has ended or the shop is paused
- Error 404 CARD_NOT_FOUND: no such card
- Error 409 VOUCHER_SAME_PHONE: this iPhone already used this offer
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/redeem/5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10 -H "Authorization: Bearer $NUQTAPASS_API_KEY"
- Example response: { "success": true, "data": { "id": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "stamps": 0, "timesRedeemed": 2, "status": "ACTIVE", …, "branch": { "id": "…", "name": "Main" } } }
GET /api/card/:cardId: Get a card by id
The card as its customer sees it: stamps, points, credit, status, dates and the shop's design. It is public, so it never shows the phone number or the staff history, and an API key adds nothing. To find the customer behind a scanned card, use GET /api/pos/customer?card=.
- Auth: Public, no key
- Plan: Any
- cardId (path): The card id (uuid).
- Error 404 CARD_NOT_FOUND: no such card
- Example request: curl https://sipcard-production-b91a.up.railway.app/api/card/5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10
- Example response: { "success": true, "data": { "id": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "shopName": "NuqtaPass Coffee", "loyaltyMode": "STAMPS", "stamps": 4, "stampsRequired": 6, "points": 0, "status": "ACTIVE", "expiresAt": "2027-05-15T09:30:00.000Z", "history": [{ "kind": "stamp", "amount": 1, "at": "2026-11-15T09:30:00.000Z" }], … } }
Till API (POS and Odoo)
The till API connects a point-of-sale system. The NuqtaPass app for Odoo uses it. Send each paid order and refund, and NuqtaPass gives or takes back stamps and points by itself. Use a pos key or a full key. The key must belong to the shop owner or an admin, and the shop must be on Business.
- What an order gives follows the shop's card. A stamp card gets one stamp when the order is at or above the stamp minimum. A points card gets points by amount, at the shop's rate and the card's tier. Prepaid and pack cards get nothing on payment: they are used with POST /api/pos/redeem.
- A number that isn't a customer yet gets a card on their first order that earns something. That answer has newCustomer: true and welcome links for adding the card to a phone.
- Orders and refunds are safe to send again. The same orderRef (or refundRef) returns the first answer, with duplicate: true and HTTP 200. Used for a different order, it gets 409 REF_CONFLICT. While the first attempt is still running, it gets 409 IN_PROGRESS: send it again a little later.
- source must be "odoo": it is the only value the API accepts today.
- The order log, retry, stats and settings (/api/pos/transactions, /api/pos/stats, /api/pos/settings) belong to the dashboard's Odoo page. API keys get 403 KEY_SCOPE there.
GET /api/pos/ping: Check the key and the shop
Checks the key, the plan and the shop, and writes nothing. It returns the shop's card type, currency, stamp minimum and open branches. Call it when you set up the connection.
- Auth: API key in the header Authorization: Bearer sip_…, scope pos or full
- Plan: Business
- Error 403 PLAN_UPGRADE_REQUIRED: the shop is not on Business
- Error 403 PLAN_ENDED, SUBSCRIPTION_EXPIRED: the shop's plan has ended or the shop is paused
- Error 403 ADMIN_REQUIRED: the key's owner is not the shop owner or an admin
- Error 403 LOYALTY_NOT_ENABLED: the shop has loyalty switched off
- Example request: curl -H "Authorization: Bearer $NUQTAPASS_API_KEY" https://sipcard-production-b91a.up.railway.app/api/pos/ping
- Example response: { "success": true, "data": { "ready": true, "shop": { "id": "…", "name": "NuqtaPass Coffee" }, "cardType": "STAMPS", "vouchers": true, "stampMinimum": 1, "currency": { "symbol": "OMR", "decimals": 3 }, "branches": [{ "id": "…", "code": "main", "name": "Main" }], "defaultBranch": { "till": "Odoo", "online": "Odoo online" }, "authenticatedAs": "owner@example.com" } }
POST /api/pos/sale: Send a paid order
Gives the stamp or points the order earns. status is OK when something was given, or NOTHING with result.reason and result.note saying why (below the stamp minimum, too small for a point, a prepaid or pack card). HTTP 201 for a new order, 200 for a resend.
- Auth: API key in the header Authorization: Bearer sip_…, scope pos or full
- Plan: Business
- source (body): string, required. "odoo".
- channel (body): string, required. "till" or "online".
- orderRef (body): string, required. Your order reference, 1 to 120 characters, unique per order.
- phone (body): string, required. The customer's number in E.164, e.g. +96891234567.
- amount (body): number or decimal string, required. The amount paid, above 0 and at most 100000.
- paidAt (body): string, optional. ISO 8601 date and time of payment.
- branch (body): string, optional. A branch id, code or name. Unknown: recorded as "Odoo" (or "Odoo online").
- customerName (body): string, optional. Up to 120 characters.
- Error 400 INVALID_SOURCE, INVALID_CHANNEL, MISSING_ORDER_REF, INVALID_REF, MISSING_PHONE, INVALID_PHONE, INVALID_AMOUNT: a field is missing or not valid
- Error 403 PLAN_UPGRADE_REQUIRED: the shop is not on Business
- Error 403 PLAN_ENDED, SUBSCRIPTION_EXPIRED: the shop's plan has ended or the shop is paused
- Error 403 ADMIN_REQUIRED: the key's owner is not the shop owner or an admin
- Error 403 LOYALTY_NOT_ENABLED: the shop has loyalty switched off
- Error 409 REF_CONFLICT: this orderRef was already used for a different order
- Error 409 IN_PROGRESS: this order is still being processed; send it again later
- Error 422: the order could not be processed; details.transactionId names it, and sending it again retries it
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/pos/sale -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"source":"odoo","channel":"till","orderRef":"Order 00042-003-0007","phone":"+96891234567","amount":"4.500"}'
- Example response: { "success": true, "data": { "transactionId": "…", "kind": "SALE", "orderRef": "Order 00042-003-0007", "refundRef": null, "status": "OK", "result": { "cardType": "STAMPS", "stamps": 1, "stampMinMilli": 1000, "newCustomer": true }, "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "duplicate": false, "welcome": { "cardUrl": "https://nuqtapass.com/card/5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "sms": "…", "whatsapp": "…", "message": "…" } } }
POST /api/pos/refund: Send a refund
Takes back what the order gave: all of it for a full refund, a share for a partial one, never below zero. It also gives back what the order used at payment. What can't be taken back (points already spent, a stamp already in a reward) is in result.shortfall. A refund of an order NuqtaPass never got answers NOTHING.
- Auth: API key in the header Authorization: Bearer sip_…, scope pos or full
- Plan: Business
- source (body): string, required. "odoo".
- orderRef (body): string, required. The orderRef of the sale being refunded.
- refundRef (body): string, required. Your refund reference, 1 to 120 characters, unique per refund.
- amount (body): number or decimal string, required. The amount refunded, above 0. It may be 0 only when returnUses names something.
- channel (body): string, optional. "till" or "online". Default: the sale's.
- refundedAt (body): string, optional. ISO 8601 date and time.
- orderAmount (body): number, optional. The whole order's amount, when NuqtaPass never got the sale.
- returnUses (body): object, optional. What the refunded lines gave back: { "points": 0, "credit": 0, "pack": 0, "reward": false, "vouchers": ["<card id>"] }. Without it, uses come back in proportion to the amount.
- Error 400 INVALID_SOURCE, MISSING_ORDER_REF, MISSING_REFUND_REF, INVALID_REF, INVALID_AMOUNT, INVALID_RETURN_USES, INVALID_ORDER_AMOUNT: a field is missing or not valid
- Error 403 PLAN_UPGRADE_REQUIRED: the shop is not on Business
- Error 403 PLAN_ENDED, SUBSCRIPTION_EXPIRED: the shop's plan has ended or the shop is paused
- Error 403 ADMIN_REQUIRED: the key's owner is not the shop owner or an admin
- Error 403 LOYALTY_NOT_ENABLED: the shop has loyalty switched off
- Error 409 REF_CONFLICT: this refundRef was already used for a different refund
- Error 409 IN_PROGRESS: this refund is still being processed; send it again later
- Error 422: the refund could not be processed; details.transactionId names it
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/pos/refund -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"source":"odoo","orderRef":"Order 00042-003-0007","refundRef":"Order 00042-003-0007 REFUND","amount":"4.500"}'
- Example response: { "success": true, "data": { "transactionId": "…", "kind": "REFUND", "orderRef": "Order 00042-003-0007", "refundRef": "Order 00042-003-0007 REFUND", "status": "OK", "result": { "cardType": "POINTS", "points": 35, "plannedPoints": 35 }, "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "duplicate": false, "pointsReturned": 0, "creditReturned": 0, "usesReturned": 0, "rewardReturned": false, "vouchersReturned": 0, "rewardNotReturned": false } }
GET /api/pos/customer: Look up a customer's cards by phone or card id
The customer's active cards at this shop, with balances, rewards and vouchers. current marks the card each action uses. When their loyalty card isn't on a phone yet, cardUrl and welcome give the link to add it. Only customers who hold a card here are found.
- Auth: API key in the header Authorization: Bearer sip_…, scope pos or full
- Plan: Business
- phone (query): string. The customer's number in E.164 (encode the + as %2B).
- card (query): string (uuid). A card id scanned from a Wallet card. Send phone or card, not both.
- Error 400 MISSING_PHONE, INVALID_PHONE, INVALID_CARD, PHONE_OR_CARD: phone or card is missing or not valid, or both were sent
- Error 403 PLAN_UPGRADE_REQUIRED: the shop is not on Business
- Error 403 PLAN_ENDED, SUBSCRIPTION_EXPIRED: the shop's plan has ended or the shop is paused
- Error 403 ADMIN_REQUIRED: the key's owner is not the shop owner or an admin
- Error 403 LOYALTY_NOT_ENABLED: the shop has loyalty switched off
- Error 404 CARD_NOT_FOUND: no card for this customer at this shop
- Example request: curl -H "Authorization: Bearer $NUQTAPASS_API_KEY" "https://sipcard-production-b91a.up.railway.app/api/pos/customer?phone=%2B96891234567"
- Example response: { "success": true, "data": { "phone": "+96891234567", "walletAdded": true, "cardUrl": null, "welcome": null, "cards": [ { "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "type": "POINTS", "current": true, "stamps": 0, "stampsRequired": 6, "rewardReady": false, "points": 410, "pointsValue": 4.1, "pointsPerUnit": 100, "balance": 0, "packUses": 0, "usesLeft": 0, "unit": null, "voucher": null, "rewardText": null, "tier": { "name": "SILVER", "cashbackPct": 5, "next": { "name": "GOLD", "pointsToGo": 3740 } } } ], "currency": { "code": "OMR", "symbol": "OMR", "decimals": 3 }, "limits": { "pointsPerVisit": null } } }
POST /api/pos/redeem: Give a reward, use a voucher, credit or a pack
Uses something from a card found with GET /api/pos/customer. "reward" gives a full stamp card's reward, or spends points on a points card. "voucher" uses a voucher card. "credit" and "pack" spend prepaid credit or pack uses and need an orderRef. With an orderRef, each use counts once per order, comes back if the order is refunded, and the answer adds transactionId, orderRef, use and duplicate.
- Auth: API key in the header Authorization: Bearer sip_…, scope pos or full
- Plan: Business
- phone (body): string, required. The customer's number in E.164, e.g. +96891234567.
- cardId (body): string (uuid), required. A cardId from GET /api/pos/customer.
- action (body): string, required. "reward", "voucher", "credit" or "pack".
- points (body): number. Whole points above 0. Required for a points reward.
- voucherId (body): string (uuid), optional. The voucher the card should be for.
- orderRef (body): string. The order this use is for. Required for credit and pack.
- amount (body): number. Credit to spend, in the shop's currency. Required for credit.
- uses (body): number, optional. Pack uses, 1 to 10. Default 1.
- branch (body): string, optional. A branch id, code or name.
- Error 400 INVALID_CARD_ID, INVALID_ACTION, INVALID_POINTS, INVALID_VOUCHER_ID, INVALID_USES, MISSING_ORDER_REF: a field is missing or not valid
- Error 400 WRONG_CARD_TYPE, VOUCHER_MISMATCH: the action does not fit this card
- Error 400 CARD_INACTIVE, or no code ("Need 6 stamps to redeem", not enough points): the till's own refusal, word for word
- Error 403 PLAN_UPGRADE_REQUIRED: the shop is not on Business
- Error 403 PLAN_ENDED, SUBSCRIPTION_EXPIRED: the shop's plan has ended or the shop is paused
- Error 403 ADMIN_REQUIRED: the key's owner is not the shop owner or an admin
- Error 403 LOYALTY_NOT_ENABLED: the shop has loyalty switched off
- Error 404 CARD_NOT_FOUND: no such card for this customer here
- Error 409 CARD_MISMATCH: points are spent from the customer's current points card; look the customer up again
- Error 409 VOUCHER_SAME_PHONE: this iPhone already used this offer
- Error 409 IN_PROGRESS, REF_CONFLICT, ORDER_REFUNDED: with an orderRef, the use is in progress, differs from the first, or the order was refunded
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/pos/redeem -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"phone":"+96891234567","cardId":"5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10","action":"reward"}'
- Example response: { "success": true, "data": { "action": "reward", "type": "STAMPS", "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "stamps": 0, "timesRedeemed": 3 } }
POST /api/pos/adjust: Correct a stamp or points
A manager's correction: add or undo one stamp, or add or take points, with a reason. It is no visit and no sale. A take-off never goes below zero, so delta in the answer can be less than asked. Every correction is in the dashboard's Activity log. Prepaid credit and pack uses are never corrected: use a sale or a refund.
- Auth: API key in the header Authorization: Bearer sip_…, scope pos or full
- Plan: Business
- cardId (body): string (uuid), required. A cardId from GET /api/pos/customer.
- action (body): string, required. "stamp_add", "stamp_undo" or "points".
- delta (body): number. Whole points other than 0, at most 1000000 either way. Required for "points".
- reason (body): string, required. Why, 3 to 200 characters.
- staffName (body): string, optional. Who made it, for the Activity log.
- Error 400 INVALID_CARD_ID, INVALID_ACTION, INVALID_DELTA, MISSING_REASON, INVALID_REASON: a field is missing or not valid
- Error 400 NOT_ADJUSTABLE, WRONG_CARD_TYPE: a prepaid, pack or voucher card, or the wrong action for this card
- Error 400 CARD_FULL, CARD_INACTIVE, or "No stamps to undo"
- Error 403 PLAN_UPGRADE_REQUIRED: the shop is not on Business
- Error 403 PLAN_ENDED, SUBSCRIPTION_EXPIRED: the shop's plan has ended or the shop is paused
- Error 403 ADMIN_REQUIRED: the key's owner is not the shop owner or an admin
- Error 403 LOYALTY_NOT_ENABLED: the shop has loyalty switched off
- Error 404 CARD_NOT_FOUND: no such card at this shop
- Example request: curl -X POST https://sipcard-production-b91a.up.railway.app/api/pos/adjust -H "Authorization: Bearer $NUQTAPASS_API_KEY" -H "Content-Type: application/json" -d '{"cardId":"5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10","action":"points","delta":-50,"reason":"Double scan at the till"}'
- Example response: { "success": true, "data": { "action": "points", "cardId": "5f0c2a9e-1b7d-4c43-9a51-3e8f6d2b7c10", "type": "POINTS", "delta": -50, "points": 360, "totalPointsEarned": 1260 } }
Rate limits
Limits count requests in a one-minute window. Past a limit the answer is 429: wait a minute and send again.
- POST /api/join: 10 a minute per IP address.
- POST /api/stamp and POST /api/points: 30 a minute each, per IP address.
- /api/card/*: 300 a minute per IP address, for all card routes together.
- /api/pos/*: 120 a minute per key (429 with code RATE_LIMITED), and 240 a minute per IP address on each route.
Errors
Every answer is JSON. A success is { "success": true, "data": … }. A failure is { "success": false, "error": "…", "code": "…" }: error is a plain sentence, and code is a stable name to act on. A few simple refusals (no key, a bad field, a rate limit) send error only, so check success first. Every response has an X-Request-Id header, and most till API errors repeat it as requestId. Quote it when you ask us for help.
- 400: A field is missing or not valid. Card refusals use 400 too, with a code such as CARD_FULL, CARD_INACTIVE, WRONG_CARD_TYPE or POINTS_TOO_SMALL.
- 401: No API key, or the key is wrong, expired or revoked.
- 403: The key works but can't do this. KEY_SCOPE: the key's scope doesn't reach this route. PLAN_UPGRADE_REQUIRED: the shop's plan doesn't include it (a key on Starter or Growth, or a dashboard sign-in token used outside the NuqtaPass apps). PLAN_ENDED: the shop's plan has ended. OTHER_SHOP: the card belongs to another shop. SHOP_PAUSED: the shop is paused.
- 404: No such card, customer or shop (CARD_NOT_FOUND for cards).
- 409: A conflict on the till API: REF_CONFLICT, IN_PROGRESS, CARD_MISMATCH, ORDER_REFUNDED or VOUCHER_SAME_PHONE.
- 422: The till API took the order but could not process it. details.transactionId names it; send the same order again to retry.
- 429: Too many requests. Wait a minute and send again.
- 500: Something failed on our side. The answer never carries internal details.