Developer reference

Livwell Open API

A read-focused, key-authenticated REST API for pulling a business's payments, memberships, catalog and directory data, plus signed webhooks for real-time events. Every request is scoped to a single branch and gated by fine-grained scopes.

Production base URL

https://platform-api.golivwell.com

Live data and real money. Use production credentials.

Get started

Quickstart

1.In the Livwell dashboard, open Settings → Developer / API and create an API key. Copy the access key and secret; the secret is shown only once.
2.Pick the branch you want to read from and note its id. Every request must carry it in the X-Branch-Id header.
3.Call any endpoint with the three headers below.

curl https://platform-api.golivwell.com/api/v1/open/payment/history \
  -H "X-Access-Key: ak_live_..." \
  -H "X-Secret-Key: sk_live_..." \
  -H "X-Branch-Id: 3fa85f64-5717-4562-b3fc-2c963f66afa6"

Security

Authentication

Partner endpoints under /api/v1/open authenticate with three request headers, not a bearer token. Credentials are verified in constant time; the secret is stored hashed and can never be retrieved after creation.

`X-Access-Key`	Public key handle, format ak_...	Required
`X-Secret-Key`	Secret, format sk_...	Required
`X-Branch-Id`	UUID of the branch to read from	Required

A key is either business-wide or locked to one branch. Branch-locked keys only accept their own branch id.
Keys may carry an IP allowlist (CIDR). Requests from outside the allowlist are rejected.
Keys expire (default two years) and can be rotated or revoked at any time.

Security

Scopes

Each endpoint requires a scope. A key is granted only the scopes it needs. Scopes ending in :READ_PII unlock personal data and require a step-up confirmation when the key is created or rotated.

Scope	Grants
`PAYMENT:READ`	Read transactions and revenue summary.
`PAYMENT:READ_PII` pii	Include client name and email on transactions.
`PAYMENT:EXPORT`	Export transaction history as CSV.
`EVENT:READ`	Read the event catalog.
`MEMBERSHIP:READ`	Read membership records.
`MEMBERSHIP:READ_PII` pii	Include the purchaser name on memberships.
`CHECKIN:READ`	Read check-in / attendance events.
`CHECKIN:READ_PII` pii	Include the client name on check-ins.
`BOOKING:READ`	Read booking occurrences (occupancy feed).
`ORDER:READ`	Read storefront orders.
`PACKAGE:READ`	Read the package catalog.
`GUEST_PASS:READ`	Read guest passes.
`CLIENT:READ_PII` pii	Read client directory. Inherently PII.
`DIRECTORY:READ`	Read branch and staff directory.
`PAYOUT:READ`	Read payouts and available balance.

Data handling

PII & redaction

Personal fields (names, emails, phone numbers) are redacted by default. They appear only when the key holds the matching :READ_PII scope; otherwise the field is omitted from the JSON entirely. PII fields are marked with a pii badge throughout this reference.

Limits

Rate limits

Each key has an hourly request quota (default 1,000 requests/hour, configurable per key). Exceeding it returns 429 Too Many Requests. Back off and retry after the window resets.

Conventions

Pagination

List endpoints accept page (1-based, default 1) and pageSize (default 20, max 100), and return the envelope below. Note the request page is 1-based while the pagination.page in the response is 0-based.

{
  "data": [ /* array of items */ ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 137,
    "totalPages": 7
  }
}

Conventions

Errors

Errors follow RFC 9457 Problem Details (application/problem+json) and include a traceId for support.

Status	Code	Meaning
400	`MISSING_BRANCH_ID / PAGE_NUMBER_INVALID / PAGE_SIZE_INVALID`	Missing or malformed X-Branch-Id, or invalid paging arguments.
401	`Invalid API credentials`	Unknown access key, wrong secret, or an expired key.
403	`Forbidden`	The key lacks the scope required for this endpoint.
404	`RESOURCE_NOT_FOUND`	The resource does not exist or is outside the key's branch.
429	`Rate limit exceeded`	Hourly request quota for the key was reached.

Payments

Transaction history, revenue summary and CSV export.

GET/api/v1/open/payment/historySCOPE PAYMENT:READ

List transactions

Paginated transaction history for the key's branch, with rich filtering.

GET https://platform-api.golivwell.com/api/v1/open/payment/history

Query parameters

`status`	`string[]`	Filter by one or more payment statuses.
`ownerType`	`string`	Filter by owner type (MEMBERSHIP, EVENT, ...).
`mode`	`string`	Filter by payment mode.
`currency`	`string`	Filter by currency.
`from`	`instant`	ISO-8601 start of window (inclusive).
`to`	`instant`	ISO-8601 end of window (inclusive).
`clientId`	`UUID`	Filter by client.
`couponUsed`	`boolean`	Only transactions where a coupon was used.
`refunded`	`boolean`	Only refunded transactions.
`search`	`string`	Free-text search.
`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).
`sort`	`string`default: createdAt	Sort field.
`sortDirection`	`string`default: DESC	ASC or DESC.

Response OpenApiTransactionResponse (paginated)

A payment transaction (sales ledger entry).

Field	Type	Description
`id`	`UUID`	Transaction id.
`businessId`	`UUID`	Owning business.
`branchId`	`UUID`nullable	Branch, if branch-scoped.
`ownerType`	`string`	What the payment was for, e.g. MEMBERSHIP, EVENT, ORDER.
`currency`	`string`	ISO 4217 currency code.
`subtotalAmount`	`decimal`	Amount before tax, fees and discount.
`taxAmount`	`decimal`	Tax charged.
`feeAmount`	`decimal`	Processing / platform fee.
`discountAmount`	`decimal`	Discount applied.
`grossAmount`	`decimal`	Total charged to the customer.
`refundedAmount`	`decimal`	Amount refunded so far.
`status`	`string`	Payment status, e.g. SUCCEEDED, REFUNDED.
`description`	`string`nullable	Human-readable description.
`clientName`	`string`nullable pii	Requires PAYMENT:READ_PII.
`clientEmail`	`string`nullable pii	Requires PAYMENT:READ_PII.
`createdAt`	`instant`	Creation timestamp (ISO-8601, UTC).

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "ownerType": "MEMBERSHIP",
      "currency": "USD",
      "subtotalAmount": 49.99,
      "taxAmount": 49.99,
      "feeAmount": 49.99,
      "discountAmount": 49.99,
      "grossAmount": 49.99,
      "refundedAmount": 49.99,
      "status": "ACTIVE",
      "description": "string",
      "clientName": "Jane Doe",
      "clientEmail": "jane@example.com",
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/payment/history/exportSCOPE PAYMENT:EXPORT

Export transactions (CSV)

Streams matching transactions as a CSV attachment. Same filters as the list endpoint (no paging).

GET https://platform-api.golivwell.com/api/v1/open/payment/history/export

Query parameters

`status`	`string[]`	Filter by payment statuses.
`ownerType`	`string`	Filter by owner type.
`mode`	`string`	Filter by payment mode.
`currency`	`string`	Filter by currency.
`from`	`instant`	ISO-8601 start of window (inclusive).
`to`	`instant`	ISO-8601 end of window (inclusive).
`clientId`	`UUID`	Filter by client.
`couponUsed`	`boolean`	Coupon-used only.
`refunded`	`boolean`	Refunded only.
`search`	`string`	Free-text search.

Capped at 50,000 rows.
Columns: id, createdAt, ownerType, status, currency, subtotalAmount, taxAmount, feeAmount, discountAmount, grossAmount, refundedAmount, description. clientName and clientEmail columns are added only when the key holds PAYMENT:READ_PII.
Returns Content-Disposition: attachment; filename=transactions.csv.

Returns text/csv.

GET/api/v1/open/payment/history/{transactionId}SCOPE PAYMENT:READ

Get a transaction

A single transaction. Must belong to the key's branch.

GET https://platform-api.golivwell.com/api/v1/open/payment/history/{transactionId}

Path parameters

transactionId

UUIDrequired

Transaction id.

Response OpenApiTransactionResponse

A payment transaction (sales ledger entry).

Field	Type	Description
`id`	`UUID`	Transaction id.
`businessId`	`UUID`	Owning business.
`branchId`	`UUID`nullable	Branch, if branch-scoped.
`ownerType`	`string`	What the payment was for, e.g. MEMBERSHIP, EVENT, ORDER.
`currency`	`string`	ISO 4217 currency code.
`subtotalAmount`	`decimal`	Amount before tax, fees and discount.
`taxAmount`	`decimal`	Tax charged.
`feeAmount`	`decimal`	Processing / platform fee.
`discountAmount`	`decimal`	Discount applied.
`grossAmount`	`decimal`	Total charged to the customer.
`refundedAmount`	`decimal`	Amount refunded so far.
`status`	`string`	Payment status, e.g. SUCCEEDED, REFUNDED.
`description`	`string`nullable	Human-readable description.
`clientName`	`string`nullable pii	Requires PAYMENT:READ_PII.
`clientEmail`	`string`nullable pii	Requires PAYMENT:READ_PII.
`createdAt`	`instant`	Creation timestamp (ISO-8601, UTC).

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "ownerType": "MEMBERSHIP",
  "currency": "USD",
  "subtotalAmount": 49.99,
  "taxAmount": 49.99,
  "feeAmount": 49.99,
  "discountAmount": 49.99,
  "grossAmount": 49.99,
  "refundedAmount": 49.99,
  "status": "ACTIVE",
  "description": "string",
  "clientName": "Jane Doe",
  "clientEmail": "jane@example.com",
  "createdAt": "2026-09-15T09:30:00Z"
}

GET/api/v1/open/payment/summarySCOPE PAYMENT:READ

Revenue summary

Aggregate revenue over a window, broken down by owner type.

GET https://platform-api.golivwell.com/api/v1/open/payment/summary

Query parameters

`from`	`instant`	Window start. Defaults to 30 days ago.
`to`	`instant`	Window end. Defaults to now.

Response OpenApiRevenueSummaryResponse

Aggregate revenue over a window, broken down by owner type.

Field	Type	Description
`from`	`instant`	Window start.
`to`	`instant`	Window end.
`grossAmount`	`decimal`	Total gross revenue.
`refundedAmount`	`decimal`	Total refunded.
`netAmount`	`decimal`	Gross minus refunds.
`transactionCount`	`long`	Number of transactions.
`byOwnerType`	`Line[]`	Per owner-type breakdown (see Line).

Example response

{
  "from": "2026-09-15T09:30:00Z",
  "to": "2026-09-15T09:30:00Z",
  "grossAmount": 49.99,
  "refundedAmount": 49.99,
  "netAmount": 49.99,
  "transactionCount": 128,
  "byOwnerType": [
    {
      "ownerType": "MEMBERSHIP",
      "grossAmount": 49.99,
      "refundedAmount": 49.99,
      "transactionCount": 128
    }
  ]
}

Catalog & records

Events, memberships, orders, packages, guest passes and check-ins.

GET/api/v1/open/eventsSCOPE EVENT:READ

List events

The branch's event catalog.

GET https://platform-api.golivwell.com/api/v1/open/events

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiEventResponse (paginated)

Field	Type	Description
`id`	`UUID`	Event id.
`branchId`	`UUID`nullable	Host branch.
`branchName`	`string`nullable	Host branch name.
`name`	`string`	Event name.
`summary`	`string`nullable	Short summary.
`eventType`	`string`	Event type.
`scheduleType`	`string`	Schedule type.
`status`	`string`	Lifecycle status.
`basePrice`	`decimal`nullable	Base ticket price.
`currency`	`string`nullable	Currency of basePrice.
`maxCapacity`	`integer`nullable	Capacity cap.
`imageUrl`	`string`nullable	Cover image.
`nextSessionDate`	`date`nullable	Next session date.
`lastSessionDate`	`date`nullable	Last session date.
`hasEnded`	`boolean`	Whether all sessions have passed.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchName": "string",
      "name": "Sunrise Yoga",
      "summary": "string",
      "eventType": "CLASS",
      "scheduleType": "RECURRING",
      "status": "ACTIVE",
      "basePrice": 49.99,
      "currency": "USD",
      "maxCapacity": 20,
      "imageUrl": "string",
      "nextSessionDate": "2026-09-15",
      "lastSessionDate": "2026-09-15",
      "hasEnded": true,
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/membershipsSCOPE MEMBERSHIP:READ

List memberships

Business-level membership records.

GET https://platform-api.golivwell.com/api/v1/open/memberships

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

purchaserName is included only when the key holds MEMBERSHIP:READ_PII.

Response OpenApiMembershipResponse (paginated)

Field	Type	Description
`id`	`UUID`	Membership record id.
`purchaserClientId`	`UUID`	Client who purchased.
`planId`	`UUID`	Membership plan id.
`planName`	`string`	Plan name.
`status`	`string`	Membership status.
`currentPeriodStart`	`instant`nullable	Current period start.
`currentPeriodEnd`	`instant`nullable	Current period end.
`autoRenew`	`boolean`	Auto-renew enabled.
`complimentary`	`boolean`	Complimentary (free) membership.
`cancelEffectiveAt`	`instant`nullable	When cancellation takes effect.
`seatsUsed`	`integer`	Seats used (shared plans).
`seatsTotal`	`integer`	Total seats.
`purchaserName`	`string`nullable pii	Requires MEMBERSHIP:READ_PII.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "purchaserClientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "planId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "planName": "Unlimited Monthly",
      "status": "ACTIVE",
      "currentPeriodStart": "2026-09-15T09:30:00Z",
      "currentPeriodEnd": "2026-09-15T09:30:00Z",
      "autoRenew": true,
      "complimentary": true,
      "cancelEffectiveAt": "2026-09-15T09:30:00Z",
      "seatsUsed": 20,
      "seatsTotal": 20,
      "purchaserName": "Jane Doe"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/checkinsSCOPE CHECKIN:READ

List check-ins

Attendance / check-in events.

GET https://platform-api.golivwell.com/api/v1/open/checkins

Query parameters

`from`	`instant`	ISO-8601 start of window (inclusive).
`to`	`instant`	ISO-8601 end of window (inclusive).
`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

clientName is included only when the key holds CHECKIN:READ_PII.

Response OpenApiCheckInResponse (paginated)

Field	Type	Description
`checkInId`	`UUID`	Check-in id.
`scannedAt`	`instant`	When the check-in was scanned.
`clientId`	`UUID`nullable	Client, if identified.
`membershipRecordId`	`UUID`nullable	Membership used.
`planName`	`string`nullable	Plan used.
`branchId`	`UUID`nullable	Branch scanned at.
`branchName`	`string`nullable	Branch name.
`statusAtScan`	`string`nullable	Access status at scan time.
`clientName`	`string`nullable pii	Requires CHECKIN:READ_PII.

Example response

{
  "data": [
    {
      "checkInId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "scannedAt": "2026-09-15T09:30:00Z",
      "clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "membershipRecordId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "planName": "Unlimited Monthly",
      "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchName": "string",
      "statusAtScan": "string",
      "clientName": "Jane Doe"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/ordersSCOPE ORDER:READ

List orders

Storefront orders.

GET https://platform-api.golivwell.com/api/v1/open/orders

Query parameters

`from`	`instant`	ISO-8601 start of window (inclusive).
`to`	`instant`	ISO-8601 end of window (inclusive).
`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiOrderResponse (paginated)

Field	Type	Description
`id`	`UUID`	Order id.
`businessId`	`UUID`	Owning business.
`branchId`	`UUID`nullable	Branch.
`clientId`	`UUID`nullable	Purchasing client.
`orderNumber`	`string`	Human-readable order number.
`subtotal`	`decimal`	Subtotal.
`taxTotal`	`decimal`	Tax total.
`discountAmount`	`decimal`	Discount applied.
`totalAmount`	`decimal`	Order total.
`currency`	`string`	Currency.
`status`	`string`	Order status.
`purchaseChannel`	`string`nullable	e.g. ONLINE, POS.
`paymentMethod`	`string`nullable	Payment method.
`paidAt`	`instant`nullable	Paid timestamp.
`fulfilledAt`	`instant`nullable	Fulfilled timestamp.
`cancelledAt`	`instant`nullable	Cancelled timestamp.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "orderNumber": "ORD-10432",
      "subtotal": 49.99,
      "taxTotal": 49.99,
      "discountAmount": 49.99,
      "totalAmount": 49.99,
      "currency": "USD",
      "status": "ACTIVE",
      "purchaseChannel": "string",
      "paymentMethod": "string",
      "paidAt": "2026-09-15T09:30:00Z",
      "fulfilledAt": "2026-09-15T09:30:00Z",
      "cancelledAt": "2026-09-15T09:30:00Z",
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/orders/{orderId}SCOPE ORDER:READ

Get an order

A single storefront order.

GET https://platform-api.golivwell.com/api/v1/open/orders/{orderId}

Path parameters

orderId

UUIDrequired

Order id.

Response OpenApiOrderResponse

Field	Type	Description
`id`	`UUID`	Order id.
`businessId`	`UUID`	Owning business.
`branchId`	`UUID`nullable	Branch.
`clientId`	`UUID`nullable	Purchasing client.
`orderNumber`	`string`	Human-readable order number.
`subtotal`	`decimal`	Subtotal.
`taxTotal`	`decimal`	Tax total.
`discountAmount`	`decimal`	Discount applied.
`totalAmount`	`decimal`	Order total.
`currency`	`string`	Currency.
`status`	`string`	Order status.
`purchaseChannel`	`string`nullable	e.g. ONLINE, POS.
`paymentMethod`	`string`nullable	Payment method.
`paidAt`	`instant`nullable	Paid timestamp.
`fulfilledAt`	`instant`nullable	Fulfilled timestamp.
`cancelledAt`	`instant`nullable	Cancelled timestamp.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "clientId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "orderNumber": "ORD-10432",
  "subtotal": 49.99,
  "taxTotal": 49.99,
  "discountAmount": 49.99,
  "totalAmount": 49.99,
  "currency": "USD",
  "status": "ACTIVE",
  "purchaseChannel": "string",
  "paymentMethod": "string",
  "paidAt": "2026-09-15T09:30:00Z",
  "fulfilledAt": "2026-09-15T09:30:00Z",
  "cancelledAt": "2026-09-15T09:30:00Z",
  "createdAt": "2026-09-15T09:30:00Z"
}

GET/api/v1/open/packagesSCOPE PACKAGE:READ

List packages

The package catalog.

GET https://platform-api.golivwell.com/api/v1/open/packages

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiPackageResponse (paginated)

Field	Type	Description
`id`	`UUID`	Package id.
`branchId`	`UUID`nullable	Branch.
`branchName`	`string`nullable	Branch name.
`categoryName`	`string`nullable	Category.
`packageName`	`string`	Package name.
`slug`	`string`nullable	URL slug.
`price`	`decimal`	Price.
`currency`	`string`	Currency.
`onlineSale`	`boolean`	Sold online.
`published`	`boolean`	Published / visible.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchName": "string",
      "categoryName": "string",
      "packageName": "10-Class Pack",
      "slug": "string",
      "price": 49.99,
      "currency": "USD",
      "onlineSale": true,
      "published": true,
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/guest-passesSCOPE GUEST_PASS:READ

List guest passes

Business-level guest passes.

GET https://platform-api.golivwell.com/api/v1/open/guest-passes

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiGuestPassResponse (paginated)

Field	Type	Description
`id`	`UUID`	Guest pass id.
`name`	`string`	Internal name.
`customerLabel`	`string`nullable	Customer-facing label.
`accessCount`	`integer`	Number of accesses granted.
`validityRule`	`string`	Validity rule.
`price`	`decimal`	Price.
`currency`	`string`	Currency.
`status`	`string`	Status.
`saleStartAt`	`instant`nullable	Sale window start.
`saleEndAt`	`instant`nullable	Sale window end.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Sunrise Yoga",
      "customerLabel": "string",
      "accessCount": 20,
      "validityRule": "string",
      "price": 49.99,
      "currency": "USD",
      "status": "ACTIVE",
      "saleStartAt": "2026-09-15T09:30:00Z",
      "saleEndAt": "2026-09-15T09:30:00Z",
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

Clients

Client directory. Inherently PII.

GET/api/v1/open/clientsSCOPE CLIENT:READ_PII

List clients

Client directory for the business.

GET https://platform-api.golivwell.com/api/v1/open/clients

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiClientResponse (paginated)

Client directory record. Inherently PII (requires CLIENT:READ_PII). Excludes health data, financials and notes.

Field	Type	Description
`id`	`UUID`	Client id.
`businessId`	`UUID`	Owning business.
`branchId`	`UUID`nullable	Home branch.
`memberNumber`	`string`nullable	Member number.
`firstName`	`string`nullable pii	First name.
`lastName`	`string`nullable pii	Last name.
`preferredName`	`string`nullable pii	Preferred name.
`email`	`string`nullable pii	Email.
`phone`	`string`nullable pii	Phone.
`status`	`string`	Client status.
`joinedAt`	`instant`nullable	Join date.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "memberNumber": "MEM-0087",
      "firstName": "Jane",
      "lastName": "Doe",
      "preferredName": "string",
      "email": "jane@example.com",
      "phone": "string",
      "status": "ACTIVE",
      "joinedAt": "2026-09-15T09:30:00Z",
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/clients/{clientId}SCOPE CLIENT:READ_PII

Get a client

A single client record.

GET https://platform-api.golivwell.com/api/v1/open/clients/{clientId}

Path parameters

clientId

UUIDrequired

Client id.

Response OpenApiClientResponse

Client directory record. Inherently PII (requires CLIENT:READ_PII). Excludes health data, financials and notes.

Field	Type	Description
`id`	`UUID`	Client id.
`businessId`	`UUID`	Owning business.
`branchId`	`UUID`nullable	Home branch.
`memberNumber`	`string`nullable	Member number.
`firstName`	`string`nullable pii	First name.
`lastName`	`string`nullable pii	Last name.
`preferredName`	`string`nullable pii	Preferred name.
`email`	`string`nullable pii	Email.
`phone`	`string`nullable pii	Phone.
`status`	`string`	Client status.
`joinedAt`	`instant`nullable	Join date.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "memberNumber": "MEM-0087",
  "firstName": "Jane",
  "lastName": "Doe",
  "preferredName": "string",
  "email": "jane@example.com",
  "phone": "string",
  "status": "ACTIVE",
  "joinedAt": "2026-09-15T09:30:00Z",
  "createdAt": "2026-09-15T09:30:00Z"
}

Directory & finance

Branches, staff, payouts, balance and the occupancy feed.

GET/api/v1/open/directory/branchesSCOPE DIRECTORY:READ

List branches

Branch directory.

GET https://platform-api.golivwell.com/api/v1/open/directory/branches

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiBranchResponse (paginated)

Field	Type	Description
`id`	`UUID`	Branch id.
`name`	`string`	Branch name.
`code`	`string`nullable	Branch code.
`status`	`string`	Branch status.
`headquarters`	`boolean`	Is headquarters.
`email`	`string`nullable	Contact email.
`phone`	`string`nullable	Contact phone.
`timezone`	`string`nullable	IANA timezone.
`capacity`	`integer`nullable	Capacity.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Sunrise Yoga",
      "code": "string",
      "status": "ACTIVE",
      "headquarters": true,
      "email": "jane@example.com",
      "phone": "string",
      "timezone": "Africa/Lagos",
      "capacity": 20,
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/directory/staffSCOPE DIRECTORY:READ

List staff

Staff directory (role and display fields only).

GET https://platform-api.golivwell.com/api/v1/open/directory/staff

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiStaffResponse (paginated)

Staff directory entry. Role and display fields only.

Field	Type	Description
`id`	`UUID`	Staff id.
`primaryBranchId`	`UUID`nullable	Primary branch.
`firstName`	`string`nullable	First name.
`lastName`	`string`nullable	Last name.
`preferredName`	`string`nullable	Preferred name.
`jobTitle`	`string`nullable	Job title.
`department`	`string`nullable	Department.
`status`	`string`	Employment status.
`photoUrl`	`string`nullable	Profile photo.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "primaryBranchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "firstName": "Jane",
      "lastName": "Doe",
      "preferredName": "string",
      "jobTitle": "string",
      "department": "string",
      "status": "ACTIVE",
      "photoUrl": "string",
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/payoutsSCOPE PAYOUT:READ

List payouts

Business-level payouts.

GET https://platform-api.golivwell.com/api/v1/open/payouts

Query parameters

`page`	`integer`default: 1	1-based page number (must be >= 1).
`pageSize`	`integer`default: 20	Page size (max 100).

Response OpenApiPayoutResponse (paginated)

Field	Type	Description
`id`	`UUID`	Payout id.
`amount`	`decimal`	Payout amount.
`currency`	`string`	Currency.
`status`	`string`	Payout status.
`railReference`	`string`nullable	Bank / rail reference.
`destinationMasked`	`string`nullable	Masked destination account.
`periodStart`	`instant`nullable	Settlement period start.
`periodEnd`	`instant`nullable	Settlement period end.
`settledAt`	`instant`nullable	Settled timestamp.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "data": [
    {
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "amount": 49.99,
      "currency": "USD",
      "status": "ACTIVE",
      "railReference": "string",
      "destinationMasked": "string",
      "periodStart": "2026-09-15T09:30:00Z",
      "periodEnd": "2026-09-15T09:30:00Z",
      "settledAt": "2026-09-15T09:30:00Z",
      "createdAt": "2026-09-15T09:30:00Z"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "totalElements": 1,
    "totalPages": 1
  }
}

GET/api/v1/open/balanceSCOPE PAYOUT:READ

Get balance

Pending and available balance for the business.

GET https://platform-api.golivwell.com/api/v1/open/balance

Response OpenApiBalanceResponse

Field	Type	Description
`pendingAmount`	`decimal`	Funds not yet available.
`availableAmount`	`decimal`	Funds available for payout.
`currency`	`string`	Currency.

Example response

{
  "pendingAmount": 49.99,
  "availableAmount": 49.99,
  "currency": "USD"
}

GET/api/v1/open/bookings/occurrencesSCOPE BOOKING:READ

Booking occupancy feed

Occupancy across bookable surfaces in a window. Returns a bare JSON array (not paginated).

GET https://platform-api.golivwell.com/api/v1/open/bookings/occurrences

Query parameters

`from`	`instant`	ISO-8601 start of window (inclusive).
`to`	`instant`	ISO-8601 end of window (inclusive).

Response OpenApiBookingOccurrenceResponse (array)

An occupancy feed entry across bookable surfaces.

Field	Type	Description
`surface`	`string`	Bookable surface, e.g. APPOINTMENT, FACILITY.
`occurrenceId`	`UUID`	Occurrence id.
`resourceCatalogId`	`UUID`nullable	Underlying resource.
`branchId`	`UUID`nullable	Branch.
`title`	`string`	Occurrence title.
`startAt`	`instant`	Start time.
`endAt`	`instant`	End time.
`bookingCount`	`long`	Number of bookings on this occurrence.

Example response

[
  {
    "surface": "APPOINTMENT",
    "occurrenceId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "resourceCatalogId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "branchId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "string",
    "startAt": "2026-09-15T09:30:00Z",
    "endAt": "2026-09-15T09:30:00Z",
    "bookingCount": 128
  }
]

Real-time

Webhooks

Receiving events

Register an HTTPS endpoint and subscribe to the events you care about. Livwell POSTs a JSON payload for each event, signs it, and retries failed deliveries with exponential backoff (up to 5 attempts). Respond with a 2xx to acknowledge.

POST https://your-app.com/livwell/webhooks
X-Livwell-Signature: sha256=<hex>
X-Webhook-Event: payment.succeeded
Content-Type: application/json

{
  "id": "evt_9f2c...",
  "event": "payment.succeeded",
  "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "createdAt": "2026-09-15T09:30:00Z",
  "data": { }
}

Verifying signatures

Every delivery carries an X-Livwell-Signature header of the form sha256=<hex>: an HMAC-SHA256 of the raw request body using your endpoint's signing secret. Compute the same HMAC and compare in constant time. Always verify against the raw bytes, before any JSON parsing.

import crypto from "node:crypto";

function isValid(rawBody, signatureHeader, signingSecret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", signingSecret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

Event types

Event	Constant	Fires when
`payment.succeeded`	`PAYMENT_SUCCEEDED`	A payment is captured successfully.
`payment.refunded`	`PAYMENT_REFUNDED`	A payment is fully refunded.
`payment.partially_refunded`	`PAYMENT_PARTIALLY_REFUNDED`	A payment is partially refunded.
`membership.activated`	`MEMBERSHIP_ACTIVATED`	A membership becomes active.
`membership.renewed`	`MEMBERSHIP_RENEWED`	A membership renews for a new period.
`booking.completed`	`BOOKING_COMPLETED`	A booking is marked completed.
`booking.checked_in`	`BOOKING_CHECKED_IN`	An attendee checks in to a booking.
`order.fulfilled`	`ORDER_FULFILLED`	A storefront order is fulfilled.
`package.purchased`	`PACKAGE_PURCHASED`	A package is purchased.

Provisioning

Managing webhooks

The endpoints below register and manage webhook endpoints. They authenticate with a user JWT (Authorization: Bearer) and are what the Livwell dashboard calls under the hood. API keys themselves are created and managed in the dashboard under Settings → Developer / API.

Webhook endpoints

POST/api/v1/businesses/{businessId}/webhooksWEBHOOK:CREATE

Create an endpoint

Registers a webhook endpoint and returns the signing secret once.

POST https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks
Authorization: Bearer <jwt>

Path parameters

businessId

UUIDrequired

Business id.

Request body WebhookEndpointCreateRequest

Field	Type	Description
`url`	`string`	Required. Destination URL, max 1000 chars.
`description`	`string`nullable	Label, max 300 chars.
`events`	`string[]`	Required, non-empty. Event constants to subscribe to.

Response WebhookEndpointCreationResponse

Returned once on create/rotate-secret. The signing secret is shown only once.

Field	Type	Description
`id`	`UUID`	Endpoint id.
`url`	`string`	Destination URL.
`signingSecret`	`string`	HMAC signing secret. Shown once.
`events`	`string[]`	Subscribed event types.
`warning`	`string`	Reminder that the secret is shown only once.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://example.com/livwell/webhooks",
  "signingSecret": "whsec_shown_once_do_not_share_xxxxxxxxxx",
  "events": [
    "string"
  ],
  "warning": "Store this secret now. It cannot be retrieved again."
}

GET/api/v1/businesses/{businessId}/webhooksWEBHOOK:LIST

List endpoints

All webhook endpoints for the business.

GET https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks
Authorization: Bearer <jwt>

Path parameters

businessId

UUIDrequired

Business id.

Response WebhookEndpointResponse (array)

Webhook endpoint metadata. Never carries the signing secret.

Field	Type	Description
`id`	`UUID`	Endpoint id.
`businessId`	`UUID`	Owning business.
`url`	`string`	Destination URL.
`description`	`string`nullable	Label.
`events`	`string[]`	Subscribed event types.
`active`	`boolean`	Whether deliveries are sent.
`secretSet`	`boolean`	Whether a signing secret exists.
`createdAt`	`instant`	Creation timestamp.

Example response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "url": "https://example.com/livwell/webhooks",
    "description": "string",
    "events": [
      "string"
    ],
    "active": true,
    "secretSet": true,
    "createdAt": "2026-09-15T09:30:00Z"
  }
]

GET/api/v1/businesses/{businessId}/webhooks/{endpointId}WEBHOOK:READ

Get an endpoint

A single webhook endpoint.

GET https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks/{endpointId}
Authorization: Bearer <jwt>

Path parameters

`businessId`	`UUID`required	Business id.
`endpointId`	`UUID`required	Endpoint id.

Response WebhookEndpointResponse

Webhook endpoint metadata. Never carries the signing secret.

Field	Type	Description
`id`	`UUID`	Endpoint id.
`businessId`	`UUID`	Owning business.
`url`	`string`	Destination URL.
`description`	`string`nullable	Label.
`events`	`string[]`	Subscribed event types.
`active`	`boolean`	Whether deliveries are sent.
`secretSet`	`boolean`	Whether a signing secret exists.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://example.com/livwell/webhooks",
  "description": "string",
  "events": [
    "string"
  ],
  "active": true,
  "secretSet": true,
  "createdAt": "2026-09-15T09:30:00Z"
}

PUT/api/v1/businesses/{businessId}/webhooks/{endpointId}WEBHOOK:UPDATE

Update an endpoint

Update URL, description, events or active state.

PUT https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks/{endpointId}
Authorization: Bearer <jwt>

Path parameters

`businessId`	`UUID`required	Business id.
`endpointId`	`UUID`required	Endpoint id.

Request body WebhookEndpointUpdateRequest

PATCH-style: null fields are left unchanged.

Field	Type	Description
`url`	`string`nullable	New destination URL.
`description`	`string`nullable	New label.
`events`	`string[]`nullable	New event subscription set.
`active`	`boolean`nullable	Enable/disable deliveries.

Response WebhookEndpointResponse

Webhook endpoint metadata. Never carries the signing secret.

Field	Type	Description
`id`	`UUID`	Endpoint id.
`businessId`	`UUID`	Owning business.
`url`	`string`	Destination URL.
`description`	`string`nullable	Label.
`events`	`string[]`	Subscribed event types.
`active`	`boolean`	Whether deliveries are sent.
`secretSet`	`boolean`	Whether a signing secret exists.
`createdAt`	`instant`	Creation timestamp.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://example.com/livwell/webhooks",
  "description": "string",
  "events": [
    "string"
  ],
  "active": true,
  "secretSet": true,
  "createdAt": "2026-09-15T09:30:00Z"
}

POST/api/v1/businesses/{businessId}/webhooks/{endpointId}/rotate-secretWEBHOOK:UPDATE

Rotate signing secret

Issues a new signing secret and returns it once.

POST https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks/{endpointId}/rotate-secret
Authorization: Bearer <jwt>

Path parameters

`businessId`	`UUID`required	Business id.
`endpointId`	`UUID`required	Endpoint id.

Response WebhookEndpointCreationResponse

Returned once on create/rotate-secret. The signing secret is shown only once.

Field	Type	Description
`id`	`UUID`	Endpoint id.
`url`	`string`	Destination URL.
`signingSecret`	`string`	HMAC signing secret. Shown once.
`events`	`string[]`	Subscribed event types.
`warning`	`string`	Reminder that the secret is shown only once.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "url": "https://example.com/livwell/webhooks",
  "signingSecret": "whsec_shown_once_do_not_share_xxxxxxxxxx",
  "events": [
    "string"
  ],
  "warning": "Store this secret now. It cannot be retrieved again."
}

POST/api/v1/businesses/{businessId}/webhooks/{endpointId}/testWEBHOOK:UPDATE

Send a test event

Delivers a test payload to the endpoint and returns the delivery result.

POST https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks/{endpointId}/test
Authorization: Bearer <jwt>

Path parameters

`businessId`	`UUID`required	Business id.
`endpointId`	`UUID`required	Endpoint id.

Response WebhookDeliveryResponse

Field	Type	Description
`id`	`UUID`	Delivery id.
`eventType`	`string`	Event type delivered.
`status`	`string`	Delivery status.
`responseCode`	`integer`nullable	HTTP status returned by your endpoint.
`error`	`string`nullable	Failure detail, if any.
`attempts`	`integer`	Delivery attempts so far.
`createdAt`	`instant`	Creation timestamp.
`lastAttemptAt`	`instant`nullable	Last attempt timestamp.

Example response

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "eventType": "CLASS",
  "status": "ACTIVE",
  "responseCode": 20,
  "error": "string",
  "attempts": 20,
  "createdAt": "2026-09-15T09:30:00Z",
  "lastAttemptAt": "2026-09-15T09:30:00Z"
}

GET/api/v1/businesses/{businessId}/webhooks/{endpointId}/deliveriesWEBHOOK:READ

List deliveries

Recent delivery attempts for an endpoint.

GET https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks/{endpointId}/deliveries
Authorization: Bearer <jwt>

Path parameters

`businessId`	`UUID`required	Business id.
`endpointId`	`UUID`required	Endpoint id.

Query parameters

limit

integerdefault: 50

Deliveries to return.

Response WebhookDeliveryResponse (array)

Field	Type	Description
`id`	`UUID`	Delivery id.
`eventType`	`string`	Event type delivered.
`status`	`string`	Delivery status.
`responseCode`	`integer`nullable	HTTP status returned by your endpoint.
`error`	`string`nullable	Failure detail, if any.
`attempts`	`integer`	Delivery attempts so far.
`createdAt`	`instant`	Creation timestamp.
`lastAttemptAt`	`instant`nullable	Last attempt timestamp.

Example response

[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "eventType": "CLASS",
    "status": "ACTIVE",
    "responseCode": 20,
    "error": "string",
    "attempts": 20,
    "createdAt": "2026-09-15T09:30:00Z",
    "lastAttemptAt": "2026-09-15T09:30:00Z"
  }
]

DELETE/api/v1/businesses/{businessId}/webhooks/{endpointId}WEBHOOK:DELETE

Delete an endpoint

Removes the endpoint. Returns 204.

DELETE https://platform-api.golivwell.com/api/v1/businesses/{businessId}/webhooks/{endpointId}
Authorization: Bearer <jwt>

Path parameters

`businessId`	`UUID`required	Business id.
`endpointId`	`UUID`required	Endpoint id.