Core Concepts

Five ideas underpin every Swoop POS integration.

Tenants & locations

A tenant maps a Swoop location (a club) to a provider plus that provider's config. Routing an order is a lookup: locationId → Provider. Adding a club — or moving a club to a different POS — is a config row, not code:

[
  { "swoopLocationId": "51", "provider": "my-pos", "config": { "storeId": "...", "endpointId": "..." } }
]

The registry is built from this config at startup. A location with no tenant row has no provider, and its orders are not pushed.

Canonical contract

Swoop never hands your POS a Swoop-shaped or vendor-shaped order. Everything crosses the boundary as the canonical contract: CanonicalOrder, StatusEvent, MenuItem. This is the seam that keeps any one POS "POS #1, never the only POS." You translate canonical → your POS on the way in, and your POS → canonical on the way out. See Order Lifecycle for the full shape.

Item & modifier mapping

A CanonicalOrder references Swoop item ids and Swoop option ids — not your SKUs. The adapter resolves them to your POS's ids through an item-mapping store, exposed to your provider as the ItemResolver:

ResolveItem(locationID, swoopItemID string) (id string, ok bool)
ResolveModifier(locationID, swoopOptionID string) (id string, ok bool)

If a referenced item or modifier has no mapping, the order is dead-lettered for human attention — it is never pushed to the POS with a guessed item. (ErrUnmappedItem.) Mappings are seeded ahead of go-live and reconciled with MenuReader.

Idempotency

Order delivery is at-least-once — Pub/Sub can redeliver, and a POS may resend a webhook. Both paths are safe:

• Inbound: the processor is idempotent on the Swoop order id; a redelivered orderPlaced does not create a duplicate POS order.
• Outbound to the POS: use the Swoop order id as your idempotency key (pass it as your external/third-party reference; a duplicate returns 409, which the integration treats as success).

Always key on swoopOrderId.

Delivery vs pickup

Fulfillment is either delivery (on-course, to a marker like 4th Hole) or pickup (a counter such as the Halfway House). The same canonical ready status maps to different member-facing states depending on fulfillment — ready for pickup vs ready for delivery / en route. Your provider doesn't need to know the member-facing mapping; emit the canonical status and Swoop resolves it from the order's fulfillment.