Custom POS Loyalty Integration — Verified API for POS Vendors | OwnRewards

For merchants

Merchants keep your billing screen. Loyalty rides alongside — lookup, redeem, earn, reverse — without leaving the ticket.

For POS vendors

You become the POS that ships enterprise retention. Co-market with us; partner pricing available.

What you enable

Every OwnRewards feature — offered through your counter.

You don't rebuild loyalty. You open the pipe. Merchants configure programs in OwnRewards; your POS becomes the place they earn and redeem.

Points & cashback
Earn on every closed bill — with a margin rulebook (OTP, caps, stacking) so generosity doesn't eat the ticket.
See feature
Rewards & coupons
Catalog redemptions and ruled coupons validated before payment — shared festival codes or unique per customer.
See feature
VIP tiers
Status ladders that upgrade automatically — celebrate in WhatsApp and show progress in the member app.
See feature
WhatsApp loyalty
Balance updates, OTPs and win-backs on the app customers actually open — quiet hours and credits enforced.
See feature
Member app
Branded PWA — points card, coupon wallet, referrals. No app store.
See feature
Automations & journeys
Birthday, silence win-back, points-expiring — set once in OwnRewards; your POS just posts the bill.
See feature
Feedback → Google
Post-visit forms after the bill; 2★ recovery stays private, 5★ gets a Google path.
See feature
Analytics merchants trust
Cohorts, at-risk lists, dual loyalty ROI — retention they can prove from the same bills you already send.
See feature

Counter loop

Four calls. Full loyalty at the till.

Do not redeem by only posting a bill — redemption goes through cart-checkout. Earn happens after payment on save-own-bill.

1
Phone on the ticket
Cashier enters the customer phone. POS calls cart-validate — balance, eligible rewards and coupons come back in one response.
POST /loyalty-redeem/cart-validate
2
Apply offer + OTP
Customer picks points, a reward or a coupon. Optional OTP confirms high-value redemptions. Discount lands on the ticket before payment.
POST /loyalty-redeem/cart-checkout
3
Bill closes → earn
After payment, POS posts the closed bill with a unique order id and stable itemIds. Points credit; WhatsApp fires.
POST /loyalty-bill/save-own-bill
4
Cancel / return
Void or return? Call order/return — loyalty reverses cleanly. Duplicate bill posts return 409 and credit nothing twice.
POST /v1/loyalty/order/return

API surface

Open APIs you call — plus one catalog URL you host.

Live reliability suite · 11/11

Job	Endpoint	Notes
Pre-bill lookup	POST /loyalty-redeem/cart-validate	Points, redeemable balance, eligible rewards & wallet coupons
Typed coupon check	POST /loyalty-redeem/validate-coupon	Shared or unique codes before apply
Redeem + OTP	POST /loyalty-redeem/cart-checkout	Apply reward / points / coupon; OTP when outlet requires it
Bill earn	POST /loyalty-bill/save-own-bill	billStructureId auth · unique order id · line items with itemId
Cancel / return	POST /v1/loyalty/order/return	API key · reverses earn/redeem safely
Product catalog	You host HTTPS catalog	OwnRewards pulls; register catalogUrl + Bearer token
Custom events	POST /events/publish	Optional — birthdays, visits, custom triggers
Outbound webhooks	Platform webhooks (HMAC)	Earn, redeem, tier — push into your stack

Auth: billStructureId on save-own-bill · optional API key on cart routes · X-API-Key + Secret on /v1/loyalty and events.

Ship it

Onboard once. Activate when the mapping is right.

1
Connect Custom POS
Outlet → Integrations → Custom POS. You get billStructureMappingId and a saveBillUrl.
2
Push a sample bill
Post one sample to save-own-bill. Map your JSON fields to OwnRewards canonical fields in admin.
3
Activate mapping
draft → pending → active. Earn runs only when active — no surprise credits during mapping.
4
Wire the counter loop
cart-validate → (validate-coupon) → cart-checkout → save-own-bill → order/return on voids.
5
Optional: catalog & keys
Register your catalog URL. Create an API key for /v1/loyalty and events. Subscribe to webhooks.

Idempotent bills — honor 409
Stable itemId on every line
Never log OTPs or API secrets
Subscribe to webhooks; don't poll after 2xx

Core loop (illustrative)

// 1) Lookup at the till
POST /loyalty-redeem/cart-validate
{
  "phoneNo": "9876503099",
  "countryCode": "91",
  "outletId": "<outletId>",
  "billAmount": 500,
  "cartItems": [{ "itemId": "SKU-1", "name": "Latte", "qty": 1, "price": 180 }]
}

// 2) Apply reward / points / coupon (+ OTP when required)
POST /loyalty-redeem/cart-checkout
{ "phoneNo": "…", "outletId": "…", "rewardId": "…", "otp": "123456" }

// 3) After payment — earn (unique order id; 409 = already credited)
POST /loyalty-bill/save-own-bill
{ "billStructureId": "…", "orderId": "POS-88421", "items": [/* itemId required */] }

// 4) On void / return
POST /v1/loyalty/order/return
Headers: X-API-Key, X-API-Secret

Prefer the full integrator guide for schemas, error codes and catalog pull contract.

Why POS vendors ship this

Billing plus retention beats billing alone.

Stickier merchants
Loyalty programs raise switching cost. Merchants who earn and redeem inside your POS stay on your POS.
One integration, many brands
You ship the connector once. Each merchant configures their own earn rates, rewards and WhatsApp in OwnRewards.
Co-sell ready
Partner pricing, co-marketing and a joint story: billing + retention in one counter flow.
Production patterns
Idempotent bills (409), OTP redemption, HMAC webhooks, rate limits with Retry-After — built for real tills.

Partner program overview Book a technical demo

FAQ

Custom POS FAQ

Teams that already post bills over HTTPS usually ship the core loop (validate → checkout → save-own-bill → return) in a few days. Catalog pull and webhooks add a short follow-up.

Your POS. Our loyalty engine. Their regulars coming back.

For merchants

For POS vendors

Every OwnRewards feature — offered through your counter.

Points & cashback

Rewards & coupons

VIP tiers

WhatsApp loyalty

Member app

Automations & journeys

Feedback → Google

Analytics merchants trust

Four calls. Full loyalty at the till.

Phone on the ticket

Apply offer + OTP

Bill closes → earn

Cancel / return

Open APIs you call — plus one catalog URL you host.

Onboard once. Activate when the mapping is right.

Connect Custom POS

Push a sample bill

Activate mapping

Wire the counter loop

Optional: catalog & keys

Billing plus retention beats billing alone.

Stickier merchants

One integration, many brands

Co-sell ready

Production patterns

Custom POS FAQ

Ready to offer loyalty inside your POS?

Your POS. Our loyalty engine. Their regulars coming back.

Who this page is for

For merchants

For POS vendors

Every OwnRewards feature — offered through your counter.

Points & cashback

Rewards & coupons

VIP tiers

WhatsApp loyalty

Member app

Automations & journeys

Feedback → Google

Analytics merchants trust

Four calls. Full loyalty at the till.

Phone on the ticket

Apply offer + OTP

Bill closes → earn

Cancel / return

Open APIs you call — plus one catalog URL you host.

Onboard once. Activate when the mapping is right.

Connect Custom POS

Push a sample bill

Activate mapping

Wire the counter loop

Optional: catalog & keys

Billing plus retention beats billing alone.

Stickier merchants

One integration, many brands

Co-sell ready

Production patterns

Custom POS FAQ

How long does a typical POS integration take?

What prevents duplicate points on retries?

Is OTP redemption mandatory?

Can we redeem by only posting the bill?

Do we need PetPooja?

What do merchants still configure in OwnRewards?

Is there a headless path for authenticated apps?

How do you verify the API?

Ready to offer loyalty inside your POS?