Saltar al contenido

Customers

Customers

Persistent guest profiles. Tablezio links email and phone uniquely per restaurant, tracks visit history automatically, and exposes block/unblock for no-show enforcement.

List customers

GET /v1/customers Scope: customers:read

Search and filter your customer base.

Query parameters

limitintegerOptional

Page size.

starting_afterstringOptional

Cursor.

ending_beforestringOptional

Cursor (backwards).

emailstringOptional

Exact email match.

phonestringOptional

Exact phone match.

is_blockedbooleanOptional

true returns only blocked customers.

searchstringOptional

Case-insensitive search over name, email and phone.

Request

curl 'https://api.tablezio.com/v1/customers?search=lucia' -H 'X-API-Key: tbz_…'

Response

application/json
{ "object": "list", "data": [ /* customer */ ], "has_more": false, "next_cursor": null, "previous_cursor": null, "url": "/v1/customers" }

Retrieve a customer

GET /v1/customers/{id} Scope: customers:read

Fetch a single customer.

Path parameters

idstringRequired

Customer ID (cus_…).

Request

curl https://api.tablezio.com/v1/customers/cus_… -H 'X-API-Key: tbz_…'

Response

application/json
{
  "id": "cus_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "customer",
  "created": 1716730000,
  "updated": 1716730000,
  "first_name": "Lucia",
  "last_name": "Martín",
  "email": "[email protected]",
  "phone": "+34 600 000 000",
  "notes": null,
  "tags": ["vip"],
  "total_visits": 14,
  "total_spent": 124000,
  "last_visit_at": 1716557000,
  "loyalty_points": 320,
  "dietary_restrictions": ["gluten_free"],
  "birthday": "1991-04-22",
  "anniversary_date": null,
  "source": "walk_in",
  "is_active": true,
  "is_blocked": false,
  "block_reason": null,
  "blocked_at": null,
  "no_show_count": 0,
  "total_reservations": 11
}

Create a customer

POST /v1/customers Scope: customers:write

Adds a customer profile. Use Idempotency-Key when capturing via a public form.

Body parameters

first_namestringRequired

Given name.

last_namestringOptional

Family name.

emailstringOptional

Email. Must be unique per restaurant.

phonestringOptional

Phone. Must be unique per restaurant.

birthdaystring (YYYY-MM-DD)Optional

For birthday campaigns.

anniversary_datestring (YYYY-MM-DD)Optional

For anniversary campaigns.

dietary_restrictionsstring[]Optional

Tags surfaced to front-of-house.

tagsstring[]Optional

Free-form segmentation tags.

notesstringOptional

Internal staff notes.

sourcestringOptional

Origin channel (walk_in, online, import…).

Request

curl -X POST https://api.tablezio.com/v1/customers \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{ "first_name": "Lucia", "email": "[email protected]" }'

Response

application/json
{
  "id": "cus_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "customer",
  "created": 1716730000,
  "updated": 1716730000,
  "first_name": "Lucia",
  "last_name": "Martín",
  "email": "[email protected]",
  "phone": "+34 600 000 000",
  "notes": null,
  "tags": ["vip"],
  "total_visits": 14,
  "total_spent": 124000,
  "last_visit_at": 1716557000,
  "loyalty_points": 320,
  "dietary_restrictions": ["gluten_free"],
  "birthday": "1991-04-22",
  "anniversary_date": null,
  "source": "walk_in",
  "is_active": true,
  "is_blocked": false,
  "block_reason": null,
  "blocked_at": null,
  "no_show_count": 0,
  "total_reservations": 11
}

Update a customer

PATCH /v1/customers/{id} Scope: customers:write

Partial update of any profile field.

Path parameters

idstringRequired

Customer ID.

Body parameters

*anyOptional

Any field from Create.

Request

curl -X PATCH https://api.tablezio.com/v1/customers/cus_… \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{ "tags": ["vip", "regular"] }'

Response

application/json
{
  "id": "cus_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "customer",
  "created": 1716730000,
  "updated": 1716730000,
  "first_name": "Lucia",
  "last_name": "Martín",
  "email": "[email protected]",
  "phone": "+34 600 000 000",
  "notes": null,
  "tags": ["vip"],
  "total_visits": 14,
  "total_spent": 124000,
  "last_visit_at": 1716557000,
  "loyalty_points": 320,
  "dietary_restrictions": ["gluten_free"],
  "birthday": "1991-04-22",
  "anniversary_date": null,
  "source": "walk_in",
  "is_active": true,
  "is_blocked": false,
  "block_reason": null,
  "blocked_at": null,
  "no_show_count": 0,
  "total_reservations": 11
}

Block a customer

POST /v1/customers/{id}/block Scope: customers:write

Prevents new reservations from this customer until unblocked. Useful after repeated no-shows.

Path parameters

idstringRequired

Customer ID.

Body parameters

reasonstringOptional

Free-form reason logged on the customer record.

Request

curl -X POST https://api.tablezio.com/v1/customers/cus_…/block -H 'X-API-Key: tbz_…'

Response

application/json
{
  "id": "cus_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "customer",
  "created": 1716730000,
  "updated": 1716730000,
  "first_name": "Lucia",
  "last_name": "Martín",
  "email": "[email protected]",
  "phone": "+34 600 000 000",
  "notes": null,
  "tags": ["vip"],
  "total_visits": 14,
  "total_spent": 124000,
  "last_visit_at": 1716557000,
  "loyalty_points": 320,
  "dietary_restrictions": ["gluten_free"],
  "birthday": "1991-04-22",
  "anniversary_date": null,
  "source": "walk_in",
  "is_active": true,
  "is_blocked": false,
  "block_reason": null,
  "blocked_at": null,
  "no_show_count": 0,
  "total_reservations": 11
}

Unblock a customer

POST /v1/customers/{id}/unblock Scope: customers:write

Clears the block flag.

Path parameters

idstringRequired

Customer ID.

Request

curl -X POST https://api.tablezio.com/v1/customers/cus_…/unblock -H 'X-API-Key: tbz_…'

Response

application/json
{
  "id": "cus_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "customer",
  "created": 1716730000,
  "updated": 1716730000,
  "first_name": "Lucia",
  "last_name": "Martín",
  "email": "[email protected]",
  "phone": "+34 600 000 000",
  "notes": null,
  "tags": ["vip"],
  "total_visits": 14,
  "total_spent": 124000,
  "last_visit_at": 1716557000,
  "loyalty_points": 320,
  "dietary_restrictions": ["gluten_free"],
  "birthday": "1991-04-22",
  "anniversary_date": null,
  "source": "walk_in",
  "is_active": true,
  "is_blocked": false,
  "block_reason": null,
  "blocked_at": null,
  "no_show_count": 0,
  "total_reservations": 11
}

Adjust loyalty points

POST /v1/customers/{id}/loyalty_points/adjust Scope: loyalty:write

Adds (positive) or removes (negative) points from the customer balance.

Path parameters

idstringRequired

Customer ID.

Body parameters

pointsintegerRequired

Delta. Can be negative.

reasonstringOptional

Optional reason; appears on the customer history.

Request

curl -X POST https://api.tablezio.com/v1/customers/cus_…/loyalty_points/adjust \
  -H 'X-API-Key: tbz_…' -H 'Content-Type: application/json' \
  -d '{ "points": 50, "reason": "Friend referral" }'

Response

application/json
{
  "id": "cus_8b2c3d4e5f6a7b8c9d0e1f20",
  "object": "customer",
  "created": 1716730000,
  "updated": 1716730000,
  "first_name": "Lucia",
  "last_name": "Martín",
  "email": "[email protected]",
  "phone": "+34 600 000 000",
  "notes": null,
  "tags": ["vip"],
  "total_visits": 14,
  "total_spent": 124000,
  "last_visit_at": 1716557000,
  "loyalty_points": 320,
  "dietary_restrictions": ["gluten_free"],
  "birthday": "1991-04-22",
  "anniversary_date": null,
  "source": "walk_in",
  "is_active": true,
  "is_blocked": false,
  "block_reason": null,
  "blocked_at": null,
  "no_show_count": 0,
  "total_reservations": 11
}