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.
| Format | Value |
|---|---|
text | String, up to 1,000 characters |
email | Email address, up to 254 characters |
phone | Phone number in E.164 format, for example +919998880000 |
date | Date as YYYY-MM-DD |
boolean | true or false |
list | Array of option IDs (one ID for a single select attribute) |
file | Array 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())
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"
}
| Code | Status | Meaning |
|---|---|---|
INVALID_NAME | 400 | The name is empty, longer than 100 characters, or has no English letter or digit |
INVALID_VALUE | 400 | A value does not match the attribute format, or the request is malformed |
ORDER_MISMATCH | 400 | The keys sent to reorder are not exactly the custom attributes of the store |
LIMIT_REACHED | 400 | The store already has 50 custom attributes |
OPTION_LIMIT_REACHED | 400 | The list would exceed 5,000 active options |
SYSTEM_ATTRIBUTE | 403 | The operation is not allowed on a system attribute |
ATTRIBUTE_NOT_FOUND | 404 | No attribute or option with that key or ID |
NAME_EXISTS | 409 | Another attribute has that name, or another option has that label |
Rate Limits
Limits apply per API key. A request over the limit returns 429.
| Requests | Limit |
|---|---|
| Reading attributes, options and customer values | 60 per minute |
| Creating, updating, duplicating and deleting an attribute; renaming, archiving and restoring an option; updating customer values | 30 per minute |
| Reordering attributes, deleting attributes in bulk and adding options | 10 per minute |
See the API Reference for the full list of endpoints, including updating, duplicating, reordering and deleting attributes and managing list options.