Skip to contentSkip to navigation
Hatcel
Developers
2026-10-08API status

Customers

List, retrieve, create, update and delete customers

A person the venue knows, with their tags, lists and marketing consent.

The customer object

A test key sees and writes only test rows of this object. See Test data.

idstringrequired

A customer id, cus_ and 22 characters.

object"customer"required
first_namestringrequired
last_namestringrequirednullable
nicknamestringrequirednullable
emailstringrequirednullable
phonestringrequirednullable

E.164, e.g. +61400000000.

date_of_birthstringrequirednullable

yyyy-MM-dd.

companystringrequirednullable
addressobjectrequired
address.line1stringrequirednullable
address.line2stringrequirednullable
address.suburbstringrequirednullable
address.statestringrequirednullable
address.postcodestringrequirednullable
address.countrystringrequirednullable
adultbooleanrequirednullable
marketing_consentbooleanrequired

Whether they agreed to marketing email and SMS.

membershipobjectrequired
membership.memberbooleanrequired
membership.tierstringrequirednullable
tagsarray of objectsrequired
tags[].idstringrequired

A tag id, tag_ and 22 characters.

tags[].namestringrequired
tags[].added_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

listsarray of objectsrequired
lists[].idstringrequired

A list id, lst_ and 22 characters.

lists[].namestringrequired
lists[].statusstringrequirednullable

active, or unsubscribed.

lists[].added_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

lists[].unsubscribed_atstringrequirednullable

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

livemodebooleanrequired

False for test data, true for real data.

created_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

updated_atstringrequired

A UTC instant, ISO 8601, e.g. 2026-10-08T03:00:00.000Z.

versionstringrequired

Send it quoted as If-Match to change this customer.

The customer object
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

List customers

GEThttps://api.hatcel.com/customers
Any key

Every customer the key can see, newest first, a page at a time.

Query parameters

limitinteger

How many to return, 1 to 100. Defaults to 25.

starting_afterstring

The next_cursor of the page before. Omit it for the first page.

updated_sincestring

Only rows changed at or after this instant, ISO 8601 with an offset.

emailstring

Exact email address, any case.

curl "https://api.hatcel.com/customers?limit=25" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"
200 response
{
  "object": "list",
  "data": [
    {
      "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
      "object": "customer",
      "first_name": "<string>",
      "last_name": "<string>",
      "nickname": "<string>",
      "email": "alex@example.com",
      "phone": "+61400000000",
      "date_of_birth": "2026-10-08",
      "company": "<string>",
      "address": {
        "line1": "<string>",
        "line2": "<string>",
        "suburb": "<string>",
        "state": "<string>",
        "postcode": "<string>",
        "country": "<string>"
      },
      "adult": true,
      "marketing_consent": true,
      "membership": {
        "member": true,
        "tier": "<string>"
      },
      "tags": [
        {
          "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
          "name": "<string>",
          "added_at": "2026-10-08T03:00:00.000Z"
        }
      ],
      "lists": [
        {
          "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
          "name": "<string>",
          "status": "<string>",
          "added_at": "2026-10-08T03:00:00.000Z",
          "unsubscribed_at": "2026-10-08T03:00:00.000Z"
        }
      ],
      "livemode": true,
      "created_at": "2026-10-08T03:00:00.000Z",
      "updated_at": "2026-10-08T03:00:00.000Z",
      "version": "1791428400000000"
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0wOFQwMzowMDowMC4wMDBaIiwiaSI6IjBmOGZhZDViIn0"
}

Retrieve a customer

GEThttps://api.hatcel.com/customers/{id}
Any key

One customer by its id, with its version in the ETag header. Another object's id, or one this key cannot see, is a 404.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

curl "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Create a customer

POSThttps://api.hatcel.com/customers
Read and write key

Makes a customer and answers it, with a 201. An email another customer already has is a 409: look it up first with GET /customers?email=.

Headers

Idempotency-Keystringrequired

A unique string, up to 255 characters, reused only to retry this request. See Idempotency.

Body

first_namestringrequired

Required on create. Cannot be emptied.

last_namestringnullable
nicknamestringnullable
companystringnullable
emailstringnullable

Stored lowercase. One customer per email. Once set, it cannot be changed or cleared here.

phonestringnullable

Any readable number. Stored as E.164. Once set, it cannot be changed or cleared here.

date_of_birthstringnullable

yyyy-MM-dd.

gender"male" | "female" | "other"nullable
adultboolean

The age group, used only while there is no date of birth. Send it with date_of_birth.

marketing_consentfalse

Only false is accepted: true is a 403. Customers give consent themselves, on the booking page or in their portal.

how_heard_about_usstringnullable
addressobject
address.line1stringnullable
address.line2stringnullable
address.suburbstringnullable
address.statestringnullable
address.postcodestringnullable
address.countrystringnullable
curl -X POST "https://api.hatcel.com/customers" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "Alex",
    "last_name": "Taylor",
    "email": "alex@example.com"
  }'
201 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Update a customer

PATCHhttps://api.hatcel.com/customers/{id}
Read and write key

Changes only the fields sent; null clears a field, and an unknown field is a 400. An email or phone the customer already has cannot be changed or cleared here - that is a 409, and the customer changes it in their portal. An empty one can be filled. With If-Match, a customer changed since you read it is a 412 and nothing is written.

Headers

If-Matchstring

The ETag, or the quoted version, from your last read. See Changing what you read.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

Body

first_namestring

Required on create. Cannot be emptied.

last_namestringnullable
nicknamestringnullable
companystringnullable
emailstringnullable

Stored lowercase. One customer per email. Once set, it cannot be changed or cleared here.

phonestringnullable

Any readable number. Stored as E.164. Once set, it cannot be changed or cleared here.

date_of_birthstringnullable

yyyy-MM-dd.

gender"male" | "female" | "other"nullable
adultboolean

The age group, used only while there is no date of birth. Send it with date_of_birth.

marketing_consentfalse

Only false is accepted: true is a 403. Customers give consent themselves, on the booking page or in their portal.

how_heard_about_usstringnullable
addressobject
address.line1stringnullable
address.line2stringnullable
address.suburbstringnullable
address.statestringnullable
address.postcodestringnullable
address.countrystringnullable
curl -X PATCH "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0400 000 000",
    "address": {
      "suburb": "Newtown",
      "postcode": "2042"
    }
  }'
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Delete a customer

DELETEhttps://api.hatcel.com/customers/{id}
Read and write key

Removes the customer. Their bookings and orders stay.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

curl -X DELETE "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "deleted": true
}

Tag a customer

POSThttps://api.hatcel.com/customers/{id}/tags
Read and write key

Puts a tag the workspace already has on the customer, and answers the customer. Already tagged is not an error.

Headers

Idempotency-Keystringrequired

A unique string, up to 255 characters, reused only to retry this request. See Idempotency.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

Body

tagstringrequired

The tag's id, tag_ and 22 characters.

curl -X POST "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10/tags" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tag": "tag_0TMXp8QPR6yGvKuV2GZQ10"
  }'
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Untag a customer

DELETEhttps://api.hatcel.com/customers/{id}/tags/{tagId}
Read and write key

Takes the tag off, and answers the customer. A tag that was not on them is not an error.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

tagIdstringrequired

The tag's id, tag_ and 22 characters.

curl -X DELETE "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10/tags/tag_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Add a customer to a list

POSThttps://api.hatcel.com/customers/{id}/lists
Read and write key

Puts the customer on a list the workspace already has, and answers the customer. Somebody who left is put back.

Headers

Idempotency-Keystringrequired

A unique string, up to 255 characters, reused only to retry this request. See Idempotency.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

Body

liststringrequired

The list's id, lst_ and 22 characters.

curl -X POST "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10/lists" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "list": "lst_0TMXp8QPR6yGvKuV2GZQ10"
  }'
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Remove a customer from a list

DELETEhttps://api.hatcel.com/customers/{id}/lists/{listId}
Read and write key

Takes the customer off the list, and answers the customer.

Path parameters

idstringrequired

The customer's id, cus_ and 22 characters.

listIdstringrequired

The list's id, lst_ and 22 characters.

curl -X DELETE "https://api.hatcel.com/customers/cus_0TMXp8QPR6yGvKuV2GZQ10/lists/lst_0TMXp8QPR6yGvKuV2GZQ10" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"
200 response
{
  "id": "cus_0TMXp8QPR6yGvKuV2GZQ10",
  "object": "customer",
  "first_name": "<string>",
  "last_name": "<string>",
  "nickname": "<string>",
  "email": "alex@example.com",
  "phone": "+61400000000",
  "date_of_birth": "2026-10-08",
  "company": "<string>",
  "address": {
    "line1": "<string>",
    "line2": "<string>",
    "suburb": "<string>",
    "state": "<string>",
    "postcode": "<string>",
    "country": "<string>"
  },
  "adult": true,
  "marketing_consent": true,
  "membership": {
    "member": true,
    "tier": "<string>"
  },
  "tags": [
    {
      "id": "tag_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "lists": [
    {
      "id": "lst_0TMXp8QPR6yGvKuV2GZQ10",
      "name": "<string>",
      "status": "<string>",
      "added_at": "2026-10-08T03:00:00.000Z",
      "unsubscribed_at": "2026-10-08T03:00:00.000Z"
    }
  ],
  "livemode": true,
  "created_at": "2026-10-08T03:00:00.000Z",
  "updated_at": "2026-10-08T03:00:00.000Z",
  "version": "1791428400000000"
}

Remove all test data

DELETEhttps://api.hatcel.com/test-data
Read and write keyTest keys only

Removes every customer the workspace's test keys made, and every tag and list membership they added. Live data and anything staff made are never touched. A live key is refused with a 403.

curl -X DELETE "https://api.hatcel.com/test-data" \
  -H "Authorization: Bearer $HATCEL_API_KEY" \
  -H "Hatcel-Version: 2026-10-08"
200 response
{
  "object": "test_data_removal",
  "customers": 2,
  "tags": 1,
  "list_memberships": 0
}