Getting Started
This guide walks a POS partner from zero to a working order flow against the Swoop sandbox.
1. Become a partner
Email partners@swoopgolf.com to request sandbox access. You'll receive:
- A staging base URL (
https://adapter.staging.swoopgolf.com). - A webhook token (
PUBSUB_PUSH_TOKEN) for authenticating status webhooks. - A sandbox club/location with a seeded test menu.
2. Understand the flow you're implementing
| Direction | Trigger | What you build |
|---|---|---|
| Order in | Member checks out → Swoop sends a CanonicalOrder to your provider |
Provider.CreateOrder — translate the canonical order into your POS's create-order call |
| Status out | Your POS advances the ticket | WebhookTranslator.TranslateWebhook — turn your raw webhook into a StatusEvent |
| Menu sync (optional) | Reconcile catalogs | MenuReader.FetchMenu — return your POS menu as MenuItems |
Swoop delivers a canonical order to your integration and expects order-status webhooks in return — that is the whole contract. See Core Concepts for the shapes and the routing model.
3. Map your menu
Swoop orders reference Swoop item ids, not your POS's SKUs. Before orders can flow, each Swoop item and option is mapped to your POS item/modifier id in the adapter's item-mapping store. An order that references an unmapped item is dead-lettered for human attention — never pushed with a guess. See Core Concepts → Item mapping.
4. Receive a test order
With your provider registered and your menu mapped, place a test order in the sandbox. Swoop will:
- Publish
orderPlaced. - Re-fetch the authoritative order from swoop-api and build a
CanonicalOrder. - Call your
Provider.CreateOrder.
Return an OrderRef ({ id, provider }) and you've completed the inbound path.
5. Send status back
As the ticket advances, post your status webhook to:
POST https://adapter.staging.swoopgolf.com/webhook/{provider}?token=YOUR_TOKEN
Your WebhookTranslator maps it to a canonical StatusEvent; the member sees the update
live. See Webhooks for payloads and acknowledgement semantics.
6. Go live
Once order-in and status-out pass in sandbox, Swoop adds a production tenant config row mapping your club's location to your provider — no code change — and you're live.