Customers

7 operations. Every schema and example on this page is generated from the platform contract.

PATCH/api/v1/customers/{customerId}

Edit one of your customers: name, mobile, email, and your own note.

The Business app customer page save. Partial update of a customer the authenticated store actually has a membership row for (anyone else reads as 404, a shop may only edit its own customers). Omit a field to leave it untouched; send an empty string to clear it. The mobile is normalised to E.164 and refused if it is not a UK mobile; the email is trimmed and lower-cased; a mobile or email already sitting on another customer is refused rather than silently moved. A customer who asked to be deleted can no longer be edited. Idempotent: every field is a plain set, so replaying the same body converges on the same record.

auth merchant:writeop updateCustomeridempotent retry rate limited errors

Parameters

customerIdstringpathrequired

Request body

store_idstring · uuidoptional

The shop whose customer this is. May travel in the body or as ?store_id=; the authenticated store wins either way.

namestringoptional

Display name. Trimmed; up to 80 characters. Empty string clears it.

phonestringoptional

UK mobile in any spelling (07…, +44…, spaces). Stored as E.164. Empty string clears it.

emailstringoptional

Email address. Trimmed and lower-cased. Empty string clears it.

merchant_notestringoptional

The shop's own private note about this person, up to 2000 characters. Empty string clears it. Never travels to another shop.

Response, 200

customerobjectrequired

6 child fields

idstringrequired

customers.id.

namestring, nullablerequired

Display name, or null when nobody has added one.

phonestring, nullablerequired

E.164 mobile, or null.

emailstring, nullablerequired

Lower-cased email, or null.

merchant_notestring, nullablerequired

This shop's private note, or null.

merchant_note_updated_atstring, nullablerequired

When the note was last written (ISO), or null.

changed_fieldsarray of stringrequired

Names of the fields this call changed: name, phone, email, merchant_note. Never their values.

curl -X PATCH "https://www.membber.com/api/v1/customers/a1c10999-0000-4000-8000-d0c5000000a1" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066",
    "name": "Example name",
    "phone": "+44 7700 900123",
    "email": "alex@example.com",
    "merchant_note": "Added at the front desk"
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.PATCH("/api/v1/customers/{customerId}", {
  params: { path: { customerId: "a1c10999-0000-4000-8000-d0c5000000a1" } },
  body: {
    store_id: "6659c139-0000-4000-8000-d0c500000066",
    name: "Example name",
    phone: "+44 7700 900123",
    email: "alex@example.com",
    merchant_note: "Added at the front desk"
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.updateCustomer(
    path: .init(customerId: "a1c10999-0000-4000-8000-d0c5000000a1"),
    body: .json(.init(
        storeId: "6659c139-0000-4000-8000-d0c500000066",
        name: "Example name",
        phone: "+44 7700 900123",
        email: "alex@example.com",
        merchantNote: "Added at the front desk"
    ))
).ok.body.json

print(response)

Response, 200

{
  "customer": {
    "id": "00000d1b-0000-4000-8000-d0c500000000",
    "name": "Example name",
    "phone": "+44 7700 900123",
    "email": "alex@example.com",
    "merchant_note": "Added at the front desk",
    "merchant_note_updated_at": "Added at the front desk"
  },
  "changed_fields": [
    "<changed_field>"
  ]
}

GET/api/v1/customers/{customerId}/attendance

Get a member's class-booking / attendance history at one store.

The Business-app member drill-down's attendance view: every class booking for one member at one store (attended, no-show, cancelled, confirmed, waitlisted), newest-first, paginated by limit/offset, with the class + occurrence context for each row. Store-scoped and relationship-gated: a customer with no relationship to this store, or a deleted / anonymized member, returns 404. Requires the classes entitlement.

auth merchant:readop getMemberAttendancerate limited errors

Parameters

customerIdstringpathrequired

store_idstring · uuidqueryrequired

Store whose bookings for this member to read (also authorises the merchant).

limitintegerqueryoptional

Page size (default 25, max 50).

offsetintegerqueryoptional

Rows to skip from the newest-first list (default 0).

Response, 200

bookingsarray of objectrequired

14 child fields

idstringrequired

Booking id.

statusstringrequired

Booking status: attended / no_show / cancelled / confirmed / waitlisted / promotion_pending / promotion_expired.

booking_datestringrequired

Date the booked class is for (YYYY-MM-DD).

booking_sourcestring, nullablerequired

How the booking was made (app / staff / drop-in), if recorded.

class_namestring, nullablerequired

Class name.

class_categorystring, nullablerequired

Class category.

instructor_namestring, nullablerequired

Instructor for the occurrence (falls back to the class default).

scheduled_datestring, nullablerequired

Occurrence scheduled date, when the booking is tied to an occurrence.

start_timestring, nullablerequired

Occurrence start time (HH:MM:SS).

end_timestring, nullablerequired

Occurrence end time (HH:MM:SS).

attended_atstring, nullablerequired

When the member checked in, if they attended.

no_show_marked_atstring, nullablerequired

When the booking was marked a no-show, if it was.

cancelled_atstring, nullablerequired

When the booking was cancelled, if it was.

created_atstringrequired

When the booking row was created.

paginationobjectrequired

4 child fields

limitnumberrequired

offsetnumberrequired

has_morebooleanrequired

next_offsetnumber, nullablerequired

curl -G "https://www.membber.com/api/v1/customers/a1c10999-0000-4000-8000-d0c5000000a1/attendance" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/customers/{customerId}/attendance", {
  params: { path: { customerId: "a1c10999-0000-4000-8000-d0c5000000a1" }, query: { store_id: "6659c139-0000-4000-8000-d0c500000066" } },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.getMemberAttendance(
    path: .init(customerId: "a1c10999-0000-4000-8000-d0c5000000a1"),
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066")
).ok.body.json

print(response)

Response, 200

{
  "bookings": [
    {
      "id": "00000d1b-0000-4000-8000-d0c500000000",
      "status": "<status>",
      "booking_date": "<booking_date>",
      "booking_source": "<booking_source>",
      "class_name": "<class_name>",
      "class_category": "<class_category>",
      "instructor_name": "<instructor_name>",
      "scheduled_date": "<scheduled_date>",
      "start_time": "<start_time>",
      "end_time": "<end_time>",
      "attended_at": "<attended_at>",
      "no_show_marked_at": "<no_show_marked_at>",
      "cancelled_at": "<cancelled_at>",
      "created_at": "<created_at>"
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "has_more": true,
    "next_offset": 1
  }
}

PATCH/api/v1/customers/{customerId}/block

Block, mute, note or archive one of this shop's customers.

A shop stops one person acting here (joining, ordering, messaging), mutes single channels, keeps a private note, or archives someone with history so they leave the lists and counts while every order and stamp is kept. All reversible, all scoped to this shop alone, and none of them a deletion. A customer this shop has no relationship with reads as 404.

auth merchant:writeop blockCustomeridempotent retry rate limited errors

Parameters

customerIdstringpathrequired

Request body

store_idstring · uuidrequired

The shop making the decision (also authorises the merchant).

blockedbooleanoptional

true blocks them here, false lifts it (which also clears the note and the one-notice stamp).

blocked_channelsarray of stringoptional

Replaces the muted list wholesale. Any of: email, sms, drops_chat, app_message.

block_reasonstring, nullableoptional

The merchant's private note, at most 500 characters. Never sent to the customer.

archivedbooleanoptional

true hides them from this shop's lists and counts, false brings them back.

Response, 200

customerobjectrequired

7 child fields

customer_idstringrequired

blockedbooleanrequired

Wholly blocked at this shop: no joining, no ordering, no messages.

blocked_atstring, nullablerequired

When this shop blocked them. Null when they are not blocked.

blocked_channelsarray of enumrequired

Channels muted while NOT wholly blocked. A block stops all four regardless.

emailsmsdrops_chatapp_message

block_reasonstring, nullablerequired

The merchant's private note. Shown back to the merchant only; never sent to the customer.

archivedbooleanrequired

Hidden from this shop's lists and counts. Stops nothing.

archived_atstring, nullablerequired

curl -X PATCH "https://www.membber.com/api/v1/customers/a1c10999-0000-4000-8000-d0c5000000a1/block" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066"
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.PATCH("/api/v1/customers/{customerId}/block", {
  params: { path: { customerId: "a1c10999-0000-4000-8000-d0c5000000a1" } },
  body: {
    store_id: "6659c139-0000-4000-8000-d0c500000066"
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.blockCustomer(
    path: .init(customerId: "a1c10999-0000-4000-8000-d0c5000000a1"),
    body: .json(.init(
        storeId: "6659c139-0000-4000-8000-d0c500000066"
    ))
).ok.body.json

print(response)

Response, 200

{
  "customer": {
    "customer_id": "96607d1c-0000-4000-8000-d0c500000096",
    "blocked": true,
    "blocked_at": "<blocked_at>",
    "blocked_channels": [
      "email"
    ],
    "block_reason": "Added at the front desk",
    "archived": true,
    "archived_at": "<archived_at>"
  }
}

GET/api/v1/customers/{customerId}/journey

Get a customer's journey timeline at one store.

The Business-app customer-detail timeline: a single chronological (newest-first) feed interleaving every recorded touchpoint for one member at one store, paginated by a before cursor. Also returns whether the customer has any store-scoped agreements on record. Store-scoped and relationship-gated: a customer with no relationship at this store returns 404.

auth merchant:readop getCustomerJourneyrate limited errors

Parameters

customerIdstringpathrequired

store_idstring · uuidqueryrequired

Store whose journey with the customer to read (also authorises the merchant).

limitintegerqueryoptional

Page size (default 25, max 50).

beforestringqueryoptional

ISO 8601 cursor, return events strictly older than this timestamp.

Response, 200

eventsarray of objectrequired

22 child fields

idstringrequired

typeenumrequired

joinedstampvoucher_earnedvoucher_redeemedordermessageemailjourneymomentclass_bookingmembership

channelenumrequired

in_storein_appemailjourneymomentgym

timestampstringrequired

titlestringrequired

subtitlestringrequired

statusstring, nullablerequired

detailstring, nullablerequired

campaignNamestring, nullableoptional

openedboolean, nullableoptional

clickedboolean, nullableoptional

returningVisitAtstring, nullableoptional

returnDaysnumber, nullableoptional

amountPencenumber, nullableoptional

refundedPencenumber, nullableoptional

promoDiscountPencenumber, nullableoptional

appliedPromoCodestring, nullableoptional

currencystring, nullableoptional

autoSentboolean, nullableoptional

resultKindstring, nullableoptional

resultAtstring, nullableoptional

resultValuePencenumber, nullableoptional

paginationobjectrequired

4 child fields

limitnumberrequired

beforestring, nullablerequired

nextCursorstring, nullablerequired

hasMorebooleanrequired

has_store_agreementsbooleanrequired

curl -G "https://www.membber.com/api/v1/customers/a1c10999-0000-4000-8000-d0c5000000a1/journey" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/customers/{customerId}/journey", {
  params: { path: { customerId: "a1c10999-0000-4000-8000-d0c5000000a1" }, query: { store_id: "6659c139-0000-4000-8000-d0c500000066" } },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.getCustomerJourney(
    path: .init(customerId: "a1c10999-0000-4000-8000-d0c5000000a1"),
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066")
).ok.body.json

print(response)

Response, 200

{
  "events": [
    {
      "id": "00000d1b-0000-4000-8000-d0c500000000",
      "type": "joined",
      "channel": "in_store",
      "timestamp": "<timestamp>",
      "title": "Morning class",
      "subtitle": "<subtitle>",
      "status": "<status>",
      "detail": "<detail>",
      "campaignName": "<campaignName>",
      "opened": true,
      "clicked": true,
      "returningVisitAt": "<returningVisitAt>",
      "returnDays": 1,
      "amountPence": 1500,
      "refundedPence": 1,
      "promoDiscountPence": 1,
      "appliedPromoCode": "EXAMPLE10",
      "currency": "GBP",
      "autoSent": true,
      "resultKind": "<resultKind>",
      "resultAt": "<resultAt>",
      "resultValuePence": 1
    }
  ],
  "pagination": {
    "limit": 25,
    "before": "<before>",
    "nextCursor": "<nextCursor>",
    "hasMore": true
  },
  "has_store_agreements": true
}

PATCH/api/v1/customers/block

Block, mute or archive several of this shop's customers at once.

The same change applied to a group in ONE statement: either every named person is changed or nobody is. If any id is not already this shop's customer the call changes nothing and says how many were unknown.

auth merchant:writeop blockCustomersidempotent retry rate limited errors

Request body

store_idstring · uuidrequired

The shop making the decision (also authorises the merchant).

customer_idsarray of string · uuidrequired

The people this change applies to. All of them must already be this shop's customers.

blockedbooleanoptional

true blocks them here, false lifts it (which also clears the note and the one-notice stamp).

blocked_channelsarray of stringoptional

Replaces the muted list wholesale. Any of: email, sms, drops_chat, app_message.

block_reasonstring, nullableoptional

The merchant's private note, at most 500 characters. Never sent to the customer.

archivedbooleanoptional

true hides them from this shop's lists and counts, false brings them back.

Response, 200

updatednumberrequired

How many customers the change was applied to.

customersarray of objectrequired

7 child fields

customer_idstringrequired

blockedbooleanrequired

Wholly blocked at this shop: no joining, no ordering, no messages.

blocked_atstring, nullablerequired

When this shop blocked them. Null when they are not blocked.

blocked_channelsarray of enumrequired

Channels muted while NOT wholly blocked. A block stops all four regardless.

emailsmsdrops_chatapp_message

block_reasonstring, nullablerequired

The merchant's private note. Shown back to the merchant only; never sent to the customer.

archivedbooleanrequired

Hidden from this shop's lists and counts. Stops nothing.

archived_atstring, nullablerequired

curl -X PATCH "https://www.membber.com/api/v1/customers/block" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  -H "Idempotency-Key: 1f0e2d3c-4b5a-4678-9abc-def012345678" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "6659c139-0000-4000-8000-d0c500000066",
    "customer_ids": [
      "96607d1c-0000-4000-8000-d0c500000096"
    ]
  }'

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.PATCH("/api/v1/customers/block", {
  body: {
    store_id: "6659c139-0000-4000-8000-d0c500000066",
    customer_ids: [
      "96607d1c-0000-4000-8000-d0c500000096"
    ]
  },
  headers: { "Idempotency-Key": crypto.randomUUID() },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.blockCustomers(
    body: .json(.init(
        storeId: "6659c139-0000-4000-8000-d0c500000066",
        customerIds: ["96607d1c-0000-4000-8000-d0c500000096"]
    ))
).ok.body.json

print(response)

Response, 200

{
  "updated": 1,
  "customers": [
    {
      "customer_id": "96607d1c-0000-4000-8000-d0c500000096",
      "blocked": true,
      "blocked_at": "<blocked_at>",
      "blocked_channels": [
        "email"
      ],
      "block_reason": "Added at the front desk",
      "archived": true,
      "archived_at": "<archived_at>"
    }
  ]
}

GET/api/v1/customers/list

List a store's customer roster (filterable, sortable, paginated).

Merchant browses their full customer roster, everyone who has interacted with the store, enriched with lifecycle stage, visits, stamp count, order count + net spend, and marketing consent. Supports stage/facet/text filters, sort by recent/spend/visits/name, and pagination with a true filtered total_count.

auth merchant:readop listCustomersrate limited errors

Parameters

store_idstring · uuidqueryrequired

Store whose roster to list (also authorises the merchant).

sortenumqueryoptional

Sort order (default recent).

recentspendvisitsname

stageenumqueryoptional

Lifecycle-stage filter.

newactivestalelapsedreturning

facetstringqueryoptional

Comma-separated AND filters: has_orders, has_stamps, marketing_opted_in.

qstringqueryoptional

Filter the roster by name/email/phone.

limitintegerqueryoptional

Page size (default 30, max 100).

offsetintegerqueryoptional

Page offset.

Response, 200

customersarray of objectrequired

11 child fields

idstringrequired

namestring, nullablerequired

phonestring, nullablerequired

emailstring, nullablerequired

last_visit_atstring, nullablerequired

lifecycle_stagestring, nullablerequired

total_visitsnumberrequired

stamp_countnumberrequired

order_countnumberrequired

total_spent_pencenumberrequired

marketing_opted_inbooleanrequired

paginationobjectrequired

4 child fields

limitnumberrequired

offsetnumberrequired

has_morebooleanrequired

total_countnumberrequired

curl -G "https://www.membber.com/api/v1/customers/list" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/customers/list", {
  params: { query: { store_id: "6659c139-0000-4000-8000-d0c500000066" } },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.listCustomers(
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066")
).ok.body.json

print(response)

Response, 200

{
  "customers": [
    {
      "id": "00000d1b-0000-4000-8000-d0c500000000",
      "name": "Example name",
      "phone": "+44 7700 900123",
      "email": "alex@example.com",
      "last_visit_at": "<last_visit_at>",
      "lifecycle_stage": "<lifecycle_stage>",
      "total_visits": 1,
      "stamp_count": 1,
      "order_count": 1,
      "total_spent_pence": 1500,
      "marketing_opted_in": true
    }
  ],
  "pagination": {
    "limit": 25,
    "offset": 0,
    "has_more": true,
    "total_count": 1
  }
}

GET/api/v1/customers/search

Search a store's customers by name, phone, or email.

Merchant searches the customers who have interacted with their store (class bookings, stamps, or paid orders). A 2+ character term filters by name/phone/email; a short/empty term returns the most-recent customers as a list.

auth merchant:readop searchCustomersrate limited errors

Parameters

store_idstring · uuidqueryrequired

Store whose customers to search (also authorises the merchant).

qstringqueryoptional

Search term; 2+ chars filters by name/phone/email, else returns the most-recent 20.

Response, 200

customersarray of objectrequired

5 child fields

idstringrequired

namestring, nullablerequired

phonestring, nullablerequired

emailstring, nullablerequired

last_seenstring, nullablerequired

curl -G "https://www.membber.com/api/v1/customers/search" \
  -H "Authorization: Bearer $MEMBBER_TOKEN" \
  --data-urlencode "store_id=6659c139-0000-4000-8000-d0c500000066"

import { createMembberClient } from "@membber/sdk-ts";

const membber = createMembberClient({
  getAccessToken: () => process.env.MEMBBER_TOKEN,
});

const { data, error } = await membber.raw.GET("/api/v1/customers/search", {
  params: { query: { store_id: "6659c139-0000-4000-8000-d0c500000066" } },
});

if (error) {
  // Typed error envelope: { error: { code, message, requestId } }
  throw new Error(`${error.error.code}: ${error.error.message}`);
}
console.log(data);

import MembberSwift

let client = MembberClient(
    serverURL: MembberClient.productionServerURL,
    tokenProvider: { session.accessToken }
)

let response = try await client.api.searchCustomers(
    query: .init(storeId: "6659c139-0000-4000-8000-d0c500000066")
).ok.body.json

print(response)

Response, 200

{
  "customers": [
    {
      "id": "00000d1b-0000-4000-8000-d0c500000000",
      "name": "Example name",
      "phone": "+44 7700 900123",
      "email": "alex@example.com",
      "last_seen": "<last_seen>"
    }
  ]
}