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. Grab the spec and a ready-to-run collection
The whole contract ships as machine-readable artifacts you can work from directly:
- OpenAPI 3.1 document — generate a client, mock server, or contract tests from it.
- Postman collection — one ready-to-send request per operation, foldered by API suite, with realistic example bodies filled in. Import it into Postman or Insomnia, point the base URL at your staging host, set your webhook token, and every call in this guide is one click away.
API changes are tracked in the Changelog — the contract only ever grows; nothing is removed or repurposed within a version.
3. 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.
4. 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.
5. 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.
6. Send status back
As the ticket advances, post your status webhook to:
POST https://adapter.staging.swoopgolf.com/webhook/{provider}/{locationId}?token=YOUR_TOKEN
Your WebhookTranslator maps it to a canonical StatusEvent; the member sees the update
live. See Webhooks for payloads and acknowledgement semantics.
7. 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.