Customer Tags

Create, read, update, delete, and subscribe to customer labels through the Store API.

Customer Tags require customer scopes: reads use read_customers and writes use write_customers. Tags label customer profiles and can participate in customer-group rules. They are separate from Product Tags and do not filter products. The slug is optional when creating a Customer Tag and is generated from its name when omitted.

Endpoints#

Customer Tag limits

GET read_customers

Get Customer Tag limits.

Returns the field and request limits enforced by Customer Tag endpoints.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

curl 'https://api-store.tringify.com/api/2025-01/customer-tags/limits' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags/limits", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/customer-tags/limits",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"max_per_store":500,"max_per_customer":50,"name_max_length":100,"list_page_size":50,"list_max_limit":200,"page_size_options":[20,50,100],"search_max_length":200,"bulk_delete_max_count":200,"bulk_create_max_count":50,"sort_columns":["name","customer_count","created_at"]}}

List Customer Tags

GET read_customers

List Customer Tags for the store.

Returns a paginated, searchable, and sortable list. Customer counts include assignments in the token's store only.

Query parameters

Name	Type	Description
`page`	`integer`	Page number. Example: `1`
`limit`	`integer`	Page size. Example: `50`
`search`	`string`	Search by name or slug. Example: `vip`
`sort_by`	`string`	Sort by `name`, `customer_count`, or `created_at`. Allowed values `namecustomer_countcreated_at` Example: `name`
`sort_direction`	`string`	Sort direction: `asc` or `desc`. Allowed values `ascdesc` Example: `asc`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 CUSTOMER_TAG_LIST_INVALID_PAGE
Page must be positive.
400 CUSTOMER_TAG_LIST_INVALID_LIMIT
Limit is outside the Customer Tag range.
400 CUSTOMER_TAG_LIST_INVALID_SORT_BY
Sort_by is not supported.
400 CUSTOMER_TAG_LIST_INVALID_SORT_DIRECTION
Sort_direction is not supported.
400 CUSTOMER_TAG_SEARCH_TOO_LONG
Search exceeds the maximum length.

curl 'https://api-store.tringify.com/api/2025-01/customer-tags?limit=50&page=1&search=vip&sort_by=name&sort_direction=asc' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags?limit=50&page=1&search=vip&sort_by=name&sort_direction=asc", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/customer-tags?limit=50&page=1&search=vip&sort_by=name&sort_direction=asc",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"tags":[{"id":"2ef71ce9-36a5-4eeb-a465-03b51e01d191","name":"VIP","slug":"vip","customer_count":12,"created_at":"2026-08-01T09:30:00+05:30","updated_at":"2026-08-01T10:15:00+05:30"}],"total":1,"store_total":1,"page":1,"limit":50,"sort_by":"name","sort_direction":"asc"}}

Get a Customer Tag

GET read_customers

Get one Customer Tag.

Returns the Customer Tag when it belongs to the token's store.

Path parameters

Name	Type	Description
`id` required	`string`	Customer Tag UUID. Example: `2ef71ce9-36a5-4eeb-a465-03b51e01d191`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 CUSTOMER_REQUEST_INVALID
Id is not a valid UUID.
404 CUSTOMER_TAG_NOT_FOUND
Customer Tag does not exist in this store.

curl 'https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"id":"2ef71ce9-36a5-4eeb-a465-03b51e01d191","name":"VIP","slug":"vip","customer_count":12,"created_at":"2026-08-01T09:30:00+05:30","updated_at":"2026-08-01T10:15:00+05:30"}}

Create a Customer Tag

POST write_customers

Create a Customer Tag.

Creates a Customer Tag. Omit slug to generate it from the name.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name` required	`string`	Customer Tag name. Example: `VIP`
`slug`	`string`	Customer Tag slug. Omit on create to generate it from the name. Example: `vip`

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CUSTOMER_TAG_NAME_REQUIRED
Name is required.
400 CUSTOMER_TAG_NAME_TOO_LONG
Name exceeds the configured limit.
400 CUSTOMER_SLUG_INVALID
Slug is invalid.
409 CUSTOMER_TAG_NAME_DUPLICATE
A Customer Tag with this name already exists.
409 CUSTOMER_TAG_SLUG_DUPLICATE
A Customer Tag with this slug already exists.
400 CUSTOMER_TAGS_LIMIT
The store has reached its Customer Tag limit.

curl -X POST 'https://api-store.tringify.com/api/2025-01/customer-tags' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP",
  "slug": "vip"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "name": "VIP",
    "slug": "vip"
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/customer-tags",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "name": "VIP",
        "slug": "vip",
    },
)
data = res.json()

Response

201

Sample response

{"success":true,"data":{"id":"2ef71ce9-36a5-4eeb-a465-03b51e01d191","name":"VIP","slug":"vip","customer_count":12,"created_at":"2026-08-01T09:30:00+05:30","updated_at":"2026-08-01T10:15:00+05:30"}}

Bulk create Customer Tags

POST write_customers

Create multiple Customer Tags.

Creates tags from names. Existing names are skipped and row validation errors are returned without discarding valid rows.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`names` required	`array<string>`	Customer Tag names to create. Example: `["VIP", "Wholesale"]`

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CUSTOMER_TAGS_BULK_EMPTY
Names must contain at least one item.
400 CUSTOMER_TAGS_BULK_CREATE_MAX
The request exceeds the bulk-create cap.

curl -X POST 'https://api-store.tringify.com/api/2025-01/customer-tags/bulk-create' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "names": [
    "VIP",
    "Wholesale"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags/bulk-create", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "names": [
      "VIP",
      "Wholesale"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/customer-tags/bulk-create",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "names": ["VIP", "Wholesale"],
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"created":[{"id":"2ef71ce9-36a5-4eeb-a465-03b51e01d191","name":"VIP","slug":"vip","customer_count":12,"created_at":"2026-08-01T09:30:00+05:30","updated_at":"2026-08-01T10:15:00+05:30"}],"skipped":[],"errors":[],"row_errors":[]}}

Update a Customer Tag

PUT write_customers

Update a Customer Tag.

Updates provided fields. Omitted fields remain unchanged.

Path parameters

Name	Type	Description
`id` required	`string`	Customer Tag UUID. Example: `2ef71ce9-36a5-4eeb-a465-03b51e01d191`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`name`	`string`	Customer Tag name. Example: `VIP`
`slug`	`string`	Customer Tag slug. Omit on create to generate it from the name. Example: `vip`

Errors

400 CUSTOMER_REQUEST_INVALID
Id is not a valid UUID.
404 CUSTOMER_TAG_NOT_FOUND
Customer Tag does not exist in this store.
400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CUSTOMER_TAG_NAME_REQUIRED
Name is required.
400 CUSTOMER_TAG_NAME_TOO_LONG
Name exceeds the configured limit.
400 CUSTOMER_SLUG_INVALID
Slug is invalid.
409 CUSTOMER_TAG_NAME_DUPLICATE
A Customer Tag with this name already exists.
409 CUSTOMER_TAG_SLUG_DUPLICATE
A Customer Tag with this slug already exists.
400 CUSTOMER_TAGS_LIMIT
The store has reached its Customer Tag limit.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "VIP",
  "slug": "vip"
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "name": "VIP",
    "slug": "vip"
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "name": "VIP",
        "slug": "vip",
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"id":"2ef71ce9-36a5-4eeb-a465-03b51e01d191","name":"VIP","slug":"vip","customer_count":12,"created_at":"2026-08-01T09:30:00+05:30","updated_at":"2026-08-01T10:15:00+05:30"}}

Delete a Customer Tag

DELETE write_customers

Delete a Customer Tag.

If assignments or customer-group rules depend on the tag, retry with the returned confirmation token.

Path parameters

Name	Type	Description
`id` required	`string`	Customer Tag UUID. Example: `2ef71ce9-36a5-4eeb-a465-03b51e01d191`

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`confirmed`	`boolean`	On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
`confirmation_token`	`string`	Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

400 CUSTOMER_REQUEST_INVALID
Id is not a valid UUID.
404 CUSTOMER_TAG_NOT_FOUND
Customer Tag does not exist in this store.
409 CONFIRMATION_REQUIRED
Deletion requires confirmation.
400 CUSTOMER_CONFIRMATION_INVALID
The confirmation token is invalid or expired.

curl -X DELETE 'https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191", {
  method: "DELETE",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.delete(
    "https://api-store.tringify.com/api/2025-01/customer-tags/2ef71ce9-36a5-4eeb-a465-03b51e01d191",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"deleted":true,"id":"2ef71ce9-36a5-4eeb-a465-03b51e01d191"}}

Bulk delete Customer Tags

POST write_customers

Delete multiple Customer Tags.

Deletes the selected store-scoped UUIDs transactionally. Dependency changes can require a fresh confirmation retry.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Body parameters

Name	Type	Description
`tag_ids` required	`array<string>`	Store-scoped Customer Tag UUIDs. Example: `["2ef71ce9-36a5-4eeb-a465-03b51e01d191"]`
`confirmed`	`boolean`	On a confirmation retry, set this to true and send the returned confirmation_token. Omit it on the first request.
`confirmation_token`	`string`	Token from the CONFIRMATION_REQUIRED response. Omit it on the first request and resend the exact same id selection when using it.

Errors

400 STORE_API_INVALID_REQUEST_BODY
Request body is not valid JSON.
400 CUSTOMER_TAGS_NONE_SPECIFIED
Tag_ids must contain at least one UUID.
400 CUSTOMER_TAGS_BULK_DELETE_MAX
The request exceeds the bulk-delete cap.
409 CUSTOMER_TAG_BULK_RACED
Dependencies changed; obtain a fresh confirmation.
409 CONFIRMATION_REQUIRED
Deletion requires confirmation.
400 CUSTOMER_CONFIRMATION_INVALID
The confirmation token is invalid or expired.

curl -X POST 'https://api-store.tringify.com/api/2025-01/customer-tags/bulk-delete' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "tag_ids": [
    "2ef71ce9-36a5-4eeb-a465-03b51e01d191"
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/customer-tags/bulk-delete", {
  method: "POST",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "tag_ids": [
      "2ef71ce9-36a5-4eeb-a465-03b51e01d191"
    ]
  }),
});
const data = await res.json();

import requests

res = requests.post(
    "https://api-store.tringify.com/api/2025-01/customer-tags/bulk-delete",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "tag_ids": ["2ef71ce9-36a5-4eeb-a465-03b51e01d191"],
    },
)
data = res.json()

Response

200

Sample response

{"success":true,"data":{"deleted":["2ef71ce9-36a5-4eeb-a465-03b51e01d191"],"failed":[]}}

Fields#

Field	Type	Create	Update	Required	Translatable
`name`	text	Yes	Yes	create	No
`slug`	slug	Yes	Yes		No
`customer_count`	integer	No	No		No
`created_at`	datetime	No	No		No
`updated_at`	datetime	No	No		No

Webhook events#

Subscribe to these events to keep your integration in sync with customer tags. Each event shows the required Store API scope and store permission, the available payload fields, and an example payload. Subscription setup is validated against those permissions; delivery is always restricted to the subscription's store.

Customer tag created

EVENT customer_tags/create App scope: read_customers Staff permission: customers:write

Fired when a customer tag is created.

Payload fields

Field	Type	Description
`tag.id`	`string`	Always present
`tag.name`	`string`	Selectable in the Payload builder
`tag.slug`	`string`	Selectable in the Payload builder
`tag.customer_count`	`integer`	Selectable in the Payload builder
`tag.created_at`	`string`	Selectable in the Payload builder
`tag.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "tag": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "customer_count": 128,
    "id": "cus_5d2e8b1a",
    "name": "VIP",
    "slug": "vip",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Customer tag updated

EVENT customer_tags/update App scope: read_customers Staff permission: customers:write

Fired when a customer tag is renamed.

Possible `changed_fields` values

The changed_fields array names exactly which of these changed in this event — use it to skip processing updates your integration doesn't care about.

name slug

Payload fields

Field	Type	Description
`previous.id`	`string`	Always present
`previous.name`	`string`	Selectable in the Payload builder
`previous.slug`	`string`	Selectable in the Payload builder
`previous.customer_count`	`integer`	Selectable in the Payload builder
`previous.created_at`	`string`	Selectable in the Payload builder
`previous.updated_at`	`string`	Selectable in the Payload builder
`current.id`	`string`	Always present
`current.name`	`string`	Selectable in the Payload builder
`current.slug`	`string`	Selectable in the Payload builder
`current.customer_count`	`integer`	Selectable in the Payload builder
`current.created_at`	`string`	Selectable in the Payload builder
`current.updated_at`	`string`	Selectable in the Payload builder
`changed_fields`	`array`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "changed_fields": [
    "name",
    "slug"
  ],
  "current": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "customer_count": 128,
    "id": "cus_5d2e8b1a",
    "name": "VIP",
    "slug": "vip",
    "updated_at": "2026-06-09T12:00:00+05:30"
  },
  "previous": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "customer_count": 128,
    "id": "cus_5d2e8b1a",
    "name": "VIP",
    "slug": "vip",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Customer tag deleted

EVENT customer_tags/delete App scope: read_customers Staff permission: customers:write

Fired when a customer tag is deleted; assignments cascade.

Payload fields

Field	Type	Description
`tag.id`	`string`	Always present
`tag.name`	`string`	Selectable in the Payload builder
`tag.slug`	`string`	Selectable in the Payload builder
`tag.customer_count`	`integer`	Selectable in the Payload builder
`tag.created_at`	`string`	Selectable in the Payload builder
`tag.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "tag": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "customer_count": 128,
    "id": "cus_5d2e8b1a",
    "name": "VIP",
    "slug": "vip",
    "updated_at": "2026-06-09T12:00:00+05:30"
  }
}

Endpoints#

Headers

Query parameters

Headers

Errors

Path parameters

Headers

Errors

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Path parameters

Headers

Body parameters

Errors

Headers

Body parameters

Errors

Fields#

Webhook events#

Payload fields

Possible changed_fields values

Payload fields

Payload fields

Possible `changed_fields` values