Skip to main content

Customer Attributes API

Use the Customer Attributes API to define the fields your store keeps about a customer (for example a billing email, a plan or a renewal date) and to read and set their values for each customer.

Attribute endpoints are under /v2/store/attributes, customer values are under /v2/customer/{id}/attributes, and all of them require the apikey header for authentication.

Every store has six system attributes (name, whatsapp_number, facebook_id, instagram_id, whatsapp_bsuid, account_email). They are read only. You can add up to 50 custom attributes of your own.

Attribute formats​

Each attribute has a format, which decides the value it accepts.

FormatValue
textString, up to 1,000 characters
emailEmail address, up to 254 characters
phonePhone number in E.164 format, for example +919998880000
dateDate as YYYY-MM-DD
booleantrue or false
listArray of option IDs (one ID for a single select attribute)
fileArray of up to 5 files, each with url, name, type and size

Create an Attribute​

Use POST /store/attributes to create a custom attribute. name and format are required. The response returns the attribute with its key, which is generated from the name and never changes, even if you rename the attribute later. Use the key in every other call.

curl --request POST \
--url https://chat.zoko.io/v2/store/attributes \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'apikey: YOUR_API_KEY' \
--data '{
"name": "Billing Email",
"format": "email",
"description": "Email for invoices"
}'
const options = {
method: 'POST',
url: 'https://chat.zoko.io/v2/store/attributes',
headers: {
accept: 'application/json',
'content-type': 'application/json',
apikey: 'YOUR_API_KEY'
},
body: {
name: 'Billing Email',
format: 'email',
description: 'Email for invoices'
},
json: true
};

request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/store/attributes"

payload = {
"name": "Billing Email",
"format": "email",
"description": "Email for invoices"
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"apikey": "YOUR_API_KEY"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Response (201):

{
"key": "billing_email",
"name": "Billing Email",
"description": "Email for invoices",
"format": "email",
"is_system": false,
"option_count": 0,
"multi_select": false,
"visibility": null,
"position": 1,
"created_at": "2026-11-19T06:30:00.000Z",
"updated_at": "2026-11-19T06:30:00.000Z",
"visible_to_me": true
}

For a list attribute, pass the first options in list_options, and set multi_select to true if a customer can hold more than one option.

curl --request POST \
--url https://chat.zoko.io/v2/store/attributes \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'apikey: YOUR_API_KEY' \
--data '{
"name": "Plan",
"format": "list",
"list_options": [
"Free",
"Pro",
"Enterprise"
]
}'

List Attributes​

Use GET /store/attributes to retrieve the attributes of your store. System attributes come first, followed by your custom attributes in their display order.

curl --request GET \
--url https://chat.zoko.io/v2/store/attributes \
--header 'accept: application/json' \
--header 'apikey: YOUR_API_KEY'
import requests

url = "https://chat.zoko.io/v2/store/attributes"
headers = {
"accept": "application/json",
"apikey": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
"attributes": [
{
"key": "name",
"name": "Name",
"description": "A person's full name",
"format": "text",
"is_system": true,
"option_count": 0,
"multi_select": false,
"visibility": null,
"position": 1,
"created_at": "2026-11-19T06:30:00.000Z",
"updated_at": "2026-11-19T06:30:00.000Z",
"visible_to_me": true
},
{
"key": "billing_email",
"name": "Billing Email",
"description": "Email for invoices",
"format": "email",
"is_system": false,
"option_count": 0,
"multi_select": false,
"visibility": null,
"position": 1,
"created_at": "2026-11-19T06:30:00.000Z",
"updated_at": "2026-11-19T06:30:00.000Z",
"visible_to_me": true
},
{
"key": "plan",
"name": "Plan",
"description": null,
"format": "list",
"is_system": false,
"option_count": 3,
"multi_select": false,
"visibility": null,
"position": 2,
"created_at": "2026-11-19T06:30:00.000Z",
"updated_at": "2026-11-19T06:30:00.000Z",
"visible_to_me": true
}
]
}

List the Options of a List Attribute​

A list value is set with option IDs, not labels. Use GET /store/attributes/{key}/options to get the options of a list attribute. Results are paged: pass next_cursor from the response as cursor to get the next page. Use q to search by label.

curl --request GET \
--url https://chat.zoko.io/v2/store/attributes/plan/options \
--header 'accept: application/json' \
--header 'apikey: YOUR_API_KEY'
import requests

url = "https://chat.zoko.io/v2/store/attributes/plan/options"
headers = {
"accept": "application/json",
"apikey": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
"options": [
{
"id": "9d2f4a6b-1c3e-4f50-8a7b-6c5d4e3f2a1b",
"label": "Enterprise",
"archived": false
},
{
"id": "0c1d2e3f-4a5b-4c6d-9e7f-8a9b0c1d2e3f",
"label": "Free",
"archived": false
},
{
"id": "5b0f2c1e-7c3a-4e0e-9a55-2f6d1c3b8a10",
"label": "Pro",
"archived": false
}
],
"next_cursor": null
}

Get Customer Attributes​

Use GET /customer/{id}/attributes to retrieve the attribute values of a customer. attributes has one entry per attribute, keyed by attribute key; an attribute with no value is null. definitions describes the attributes returned.

Pass include_system_attributes=false to leave out the six system attributes.

curl --request GET \
--url https://chat.zoko.io/v2/customer/f1e2d3c4-b5a6-7890-abcd-ef1234567890/attributes?include_system_attributes=false \
--header 'accept: application/json' \
--header 'apikey: YOUR_API_KEY'
import requests

url = "https://chat.zoko.io/v2/customer/f1e2d3c4-b5a6-7890-abcd-ef1234567890/attributes?include_system_attributes=false"
headers = {
"accept": "application/json",
"apikey": "YOUR_API_KEY"
}

response = requests.get(url, headers=headers)
print(response.json())

Response:

{
"attributes": {
"billing_email": "accounts@example.com",
"plan": [
{
"id": "5b0f2c1e-7c3a-4e0e-9a55-2f6d1c3b8a10",
"label": "Pro",
"archived": false
}
],
"renewal_date": "2026-12-01",
"office_address": null
},
"definitions": [
{
"key": "billing_email",
"name": "Billing Email",
"description": "Email for invoices",
"format": "email",
"is_system": false,
"multi_select": false,
"visibility": null,
"position": 1,
"created_at": "2026-11-19T06:30:00.000Z",
"updated_at": "2026-11-19T06:30:00.000Z",
"visible_to_me": true
}
]
}

A list value is always returned as an array of options, each with id, label and archived.

Update Customer Attributes​

Use PUT /customer/{id}/attributes to set or clear values. The body is an object keyed by attribute key. Only the keys you send are changed; send null to clear a value. The response returns the customer's values after the update, in the same shape as Get Customer Attributes.

curl --request PUT \
--url https://chat.zoko.io/v2/customer/f1e2d3c4-b5a6-7890-abcd-ef1234567890/attributes \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'apikey: YOUR_API_KEY' \
--data '{
"billing_email": "accounts@example.com",
"plan": [
"5b0f2c1e-7c3a-4e0e-9a55-2f6d1c3b8a10"
],
"renewal_date": "2026-12-01",
"office_address": null
}'
const options = {
method: 'PUT',
url: 'https://chat.zoko.io/v2/customer/f1e2d3c4-b5a6-7890-abcd-ef1234567890/attributes',
headers: {
accept: 'application/json',
'content-type': 'application/json',
apikey: 'YOUR_API_KEY'
},
body: {
billing_email: 'accounts@example.com',
plan: ['5b0f2c1e-7c3a-4e0e-9a55-2f6d1c3b8a10'],
renewal_date: '2026-12-01',
office_address: null
},
json: true
};

request(options, function (error, response, body) {
if (error) throw new Error(error);
console.log(body);
});
import requests

url = "https://chat.zoko.io/v2/customer/f1e2d3c4-b5a6-7890-abcd-ef1234567890/attributes"

payload = {
"billing_email": "accounts@example.com",
"plan": ["5b0f2c1e-7c3a-4e0e-9a55-2f6d1c3b8a10"],
"renewal_date": "2026-12-01",
"office_address": None
}
headers = {
"accept": "application/json",
"content-type": "application/json",
"apikey": "YOUR_API_KEY"
}

response = requests.put(url, json=payload, headers=headers)
print(response.json())
note

A file value must point at a file uploaded to the Zoko CDN. Allowed file types are pdf, doc, docx, xlsx, csv, png, jpg, jpeg, gif, webp, mp4 and aac, up to 10 MB each.

Errors​

Attribute endpoints return an error code along with the HTTP status. Use the code to tell errors apart.

{
"status": 409,
"type": "client_error",
"message": "Title already exists.",
"code": "NAME_EXISTS"
}
CodeStatusMeaning
INVALID_NAME400The name is empty, longer than 100 characters, or has no English letter or digit
INVALID_VALUE400A value does not match the attribute format, or the request is malformed
ORDER_MISMATCH400The keys sent to reorder are not exactly the custom attributes of the store
LIMIT_REACHED400The store already has 50 custom attributes
OPTION_LIMIT_REACHED400The list would exceed 5,000 active options
SYSTEM_ATTRIBUTE403The operation is not allowed on a system attribute
ATTRIBUTE_NOT_FOUND404No attribute or option with that key or ID
NAME_EXISTS409Another attribute has that name, or another option has that label

Rate Limits​

Limits apply per API key. A request over the limit returns 429.

RequestsLimit
Reading attributes, options and customer values60 per minute
Creating, updating, duplicating and deleting an attribute; renaming, archiving and restoring an option; updating customer values30 per minute
Reordering attributes, deleting attributes in bulk and adding options10 per minute

See the API Reference for the full list of endpoints, including updating, duplicating, reordering and deleting attributes and managing list options.