Developer DocumentationSquare POS: Sandbox VerifiedClover · Shopify POS · Toast: Planned Evaluation

RetailLume Developer Portal & POS Integration Architecture

Store-scoped catalog synchronization, integer minor-unit selling prices, compare-and-swap (CAS) binding revision fencing, and hardware pause controls for connecting POS platforms to RetailLume electronic shelf labels.

1. STORE-SCOPED ISOLATION

(tenantId, storeId, sourceProvider)

Deterministic product keys keep each store location and POS provider strictly isolated.

2. EFFECTIVE SHELF PRICING

Integer Minor Units (priceMinor)

Always reflects the fixed selling price in minor currency units (e.g. 1549 for $15.49 USD).

3. SANDBOX & PAUSE GATE

isPaused: true · Safe Staging

Allows catalog sync and price updates to be verified in the workspace while holding physical RF label transmissions.

1. Public POS Developer Integrations & Technical Status

Verified & Evaluated Systems

RetailLume provides a canonical store catalog and ESL binding engine designed to integrate with point-of-sale platforms. Below is the technical status for publicly documented POS systems:

POS Platform	Developer & API Status	Integration Mechanism & Scope	Guide
Square POS	Sandbox Verified	OAuth 2.0 authorization (`/api/pos/square/oauth/*`), encrypted token & refresh-token persistence, location-scoped fixed-price catalog import, and signed `catalog.version.updated` webhook ingestion.	Square Guide →
Clover POS	Planned — Under Evaluation	Evaluating Clover v3 REST API (`/v3/merchants/{mId}/items`), OAuth 2.0 merchant app tokens, webhook subscriptions, and Sandbox merchant test environments for barcoded fixed-price retail.	Clover Guide →
Shopify POS	Planned — Under Evaluation	Evaluating Shopify Admin GraphQL API (2026-04+), OAuth 2.0 offline access tokens (`read_products`, `read_locations`), `products/update` HMAC webhooks, and Partner development stores.	Shopify POS Guide →
Toast POS	Planned — Under Evaluation	Evaluating Toast Partner Program access requirements, OAuth 2.0 machine-to-machine authentication, Menus/Retail APIs, and webhook availability before committing an implementation date.	Toast Guide →

2. Verified API Endpoints (Square POS & Workspace Services)

Implemented

Method & Path	Status	Authentication	Description
GET /api/pos/square/setup	Live	Store Admin Session	Inspects Square OAuth and webhook configuration readiness for a specific `storeId` without external network calls.
GET /api/pos/square/oauth/start	Live	Store Admin Session	Generates a single-use HMAC-signed OAuth state nonce and redirects the merchant to Square OAuth authorization.
GET /api/pos/square/oauth/callback	Live	Signed OAuth State	Validates and consumes the OAuth state, exchanges the code for merchant tokens, and encrypts credentials at rest.
POST /api/pos/square/select-location	Live	Store Admin Session	Binds the connected Square account to a specific Square location ID so location-specific price overrides apply.
POST /api/pos/square/sync	Live	Store Admin Session	Imports fixed-price Square catalog items, variations, and location-specific price overrides into the store workspace.
POST /api/pos/square/renew-token	Live	Store Admin Session	Refreshes the merchant's OAuth access token using the encrypted refresh token and re-encrypts rotated credentials.
POST /api/pos/square/disconnect	Live	Store Admin Session	Revokes the Square OAuth token, clears stored credentials, and preserves existing catalog items and shelf bindings.
POST /api/pos/square/webhook	Live	`x-square-hmacsha256-signature`	Verifies Square webhook signatures, deduplicates webhook receipts atomically, and updates bound variant prices.
GET /api/console/workspace	Live	Session Bearer / Cookie	Returns the store-scoped workspace projection (products, variants, ESL devices, bindings, and POS connection status).
GET /api/health	Live	Public	Returns service health, storage mode, and deployed commit version.

Square POS Customer Connection Flow & Environment Separation

Sandbox vs. Production Isolation

Sign In & Keep Dispatch Paused: Sign in to the RetailLume Merchant Console as a Store Owner or Admin and verify the store workspace is set to isPaused: true so initial catalog import is strictly read-only with zero physical tag writes.
Authorize via Square OAuth: Click Connect Square POS (which invokes GET /api/pos/square/oauth/start with least-privilege scopes ITEMS_READ and MERCHANT_PROFILE_READ) and approve access in Square.
Select Store Location & Import Catalog: Confirm or switch the active Square location (POST /api/pos/square/select-location) and trigger initial read-only catalog synchronization (POST /api/pos/square/sync).
Automatic Webhook Price Updates: Signed catalog.version.updated webhooks (API version 2026-09-16) automatically refresh catalog prices in RetailLume while respecting the store pause gate until a scoped physical-tag test is explicitly approved.

3. Sanitized Payload & Workspace Examples

All examples below use sanitized sandbox identifiers and contain no live credentials or merchant data.

POST /api/pos/square/webhook (Sanitized Example)

{
  "merchant_id": "MERCHANT_SANDBOX_EXAMPLE",
  "type": "catalog.version.updated",
  "event_id": "evt_sq_sandbox_20261031_001",
  "created_at": "2026-10-31T14:20:00.000Z",
  "data": {
    "type": "catalog",
    "id": "catalog_version_example",
    "object": {
      "catalog_version": {
        "updated_at": "2026-10-31T14:19:58.000Z"
      }
    }
  }
}

Building or Evaluating a POS Integration?

Request a sandbox review or partner discussion so our engineering team can evaluate your catalog structure and store workflow.