Resources · Developer Center

POS, OMS & ERP Integration

Wire the systems you already run — your point-of-sale, order-management, and ERP — into SocialHub loyalty. There is no proprietary connector to install: each integrates through the same governed v2 REST API, authenticated with a tenant key, scoped per endpoint, and audited on every call.

Get an API key Browse the API

One API, three system types

Every integration below is the v2 REST API over HTTPS with a Authorization: Bearer fl_live_… tenant key. Use a read-only key for reconciliation and a write-scoped key only where you award points or redeem coupons. For e-commerce platforms (Shopify, Amazon, TikTok Shop) prefer the native channel connectors — this guide is for systems without one.

POS

Point of sale

Turn an in-store purchase into loyalty value: award points on the sale and redeem coupons at the register.

OMS

Order management

Let online & omnichannel orders earn — and returns claw back — keyed to your order ids.

ERP

Enterprise resource planning

Reconcile stores, the member roster, and the points ledger with your system of record.

POS

Point-of-sale integration

The in-store register is where a purchase becomes loyalty value. Members are identified by the portal QR / check-in they present — there is no phone or email lookup in the API — and your POS acts on the resulting memberId.

Award points on a sale

// 1) Identify the member at the register. There is no phone/email lookup in the API:
//    the member presents their portal QR / in-store check-in (a member-keyed,
//    deduplicated store visit), and your POS carries the resulting memberId.
// 2) Award points on the sale:
POST https://flash.socialhub.ai/api/v2/members/{memberId}/points
Authorization: Bearer fl_live_…
Content-Type: application/json
{ "amount": 120, "description": "In-store purchase · store ST-NYC-01 · txn 90871" }
// → 200  { "transactionId": "txn_…", "balance": 1820 }
//
// IDEMPOTENCY: the API has no dedup key. Put your POS transaction id in the
// description and guard retries on YOUR side so one sale never awards twice.

Redeem a coupon at the register

// Cashier scans the member's coupon code → mark it redeemed at the register.
POST https://flash.socialhub.ai/api/v2/coupons/{couponId}/redeem
Authorization: Bearer fl_live_…
// → 200  redeemed
// → 404  coupon not found / already redeemed   (treat as "do not honor")

Read back a member's balance, tier and coupons with GET /members/{id}/points, /tier and /coupons to show them at the register.

OMS

Order-management integration

For e-commerce platforms with a native connector (Shopify, Amazon, TikTok Shop), turn it on and you are done. For any other order-management system, translate its order events into points over the API — there is no order webhook, so your OMS drives the calls.

Orders earn; returns claw back

// Already on Shopify, Amazon, or TikTok Shop? Use the NATIVE channel connectors
// (your SocialHub workspace → Settings → Channels) — they ingest orders and award
// points with no code. The pattern below is for any OTHER OMS.
//
// There is no inbound order webhook — your OMS calls SocialHub on its own events:
//   order paid / fulfilled  →  award points
POST https://flash.socialhub.ai/api/v2/members/{memberId}/points
{ "amount": 240, "description": "Order #SO-44821 fulfilled" }
//   order returned / cancelled  →  post a compensating adjustment keyed to the
//   same order id (coordinate the sign + caps with your SocialHub team).
//
// Key every call by your order id (in description) and guard reprocessing on your
// side — replaying the same order must not double-award.

New customer on an order? Capture / enroll them first (consumer flow), then award against the resulting member.

ERP

ERP & master-data integration

Keep loyalty aligned with your system of record. The API is read-oriented here: reconcile your store master and member roster, and pull the points ledger for finance — on a scheduled job that pages through with limit/offset.

Reconcile stores

// Stores are managed in SocialHub; the API is READ, for reconciliation. Map your
// ERP store codes ↔ SocialHub store ids (use those ids in POS point descriptions).
GET https://flash.socialhub.ai/api/v2/stores?limit=200&offset=0
Authorization: Bearer fl_live_…
// → 200  { "stores": [ { "id": "st_…", "name": "…", "status": "active" } ], "total": … }

Reconcile members & the points ledger

// Pull the member roster + points ledger into your ERP / BI for reconciliation.
// NOTE: members are created by consumer enrollment (QR / portal / web), NOT pushed
// from the ERP — there is no member-create endpoint.
GET https://flash.socialhub.ai/api/v2/members?status=active&limit=200&offset=0     // paginate with offset
GET https://flash.socialhub.ai/api/v2/members/{memberId}/points?limit=50          // transaction ledger
// For governed business metrics (GMV, redemption, active members) into BI, query the
// semantic layer over MCP (metrics:read) instead of aggregating raw rows yourself.

Respect pagination (≤200 members/page) and the per-key rate limit; run reconciliation off-peak.

Auth, scopes & safety

Tenant-scoped keys

Every call carries a fl_live_ key bound to one team. Keys never cross tenants; create separate keys per integration so you can rotate one without touching the others.

Read vs write presets

Reconciliation jobs use a read-only key. Give a write scope only to the POS/OMS path that awards points or redeems coupons — least privilege per system.

You own idempotency

The award/redeem endpoints have no server-side dedup key. Key every write by your transaction/order id and guard retries so a replay never double-awards.

Audited by default

Every API call is logged and visible under API Keys → recent activity, so an integration's writes are always traceable to a key.

Full endpoint reference: REST API · Quick Start · MCP (metrics into BI)

Integrating a backend system?

Talk to an engineer about your POS/OMS/ERP, member identity at the register, returns handling, or reconciliation jobs.

Talk to engineering