Developer Reference

JoyLanes Ops API

This reference documents the reservation, inventory, and integration surface behind JoyLanes Ops. It mirrors the endpoints the web portal, kiosks, and admin panel call internally. These endpoints are documentation-only in this preview and are not wired to a live server.

Base URL: api.joylanes.mrjoyfec.com/v1Format: JSONRate limit: 120 req/min

Authentication

Every request is signed with a center-scoped API key issued to staff terminals and the reservation engine. Pass it as a bearer token.

Example request header

GET /v1/lanes HTTP/1.1
Host: api.joylanes.mrjoyfec.com
Authorization: Bearer jl_live_5f2c9a1e...
X-Center-Id: riverbend-commons

Lanes

Read live lane state and apply manual host overrides.

GET/v1/lanes

List all lanes for the current center with live computed status.

Response · 200 OK

{
  "data": [
    {
      "id": "lane_1",
      "number": 1,
      "status": "active",
      "current_reservation_id": "res_8f2a1",
      "minutes_remaining": 12
    }
  ]
}

PATCH/v1/lanes/{lane_id}/override

Force a lane into a manual status (e.g. maintenance) — used by the counter host panel.

Parameters

Name	Type	Description
status	string	One of idle, active, cleaning, maintenance.
note	string?	Optional reason shown in the activity log.

Request

{
  "status": "maintenance",
  "note": "Pinsetter jam reported by guest"
}

Response · 200 OK

{
  "id": "lane_4",
  "status": "maintenance",
  "overridden_by": "staff_carlos_w",
  "overridden_at": "2026-08-18T14:02:11Z"
}

409 — Lane currently mid-session

Reservations

Shared by the web portal, kiosks, and counter — every booking runs through the same overbooking-safe slot algorithm (30-minute play + 5-minute cleanup buffer).

GET/v1/availability

Return open 35-minute cycles across all lanes for a given date (max 7 days out).

Parameters

Name	Type	Description
date	string	ISO date, today ≤ date ≤ today + 7.
party_size	integer?	Used to pre-filter by lane capacity.

Response · 200 OK

{
  "date": "2026-08-19",
  "slots": [
    { "start": "10:00", "available_lanes": ["lane_1", "lane_3"] },
    { "start": "10:35", "available_lanes": ["lane_2"] }
  ]
}

POST/v1/reservations

Create a reservation, decrement shoe stock, and issue the dual QR codes.

Request

{
  "customer_name": "Jordan Casey",
  "party_size": 4,
  "start_time": "2026-08-19T18:00:00Z",
  "channel": "web",
  "admission_minutes": 90,
  "shoes": [{ "size": "M9", "quantity": 2 }]
}

Response · 200 OK

{
  "id": "res_9d41f",
  "lane_id": "lane_2",
  "status": "upcoming",
  "buffer_end_time": "2026-08-19T18:40:00Z",
  "qr": {
    "turnstile": "MRJOY:TURNSTILE:res_9d41f:8K2QX1",
    "lane_access": "MRJOY:LANE:res_9d41f:P0M3Z9"
  },
  "payment_total": 42.99
}

409 — Slot no longer available422 — Insufficient shoe stock

DELETE/v1/reservations/{id}

Cancel a reservation and release its lane hold and shoe stock immediately.

Response · 200 OK

{
  "id": "res_9d41f",
  "status": "cancelled",
  "stock_released": true
}

PATCH/v1/reservations/{id}/check-in

Mark a reservation checked-in after the turnstile QR scan.

Response · 200 OK

{
  "id": "res_9d41f",
  "status": "checked-in",
  "checked_in_at": "2026-08-19T17:58:02Z"
}

Shoe Inventory

Concurrency-safe stock ledger keyed by size.

GET/v1/inventory/shoes

List stock levels for every tracked shoe size.

Response · 200 OK

{
  "data": [
    { "size": "M9", "total": 18, "in_use": 8, "available": 10 }
  ]
}

POST/v1/inventory/shoes/{size}/restock

Add newly received or returned pairs to available stock.

Request

{ "quantity": 6 }

Response · 200 OK

{ "size": "M9", "total": 24, "in_use": 8, "available": 16 }

POST/v1/inventory/shoes/release

Automated stock release triggered when a reservation is closed out and shoes are returned.

Request

{ "reservation_id": "res_9d41f" }

Response · 200 OK

{ "reservation_id": "res_9d41f", "released": [{ "size": "M9", "quantity": 2 }] }

POS & Payment Integrations

Reconciliation with the legacy JJA Systems POS and pinpad terminals.

POST/v1/integrations/jja/sync

Trigger a reconciliation pass between JoyLanes reservations and JJA ticket records.

Response · 200 OK

{ "synced_tickets": 14, "discrepancies": 0, "completed_at": "2026-08-18T14:10:03Z" }

POST/v1/payments/charge

Authorize and capture a card-present transaction from a counter or kiosk pinpad.

Request

{
  "terminal_id": "pinpad_2",
  "amount": 42.99,
  "currency": "USD",
  "reservation_id": "res_9d41f"
}

Response · 200 OK

{ "status": "approved", "auth_code": "0F44A2", "terminal_id": "pinpad_2" }

402 — Card declined504 — Terminal timeout

Errors & Status Codes

Code	Meaning
200	Success
401	Missing or invalid API key
402	Payment declined by terminal
404	Resource not found
409	Conflict — slot or lane no longer available
422	Validation error (e.g. insufficient stock)
429	Rate limit exceeded
500	Unexpected server error