CLIENT API

Client API

The Client API is the read-mostly slice of the Pounds API designed for building customer-facing experiences — your own branded booking page, a kiosk screen, a white-label mobile app. Same token format, different scopes.

Never ship write-scope tokens to browsers

The Client API is designed to be called from your own backend server. If you need to expose data directly from a customer's browser, mint a read-only token with just customers:read and rewards:read. Never expose a token that can create, update, or delete resources.

On this page

→ Public shop info → Services → Public rewards → Availability → Customer self-service → Customer booking

Public shop info

These endpoints return the same public profile data a customer sees when they land on the shop's page. They are safe to cache.

GET/api/v1/public/shop

Get shop profile

Returns the shop's public profile — name, logo, address, opening hours, and primary color. Scoped to the tenant that owns the API key.

Auth: Tenant API keysettings:read

Response

200 OK

{
  "data": {
    "id": "tenant_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "name": "Brew & Bean Coffee",
    "slug": "brew-bean",
    "logo": "https://cdn.pounds.network/shops/brew-bean/logo.png",
    "primaryColor": "#7c3aed",
    "description": "Third-wave coffee roastery in Shoreditch",
    "address": "42 Redchurch Street, London E2 7DP",
    "location": { "lat": 51.524, "lng": -0.074 },
    "currency": "GBP",
    "timezone": "Europe/London",
    "operatingHours": {
      "mon": "08:00-18:00",
      "tue": "08:00-18:00"
    }
  }
}

Services

The list of bookable services — the things a customer can pick when making a booking.

GET/api/v1/public/services

List bookable services

Returns every active service a customer can book, with price, duration, and the points they'll earn on completion.

Auth: Tenant API keysettings:read

Response

200 OK

{
  "data": [
    {
      "id": "svc_01HY2F8Z3M7K8XQRBV4N2YJWPD",
      "name": "Signature Cut & Style",
      "description": "60 minutes with a senior stylist",
      "durationMinutes": 60,
      "price": 8000,
      "currency": "GBP",
      "pointsOnCompletion": 100,
      "image": "https://cdn.pounds.network/services/svc_01HY2F.jpg"
    }
  ]
}

Public rewards

The catalog of rewards customers can redeem. Inactive and out-of-stock rewards are filtered out automatically.

GET/api/v1/public/rewards

List available rewards

Returns the rewards catalog visible to customers. Excludes inactive rewards and ones with zero stock remaining.

Auth: Tenant API keyrewards:read

Response

200 OK

{
  "data": [
    {
      "id": "rwd_01HY2F8Z3M7K8XQRBV4N2YJWPD",
      "name": "Free coffee",
      "description": "Any drink on the menu",
      "pointsCost": 500,
      "image": "https://cdn.pounds.network/rewards/rwd_01HY2F.jpg",
      "stockRemaining": null
    }
  ]
}

Availability

Check which slots are open before showing a booking picker to the customer.

GET/api/v1/public/availability

Get available time slots

Returns the next N available start times for a given service, respecting operating hours, existing bookings, and staff assignments.

Auth: Tenant API keybookings:read

Parameters

Name	Type	Description
`serviceId`*	string	Service to check availability for
`from`	ISO date	Earliest start time to consider (default: now)
`days`	number	How many days forward to search (default 14, max 60)

Response

200 OK

{
  "data": {
    "serviceId": "svc_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "slots": [
      { "startAt": "2026-04-11T09:00:00.000Z", "available": true },
      { "startAt": "2026-04-11T10:00:00.000Z", "available": true },
      { "startAt": "2026-04-11T11:00:00.000Z", "available": false }
    ]
  }
}

Customer self-service

These endpoints return data for a single customer. They accept either:

A tenant API key + explicit customerId query param (for server-to-server calls), or
A signed-in customer session (for customer-facing pages hosted on your domain via the Pounds customer SDK).

GET/api/v1/me/balance

Get customer balance

Returns the customer's current points balance, tier, and next-tier progress.

Auth: Customer sessioncustomers:read

Parameters

Name	Type	Description
`customerId`	string	Required when using a tenant API key. Inferred from the session otherwise.

Response

200 OK

{
  "data": {
    "customerId": "cust_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "points": 1247,
    "tier": "GOLD",
    "nextTier": {
      "name": "PLATINUM",
      "pointsNeeded": 753
    },
    "lifetimeSpend": 24500,
    "currency": "GBP"
  }
}

GET/api/v1/me/bookings

List customer bookings

Returns the customer's upcoming and past bookings, most recent first.

Auth: Customer sessionbookings:readcustomers:read

Parameters

Name	Type	Description
`customerId`	string	Required when using a tenant API key
`status`	string	Filter by status (PENDING, CONFIRMED, COMPLETED, CANCELLED)
`limit`	number	Page size (default 20, max 100)

Response

200 OK

{
  "data": [
    {
      "id": "bkng_01HY2F8Z3M7K8XQRBV4N2YJWPD",
      "status": "CONFIRMED",
      "serviceName": "Signature Cut & Style",
      "startAt": "2026-04-12T14:00:00.000Z",
      "endAt": "2026-04-12T15:00:00.000Z",
      "pointsAwarded": 0
    }
  ]
}

GET/api/v1/me/rewards

List customer rewards

Returns the rewards this specific customer has redeemed or is eligible for.

Auth: Customer sessionrewards:readcustomers:read

Parameters

Name	Type	Description
`customerId`	string	Required when using a tenant API key

Response

200 OK

{
  "data": {
    "eligible": [
      {
        "id": "rwd_01HY2F8Z3M7K8XQRBV4N2YJWPD",
        "name": "Free coffee",
        "pointsCost": 500,
        "affordable": true
      }
    ],
    "history": [
      {
        "id": "redm_01HY2F8Z3M7K8XQRBV4N2YJWPD",
        "rewardName": "Free pastry",
        "pointsDebited": 250,
        "redeemedAt": "2026-03-14T12:00:00.000Z"
      }
    ]
  }
}

Customer booking

Endpoints for letting a customer book themselves — for branded booking pages and white-label apps.

POST/api/v1/me/bookings

Create a booking

Create a new booking on behalf of the current customer. The customer is identified by the session cookie or by passing customerId explicitly when using a tenant API key.

Auth: Customer sessionbookings:write

Request body

Request

{
  "customerId": "cust_01HY2F8Z3M7K8XQRBV4N2YJWPD",
  "serviceId": "svc_01HY2F8Z3M7K8XQRBV4N2YJWPD",
  "startAt": "2026-04-12T14:00:00.000Z",
  "notes": "Coming in for a trim before the wedding"
}

Response

200 OK

{
  "data": {
    "id": "bkng_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "status": "PENDING",
    "startAt": "2026-04-12T14:00:00.000Z",
    "endAt": "2026-04-12T15:00:00.000Z",
    "confirmationCode": "VR7K8X"
  }
}

DELETE/api/v1/me/bookings/:id

Cancel a booking

Lets a customer cancel their own upcoming booking. Respects the shop's cancellation cutoff — returns 409 if the cutoff has passed.

Auth: Customer sessionbookings:write

Parameters

Name	Type	Description
`id`*	string	Booking ID

Response

200 OK

{
  "data": {
    "id": "bkng_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "status": "CANCELLED",
    "cancelledAt": "2026-04-10T09:14:22.000Z"
  }
}

POST/api/v1/me/rewards/:id/redeem

Redeem a reward

Let a customer redeem one of the rewards they're eligible for. Debits points and returns the new balance.

Auth: Customer sessionrewards:write

Parameters

Name	Type	Description
`id`*	string	Reward ID

Request body

Request

{
  "customerId": "cust_01HY2F8Z3M7K8XQRBV4N2YJWPD"
}

Response

200 OK

{
  "data": {
    "id": "redm_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "rewardId": "rwd_01HY2F8Z3M7K8XQRBV4N2YJWPD",
    "pointsDebited": 500,
    "balanceAfter": 747,
    "redeemedAt": "2026-04-10T09:14:22.000Z"
  }
}

← Back to introduction Review authentication