{ "info": { "name": "RangeWorks Partner API", "description": "REST API for RangeWorks integration partners. Provides access to account, customer,\nmembership, reservation, and live range data — including write operations for syncing\ncustomer records from external POS systems.\n\n## Authentication\n\nAll endpoints except `/auth/token` require a Bearer JWT token in the `Authorization` header.\n\n**Step 1:** Exchange your partner credentials for a token:\n\n```bash\ncurl -X POST /api/v1/auth/token \\\n -H \"Content-Type: application/json\" \\\n -d '{\"client_id\": \"your_client_id\", \"client_secret\": \"your_client_secret\"}'\n```\n\n**Step 2:** Use the returned token on all subsequent requests:\n\n```bash\ncurl /api/v1/account \\\n -H \"Authorization: Bearer \"\n```\n\nTokens expire after a configurable TTL (default 24 hours). Request a new token when you receive a `401` response.\n\n## Multi-Tenant Access\n\nYour token is scoped to a single **account** which may contain multiple **businesses** (locations).\nUse the `business_slug` query parameter on relevant endpoints to target a specific location.\n\n## Response Format\n\nAll responses follow a consistent envelope:\n\n```json\n{\n \"data\": { ... },\n \"meta\": {\n \"page\": 1,\n \"per_page\": 25,\n \"total_count\": 100,\n \"total_pages\": 4\n }\n}\n```\n\nSingle-resource endpoints omit `meta`. Error responses use:\n\n```json\n{\n \"error\": {\n \"status\": 404,\n \"code\": \"NOT_FOUND\",\n \"message\": \"Customer not found\"\n }\n}\n```\n\n## Pagination\n\nCollection endpoints accept `page` (default 1) and `per_page` (default 25, max 100) query parameters.\n\n## Rate Limits\n\nThe API enforces per-token rate limits to protect system stability. Limits vary by HTTP method:\n\n| Method | Limit | Window | Cooldown on violation |\n|--------|-------|--------|-----------------------|\n| **POST** | 10 requests | 10 seconds | 1 minute |\n| **GET** | 60 requests | 30 seconds | 1 minute |\n\nWhen a rate limit is exceeded the API returns `429 Too Many Requests` with a JSON error body\nand a `Retry-After` header indicating how many seconds to wait before retrying.\n\n```json\n{\n \"error\": {\n \"status\": 429,\n \"code\": \"RATE_LIMITED\",\n \"message\": \"Rate limit exceeded. Retry after 60 seconds.\"\n }\n}\n```\n\n**Rate limit headers** are included on every response:\n- `X-RateLimit-Limit` — Maximum requests allowed in the current window\n- `X-RateLimit-Remaining` — Requests remaining in the current window\n- `X-RateLimit-Reset` — Unix timestamp (seconds) when the current window resets\n- `Retry-After` — *(429 responses only)* Seconds until the cooldown expires\n\n**Best practices:**\n- Monitor `X-RateLimit-Remaining` and back off before hitting zero.\n- On a `429` response, wait for the duration specified in `Retry-After` before retrying.\n- Avoid tight polling loops — use reasonable intervals (e.g. 5–10 seconds for live range status).\n\n## Field Naming\n\nAll response fields use **snake_case** naming (e.g. `first_name`, `date_start`, `is_active`).\n\n## Exports\n\n- **OpenAPI JSON:** `GET /api/v1/docs/openapi`\n- **Postman Collection:** `GET /api/v1/docs/postman`\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "version": "1.0.0" }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "variable": [ { "key": "partner_api_token", "value": "", "type": "string" }, { "key": "base_url", "value": "http://localhost:4006/api/v1", "type": "string" } ], "item": [ { "name": "Auth", "item": [ { "name": "Exchange credentials for JWT", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/auth/token", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "auth", "token" ] }, "description": "Exchange your partner `client_id` and `client_secret` for a JWT Bearer token.\nThe token is valid for the configured TTL (default 24 hours). Include it in the\n`Authorization: Bearer ` header on all subsequent requests.\n", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } } ] }, { "name": "Account", "item": [ { "name": "Get current account", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/account", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "account" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the account associated with your JWT token, including all business locations." } } ] }, { "name": "Customers", "item": [ { "name": "List customers", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/customers", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "customers" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a paginated list of retail customers. Optionally filter by `business_slug`." } }, { "name": "Create or update a customer", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/customers", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "customers" ], "query": [ { "key": "business_slug", "value": "", "description": "Business location slug (required for tenant scoping)", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Upserts a retail customer using `external_id` as the match key.\nIf a customer with the given ID already exists, their record is updated;\notherwise a new customer is created.\n\n**Requires `business_slug`** — customers are scoped to a specific business location.\n", "body": { "mode": "raw", "raw": "{}", "options": { "raw": { "language": "json" } } } } }, { "name": "Get customer by ID", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/customers/{id}", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "customers", "{id}" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a single customer with their membership enrollments." } }, { "name": "List memberships for a customer", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/customers/{id}/memberships", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "customers", "{id}", "memberships" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns all membership enrollments (member records) for a specific customer." } }, { "name": "List reservations for a customer", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/customers/{id}/reservations", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "customers", "{id}", "reservations" ], "query": [ { "key": "date_start", "value": "", "description": "Filter reservations starting on or after this date (ISO 8601)", "disabled": true }, { "key": "date_end", "value": "", "description": "Filter reservations ending on or before this date (ISO 8601)", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns range lane reservations for a specific customer. Supports date range filtering." } } ] }, { "name": "Memberships", "item": [ { "name": "List membership plans", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/memberships", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "memberships" ], "query": [ { "key": "active_for_sale", "value": "", "description": "When true, hide plans that are no longer offered", "disabled": true }, { "key": "presale_mode", "value": "", "description": "When true, return only presale-mode plans", "disabled": true }, { "key": "family_addons_enabled", "value": "", "description": "When true, return only plans that allow family add-ons", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the membership plan catalog — the plans customers can purchase.\nFilter by `business_slug` to scope to a location, by `active_for_sale` to\nhide retired plans, by `presale_mode` to surface presale-only plans, or\nby `family_addons_enabled` to filter to family-capable plans.\n" } }, { "name": "Get membership plan by ID or slug", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/memberships/{id}", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "memberships", "{id}" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a single membership plan. The path parameter accepts either the\nnumeric plan ID or the plan slug.\n" } } ] }, { "name": "Members", "item": [ { "name": "List membership enrollments", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/members", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "members" ], "query": [ { "key": "customer_id", "value": "", "description": "Filter members by retail customer ID", "disabled": true }, { "key": "membership_id", "value": "", "description": "Filter members by membership plan ID", "disabled": true }, { "key": "status", "value": "", "description": "Lifecycle filter: active, expired, suspended, cancelled, pending", "disabled": true }, { "key": "fulfillment_status", "value": "", "description": "Fulfillment filter: e.g. fulfilled, pending_documents", "disabled": true }, { "key": "date_start", "value": "", "description": "Filter to members whose start date is on or after this ISO 8601 timestamp", "disabled": true }, { "key": "date_end", "value": "", "description": "Filter to members whose end date is on or before this ISO 8601 timestamp", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a paginated list of membership enrollments (members) across an\naccount. Filter by `customer_id` or `membership_id` to narrow to a\nsingle customer or plan, by `status` / `fulfillment_status` to gate on\nlifecycle state, or by `date_start` / `date_end` to filter by enrollment\nwindow.\n" } }, { "name": "Get member by ID", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/members/{id}", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "members", "{id}" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a single membership enrollment by ID." } } ] }, { "name": "Classes", "item": [ { "name": "List classes", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/classes", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "classes" ], "query": [ { "key": "active_for_sale", "value": "", "description": "When true, hide classes with no purchasable sessions", "disabled": true }, { "key": "firearm_type", "value": "", "description": "Firearm-type enum value", "disabled": true }, { "key": "skill_level", "value": "", "description": "Skill-level enum value", "disabled": true }, { "key": "certification_type", "value": "", "description": "Certification-type enum value", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the customer-facing class catalog. Each entry includes summary\nnext-session information (date, price, remaining seats). Use\n`/classes/{id}/sessions` to fetch the full schedule.\n" } }, { "name": "Get class by ID or slug", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/classes/{id}", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "classes", "{id}" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a single class with its upcoming sessions inlined under\n`range_class_definitions`. The path parameter accepts either the numeric\nclass ID or the class slug.\n" } }, { "name": "List sessions for a class", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/classes/{id}/sessions", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "classes", "{id}", "sessions" ], "query": [ { "key": "date_start", "value": "", "description": "Filter sessions starting on or after this ISO 8601 timestamp", "disabled": true }, { "key": "date_end", "value": "", "description": "Filter sessions starting on or before this ISO 8601 timestamp", "disabled": true }, { "key": "has_open_seats", "value": "", "description": "When true, hide sessions with no remaining seats", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the scheduled sessions (class definitions) for a single class.\nFilter by a date range or by `has_open_seats` to hide full sessions.\nThe path parameter accepts either the numeric class ID or the class\nslug.\n" } } ] }, { "name": "Reservations", "item": [ { "name": "List reservations", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/reservations", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "reservations" ], "query": [ { "key": "customer_id", "value": "", "description": "Filter reservations by customer ID", "disabled": true }, { "key": "date_start", "value": "", "description": "Filter reservations starting on or after this date (ISO 8601)", "disabled": true }, { "key": "date_end", "value": "", "description": "Filter reservations ending on or before this date (ISO 8601)", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a paginated list of range lane reservations. Supports filtering by customer, date range, and business location." } }, { "name": "Get reservation by ID", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/reservations/{id}", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "reservations", "{id}" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a single range lane reservation by ID." } } ] }, { "name": "Range", "item": [ { "name": "List range bays", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/bays", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "bays" ], "query": [ { "key": "active_for_reservations", "value": "", "description": "When true, hide bays that are not currently accepting reservations", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the customer-facing reservable range bays. These are distinct\nfrom the live-ops `/range/spaces` / `/range/resources` views, which\nexpose internal venue topology and live occupancy.\n" } }, { "name": "Get range bay by ID or slug", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/bays/{id}", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "bays", "{id}" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a single range bay. The path parameter accepts either the\nnumeric bay ID or the bay slug.\n" } }, { "name": "Search range bay availability for a date and time", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/availability", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "availability" ], "query": [ { "key": "business_slug", "value": "", "description": "Business location slug (required)", "disabled": false }, { "key": "search_date", "value": "", "description": "Date to search (YYYY-MM-DD)", "disabled": false }, { "key": "search_time", "value": "", "description": "Time to search (h:MM AM/PM)", "disabled": false }, { "key": "membership_id", "value": "", "description": "Evaluate availability as if the caller held this membership plan", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the per-bay slot search result for the supplied `business_slug`,\n`search_date` (YYYY-MM-DD), and `search_time` (h:MM AM/PM). Pass an\noptional `membership_id` to evaluate membership-gated bays as if the\ncaller were enrolled in that plan.\n\nThis endpoint is **not paginated** — the full array of bays is returned\nunder `data`. Bays without a successful search return `searched: false`\nand surface any validation issues under `errors`.\n" } }, { "name": "Get live range status", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/status", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "status" ], "query": [ { "key": "business_slug", "value": "", "description": "Business location slug (required)", "disabled": false } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns the real-time status of all range bays and their lanes, including which lanes\nare open, reservable, and currently occupied. This is the primary endpoint for digital\nsignage and live lane status displays.\n\n**Requires `business_slug`** — range status is always location-specific.\n" } }, { "name": "List venue spaces", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/spaces", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "spaces" ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns all venue spaces (range bays) with their associated resource IDs." } }, { "name": "List venue resources", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/resources", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "resources" ], "query": [ { "key": "space_id", "value": "", "description": "Filter resources by venue space ID", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns individual range lanes/resources, optionally filtered by `space_id`. Includes current occupancy." } }, { "name": "List range parties", "request": { "method": "GET", "header": [ { "key": "Content-Type", "value": "application/json", "type": "text" } ], "url": { "raw": "http://localhost:4006/api/v1/range/parties", "protocol": "http", "host": [ "localhost" ], "port": "4006", "path": [ "range", "parties" ], "query": [ { "key": "active", "value": "", "description": "Filter to only active (`true`) or completed (`false`) sessions", "disabled": true }, { "key": "space_id", "value": "", "description": "Filter parties by venue space ID", "disabled": true } ] }, "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{partner_api_token}}", "type": "string" } ] }, "description": "Returns a paginated list of range parties (sessions). Filter by `active` status or `space_id`." } } ] } ] }