ShelfSpaceAPI v1
API Reference

Build with ShelfSpace

A REST API for shelves, bookings, escrow, QR attribution, and messaging. Authenticated with bearer tokens issued via OAuth 2.0.

Authorization header
Authorization: Bearer shs_live_xxxxxxxxxxxxxxxxxxxx

Authentication

POST/v1/auth/session

Exchange an OAuth code for a session token.

Request
{
  "code": "string",
  "redirect_uri": "string"
}
Response · 200 OK
{
  "access_token": "shs_live_…",
  "refresh_token": "shs_rt_…",
  "expires_in": 3600,
  "user": {
    "id": "u_x9k",
    "role": "brand"
  }
}
GET/v1/me

Get the current authenticated user.

Response · 200 OK
{
  "id": "u_x9k",
  "name": "Maya Okafor",
  "role": "brand",
  "company": "Aurela Botanics"
}

Shelves

GET/v1/shelves?city=Austin&vibe=minimal

Search shelves with filters.

Response · 200 OK
{
  "data": [
    {
      "id": "s_001",
      "title": "Front counter shelf · Morning Bean Café",
      "city": "Austin",
      "price_per_week": 180,
      "foot_traffic": 320
    }
  ],
  "page": 1,
  "total": 42
}
GET/v1/shelves/:id

Get a single shelf with host details.

Response · 200 OK
{
  "id": "s_001",
  "host": {
    "id": "u_host",
    "name": "Lena Cortez"
  },
  "dimensions": "60 × 30 × 25 cm",
  "availability": [
    "2025-10-12/2025-12-31"
  ]
}
POST/v1/shelves

Create a new shelf listing (host only).

Request
{
  "title": "string",
  "city": "string",
  "price_per_week": 150,
  "dimensions": "string"
}
Response · 200 OK
{
  "id": "s_new",
  "status": "pending_review"
}
PATCH/v1/shelves/:id

Update price, availability, status.

Request
{
  "price_per_week": 200
}
Response · 200 OK
{
  "id": "s_001",
  "price_per_week": 200
}
DELETE/v1/shelves/:id

Archive a shelf listing.

Response · 200 OK
{
  "deleted": true
}

Bookings & Escrow

POST/v1/bookings

Create a booking and lock funds in escrow.

Request
{
  "shelf_id": "s_001",
  "start_date": "2025-11-01",
  "weeks": 4,
  "product_name": "Aurela Glow Serum"
}
Response · 200 OK
{
  "id": "b_x12",
  "status": "in_escrow",
  "total_amount": 720,
  "qr_code_id": "QR-AURELA-002"
}
GET/v1/bookings?status=active

List the caller's bookings.

Response · 200 OK
{
  "data": [
    {
      "id": "b_001",
      "status": "active",
      "qr_scans": 184,
      "qr_sales": 27
    }
  ]
}
POST/v1/bookings/:id/confirm-setup

Host marks shelf as set up; releases escrow trigger.

Response · 200 OK
{
  "id": "b_x12",
  "status": "active"
}
POST/v1/bookings/:id/cancel

Cancel a booking; refund per policy.

Request
{
  "reason": "string"
}
Response · 200 OK
{
  "id": "b_x12",
  "status": "cancelled",
  "refunded": 720
}

QR codes

GET/v1/qr/:code

Resolve a QR code to a product checkout.

Response · 200 OK
{
  "booking_id": "b_001",
  "product": "Aurela Glow Serum · 30ml",
  "checkout_url": "https://shop.shelfspace.io/c/QR-…"
}
GET/v1/qr/:code/analytics

Scans and conversion for a QR code.

Response · 200 OK
{
  "scans": 184,
  "sales": 27,
  "conversion_rate": 0.147
}

Messages

GET/v1/threads/:booking_id/messages

List messages on a booking thread.

Response · 200 OK
{
  "data": [
    {
      "id": "m_1",
      "from": "u_host",
      "text": "Got your shipment!"
    }
  ]
}
POST/v1/threads/:booking_id/messages

Send a message.

Request
{
  "text": "string"
}
Response · 200 OK
{
  "id": "m_new",
  "created_at": "2025-10-15T10:22:00Z"
}

Payouts (Host)

GET/v1/payouts

List payouts to the connected bank account.

Response · 200 OK
{
  "data": [
    {
      "id": "po_a1",
      "amount": 720,
      "status": "paid",
      "arrived_at": "2025-10-07"
    }
  ]
}
Webhooks

Subscribe to events like booking.confirmed, qr.scanned, payout.paid.