Contract authority: OpenAPI is the machine-readable public v1 contract. This page is generated from the Privilege Integrator Pack. If prose and OpenAPI disagree, stop and contact Privilege.

1. Overview

Privilege provides a vendor-neutral External Integration API for POS-style redemption.

Typical checkout:

1. Member presents a Privilege redemption credential (opaque token) at the till.
2. The POS asks Privilege whether that credential may be used now at this outlet (validate).
3. If the commercial sale completes, the POS records the outcome (confirm).
4. If checkout is abandoned after a hold, the POS releases it (cancel).
5. If a confirmed sale must be voided/refunded in Privilege terms, the POS calls reverse.

Authority split

Concern	Owner
Entitlement, deal eligibility, redemption lifecycle	Privilege
Local till promotion rules (%, fixed, B1G1, SKU, stacking)	Your POS
Mapping privilegePromotionId → local promo	Your POS
Privilege-attributable savings reported on confirm	Your POS → Privilege
Receipt / fiscal / basket totals	Your POS (never sent to Privilege)

Privilege does not replace your fiscal stack and does not instruct till pricing. Privilege authorizes whether the selected deal may be redeemed now at the mapped outlet, then records POS-reported Privilege savings.

Production status: Merchant-owned money/pricing semantics above are available in production on runtime 66216080884699ecab007ca25e595eaed69d3df3 (verified 2026-09-18). Schema columns for promotion id / savings provenance remain on production. Vendor E2E remains not independently verified.

---

2. API version and base URL

Item	Value
Public namespace	/api/integrations/v1
Production base URL	https://dev.privilege.hr/api/integrations/v1
Protocol	HTTPS (required in production when Privilege enforces TLS on this router)

Full example path:

POST https://dev.privilege.hr/api/integrations/v1/redemptions/validate

Not available today

• Dedicated external sandbox host / sandbox URL
• Public test-token self-service portal
• Partner Portal Integrations self-service UI for creating credentials and outlet mappings (coordinate with Privilege for now — see Authentication)
• OAuth2 / Member JWT on these routes
• Outbound webhooks for redemption events
• Vendor-specific Privilege adapters as the default integration path

Use only the documented production base URL unless Privilege explicitly provides another host during onboarding.

---

15. Go-live checklist

• [ ] Production Integration Client created for the correct company/profile (via Privilege coordination until Partner Portal Integrations is available)
• [ ] clientKey / clientSecret stored securely (server-side only)
• [ ] Outlet mappings configured and verified (externalOutletId)
• [ ] validate returns reserved with privilegePromotionId, benefit: null, expiresAt
• [ ] confirm returns confirmed after successful till sale
• [ ] cancel tested for abandoned checkout
• [ ] reverse understood/tested if your product will use it (window policy still UNRESOLVED)
• [ ] Idempotency keys unique per logical operation; timeout retries reuse the same key
• [ ] Network timeout / retry behavior tested
• [ ] requestId / X-Request-Id logged on your side
• [ ] Credential rotation procedure understood
• [ ] Support contact agreed with Privilege
• [ ] Real end-to-end checkout test completed with Privilege confirmation

---

16. Support / escalation

Agree the technical support contact with Privilege during onboarding. Do not assume a public SLA from this document.

When escalating, provide:

• requestId (from error body or X-Request-Id)
• Timestamp + timezone
• Operation (validate / confirm / cancel / reverse)
• externalOutletId
• HTTP status + error.code
• Your own POS correlation / receipt reference

Never send clientSecret or full opaque tokens in email/chat. Prefer secret prefixes only if Privilege asks for identity hints.

---