POS Integration

The POS integration lets your point-of-sale system register transactions directly via a REST API. Every time a customer pays, your POS calls the Xtarly endpoint and the customer instantly receives their points or stamps — no manual scanning required.

Getting your API key

1. Open your organization dashboard and go to Settings → General.
2. Scroll down to the POS Integration section.
3. Click Generate API key. The key is shown once — copy it immediately and store it securely (e.g. in your POS system's environment configuration).
4. If the key is ever compromised, click Rotate to invalidate the old key and generate a new one. If you already have a live key, you can rotate it even if your plan changes: you never lose the way to replace a leaked credential.

Base URL

All POS endpoints are served from your Xtarly domain:

https://www.xtarly.com/api/integrations/pos

Authentication

Include your API key in every request via the X-API-Key header:

X-API-Key: xtarly_pos_<your_key>

Requests without a valid key return 401 Unauthorized.

Endpoints

Register a transaction

POST /api/integrations/pos/transaction

Call this endpoint when a customer completes a purchase. Xtarly calculates the points or stamps earned based on your active reward program and credits them to the customer.

Request body

Provide either customerId or customerEmail — at least one is required.

Example request

curl -X POST https://www.xtarly.com/api/integrations/pos/transaction \
  -H "Content-Type: application/json" \
  -H "X-API-Key: xtarly_pos_<your_key>" \
  -d '{
    "amount": 35000,
    "customerEmail": "cliente@ejemplo.com",
    "metadata": { "ticket": "T-00412" }
  }'

Successful response 200 OK

{
  "success": true,
  "data": {
    "transactionId": "txn_abc123",
    "earnedPoints": 35,
    "earnedStamps": 0,
    "customerPoints": 210,
    "customerStamps": 0
  }
}

Look up a customer

GET /api/integrations/pos/customer/:id

Returns the current balance and tier of a customer. Useful to display loyalty status at the point of sale before or after a transaction.

Example request

curl https://www.xtarly.com/api/integrations/pos/customer/cus_abc123 \
  -H "X-API-Key: xtarly_pos_<your_key>"

Successful response 200 OK

{
  "success": true,
  "data": {
    "id": "cus_abc123",
    "name": "María García",
    "email": "cliente@ejemplo.com",
    "points": 210,
    "stamps": 0,
    "tier": null
  }
}

Point-of-sale endpoints

The same API key gives you access to the endpoints a connected point of sale uses: identifying the customer at the register, seeing what they can apply today, and redeeming coupons or rewards at checkout.

All four customer lookup endpoints return the same shape: id, name, email, phone, points, stamps and tier (the tier name, or null).

Crediting a sale from the POS

POST /api/integrations/pos/accrue

The response carries a status: ACCRUED when credited (with pointsAccrued and stampsAccrued), SKIPPED if that sale was already processed or there's no active program, and CUSTOMER_NOT_FOUND if no customer has that phone number.

What the customer can apply today

GET /api/integrations/pos/customer/benefits?customerId=cus_abc123

Returns, in a single call, the program type, the customer, their available coupons and every reward with the verdict already computed: attainable says whether they can redeem it right now, and if not, blockedReason and blockedMessage explain why (not enough points, tier not reached, already used this cycle…).

Each reward also includes a benefit object with the executable semantics of the discount — its type, its value and the menu products it applies to — so the POS can apply it on its own instead of leaving the math to the cashier.

Redeeming a coupon or a reward

POST /api/integrations/pos/coupon/redeem
POST /api/integrations/pos/reward/redeem

For a coupon, send couponId, saleId, amountCentavos and, optionally, customerId and branchName. A coupon flagged as walk-in can be redeemed without a customerId.

For a reward, send rewardId, customerId, saleId and, optionally, amountCentavos and branchName.

Both answer status: "REDEEMED" with the redemptionId, and DUPLICATE if that same sale had already redeemed. The reward redemption also returns pointsSpent, stampsSpent and the customer's balance after the redemption.

Points calculation

The points or stamps credited per transaction depend on your active program type:

You configure currencyUnit and pointsPerCurrency in Settings → Program.

Error codes