Customer passes

A customer pass is one pass a customer bought, with its code and the visits left.

List customer passes

GET /v1/customer-passes

Scope store:read. Query: customer_id, code, status (pending, active, cancelled, and for memberships payment_due, ended), page, per_page.

{
  "data": [
    {
      "id": 31,
      "pass_id": 4,
      "customer_id": 208,
      "holder_name": "Jane Doe",
      "code": "PASS-7QKM-B4RT",
      "name": "Season pass",
      "status": "active",
      "visits_total": 10,
      "visits_left": 9,
      "unlimited_visits": false,
      "valid_from": "2026-07-01",
      "valid_to": "2026-08-31",
      "price": 150.0,
      "currency": "USD",
      "billing": "once",
      "discount_percent": null,
      "paid_through": null,
      "renews_on": null,
      "cancel_at": null,
      "ended_at": null,
      "status_label": null,
      "booking_id": 1204,
      "created_at": "2026-06-14T10:02:11+00:00"
    }
  ]
}

status is pending while the order it was bought on is unpaid, active once paid, and cancelled when that order was cancelled before the pass was used.

A membership (billing: "monthly") also fills in discount_percent, paid_through, renews_on, cancel_at, ended_at and status_label, and has two more statuses. See Memberships, which also covers cancelling one and its monthly charges.

Get a customer pass

GET /v1/customer-passes/{id}

Scope store:read. Adds visits: every visit taken on the pass, with booking_id, line_type, line_id, amount and status (held, used, released).

Issue a pass

POST /v1/customer-passes

Scope store:write. For a pass sold somewhere else, or given away. It is active at once.

Field	Type	Required	Description
pass_id	integer	yes	The pass
customer_id	integer	yes	Who holds it
holder_name	string	no	Name on the pass. Defaults to the customer's name
price	number	no	What was paid. Defaults to the pass price
send_email	boolean	no	Default true: the code is emailed to the customer

Returns 201 with the customer pass. A pass whose valid_to has passed on the shop's calendar is no longer sold: the request returns 422 with the code pass_ended. A pass whose who_can_buy is off returns 422 with the code pass_not_for_sale. A staff_only pass sells here as normal.

Buying a pass with a booking

Send passes on POST /bookings. Each pass is written as pending and becomes active (and the code is emailed) once the booking is confirmed or paid. An order of passes alone is a store booking and needs no dates. A pass that is switched off or whose valid_to has passed is refused with a validation error on passes.N.

{
  "customer_id": 208,
  "status": "confirmed",
  "passes": [{ "pass_id": 4, "holder_name": "Jane Doe" }]
}