Tag Customer

This endpoint adds or removes tags from a customer for segmentation and categorization.

POST /v1/customers/:id/tag

cURL

curl --location --request POST 'https://api.stateset.com/v1/customers/:id/tag' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <token>' \
--data-raw '{
    "customer_id": "cust_123abc",
    "tags_to_add": ["vip", "high_value", "early_adopter"],
    "tags_to_remove": ["prospect"],
    "tag_metadata": {
        "category": "loyalty",
        "source": "manual",
        "expiry_date": "2024-12-31"
    }
}'

mutation customerTagMutation {
  customerTag(
    customerId: "${customerId}",
    tagsToAdd: ${tagsToAdd},
    tagsToRemove: ${tagsToRemove},
    tagMetadata: ${tagMetadata}
  ) {
    customer {
      id
      current_tags
      segments
      tag_count
    }
    userErrors {
      field
      message
    }
  }
}

const taggedCustomer = await stateset.customers.tag({
  customer_id: 'cust_123abc',
  tags_to_add: ['vip', 'high_value', 'early_adopter'],
  tags_to_remove: ['prospect'],
  tag_metadata: {
    category: 'loyalty',
    source: 'manual',
    expiry_date: '2024-12-31'
  }
});

tagged_customer = stateset.customers.tag({
  'customer_id': 'cust_123abc',
  'tags_to_add': ['vip', 'high_value', 'early_adopter'],
  'tags_to_remove': ['prospect'],
  'tag_metadata': {
    'category': 'loyalty',
    'source': 'manual',
    'expiry_date': '2024-12-31'
  }
})

tagged_customer = Stateset::Customer.tag({
  customer_id: 'cust_123abc',
  tags_to_add: ['vip', 'high_value', 'early_adopter'],
  tags_to_remove: ['prospect'],
  tag_metadata: {
    category: 'loyalty',
    source: 'manual',
    expiry_date: '2024-12-31'
  }
})

taggedCustomer, err := stateset.Customers.tag({
  CustomerID: 'cust_123abc',
  TagsToAdd: []string{'vip', 'high_value', 'early_adopter'},
  TagsToRemove: []string{'prospect'},
  TagMetadata: TagMetadata{
    Category: 'loyalty',
    Source: 'manual',
    ExpiryDate: '2024-12-31'
  }
})

Customer taggedCustomer = stateset.customers.tag({
  customerId: 'cust_123abc',
  tagsToAdd: ['vip', 'high_value', 'early_adopter'],
  tagsToRemove: ['prospect'],
  tagMetadata: {
    category: 'loyalty',
    source: 'manual',
    expiryDate: '2024-12-31'
  }
});

$tagged_customer = $stateset->customers->tag([
  'customer_id' => 'cust_123abc',
  'tags_to_add' => ['vip', 'high_value', 'early_adopter'],
  'tags_to_remove' => ['prospect'],
  'tag_metadata' => [
    'category' => 'loyalty',
    'source' => 'manual',
    'expiry_date' => '2024-12-31'
  ]
]);

var taggedCustomer = await stateset.Customers.Tag(new {
  CustomerId = 'cust_123abc',
  TagsToAdd = new[] { 'vip', 'high_value', 'early_adopter' },
  TagsToRemove = new[] { 'prospect' },
  TagMetadata = new {
    Category = 'loyalty',
    Source = 'manual',
    ExpiryDate = '2024-12-31'
  }
});

Response

{
  "id": "cust_123abc",
  "current_tags": [
    "vip",
    "high_value", 
    "early_adopter",
    "repeat_buyer",
    "email_subscriber"
  ],
  "tags_added": ["vip", "high_value", "early_adopter"],
  "tags_removed": ["prospect"],
  "tag_count": 5,
  "segments": [
    {
      "id": "seg_premium",
      "name": "Premium Customers",
      "matched_by_tags": ["vip", "high_value"]
    },
    {
      "id": "seg_engaged",
      "name": "Highly Engaged",
      "matched_by_tags": ["repeat_buyer", "email_subscriber"]
    }
  ],
  "updated_at": "2024-01-15T10:30:00Z",
  "updated_by": "user_123",
  "success": true
}

{
  "error": {
    "code": "invalid_tag",
    "message": "Tag 'invalid-tag!' contains invalid characters. Tags must be alphanumeric with underscores only.",
    "details": {
      "invalid_tags": ["invalid-tag!"],
      "valid_pattern": "^[a-zA-Z0-9_]+$"
    }
  }
}

Body

customer_id · string

The unique identifier of the customer

tags_to_add · array

Array of tags to add to the customer

tags_to_remove · array

Array of tags to remove from the customer

tag_metadata · object

Optional metadata for tags

Show properties

category · string

Tag category (e.g., “loyalty”, “segment”, “preference”, “behavior”)

source · string

Source of the tag (e.g., “manual”, “automatic”, “import”, “rule_based”)

expiry_date · string

Optional expiry date for time-limited tags

Response

id · string

The customer ID

current_tags · array

Array of all current tags on the customer

tags_added · array

Tags that were successfully added

tags_removed · array

Tags that were successfully removed

tag_count · number

Total number of tags on the customer

segments · array

Customer segments based on current tags

updated_at · string

Timestamp when tags were last updated

success · boolean

Indicates whether the operation was successful

cURL

curl --location --request POST 'https://api.stateset.com/v1/customers/:id/tag' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <token>' \
--data-raw '{
    "customer_id": "cust_123abc",
    "tags_to_add": ["vip", "high_value", "early_adopter"],
    "tags_to_remove": ["prospect"],
    "tag_metadata": {
        "category": "loyalty",
        "source": "manual",
        "expiry_date": "2024-12-31"
    }
}'

mutation customerTagMutation {
  customerTag(
    customerId: "${customerId}",
    tagsToAdd: ${tagsToAdd},
    tagsToRemove: ${tagsToRemove},
    tagMetadata: ${tagMetadata}
  ) {
    customer {
      id
      current_tags
      segments
      tag_count
    }
    userErrors {
      field
      message
    }
  }
}

const taggedCustomer = await stateset.customers.tag({
  customer_id: 'cust_123abc',
  tags_to_add: ['vip', 'high_value', 'early_adopter'],
  tags_to_remove: ['prospect'],
  tag_metadata: {
    category: 'loyalty',
    source: 'manual',
    expiry_date: '2024-12-31'
  }
});

tagged_customer = stateset.customers.tag({
  'customer_id': 'cust_123abc',
  'tags_to_add': ['vip', 'high_value', 'early_adopter'],
  'tags_to_remove': ['prospect'],
  'tag_metadata': {
    'category': 'loyalty',
    'source': 'manual',
    'expiry_date': '2024-12-31'
  }
})

tagged_customer = Stateset::Customer.tag({
  customer_id: 'cust_123abc',
  tags_to_add: ['vip', 'high_value', 'early_adopter'],
  tags_to_remove: ['prospect'],
  tag_metadata: {
    category: 'loyalty',
    source: 'manual',
    expiry_date: '2024-12-31'
  }
})

taggedCustomer, err := stateset.Customers.tag({
  CustomerID: 'cust_123abc',
  TagsToAdd: []string{'vip', 'high_value', 'early_adopter'},
  TagsToRemove: []string{'prospect'},
  TagMetadata: TagMetadata{
    Category: 'loyalty',
    Source: 'manual',
    ExpiryDate: '2024-12-31'
  }
})

Customer taggedCustomer = stateset.customers.tag({
  customerId: 'cust_123abc',
  tagsToAdd: ['vip', 'high_value', 'early_adopter'],
  tagsToRemove: ['prospect'],
  tagMetadata: {
    category: 'loyalty',
    source: 'manual',
    expiryDate: '2024-12-31'
  }
});

$tagged_customer = $stateset->customers->tag([
  'customer_id' => 'cust_123abc',
  'tags_to_add' => ['vip', 'high_value', 'early_adopter'],
  'tags_to_remove' => ['prospect'],
  'tag_metadata' => [
    'category' => 'loyalty',
    'source' => 'manual',
    'expiry_date' => '2024-12-31'
  ]
]);

var taggedCustomer = await stateset.Customers.Tag(new {
  CustomerId = 'cust_123abc',
  TagsToAdd = new[] { 'vip', 'high_value', 'early_adopter' },
  TagsToRemove = new[] { 'prospect' },
  TagMetadata = new {
    Category = 'loyalty',
    Source = 'manual',
    ExpiryDate = '2024-12-31'
  }
});

Response

{
  "id": "cust_123abc",
  "current_tags": [
    "vip",
    "high_value", 
    "early_adopter",
    "repeat_buyer",
    "email_subscriber"
  ],
  "tags_added": ["vip", "high_value", "early_adopter"],
  "tags_removed": ["prospect"],
  "tag_count": 5,
  "segments": [
    {
      "id": "seg_premium",
      "name": "Premium Customers",
      "matched_by_tags": ["vip", "high_value"]
    },
    {
      "id": "seg_engaged",
      "name": "Highly Engaged",
      "matched_by_tags": ["repeat_buyer", "email_subscriber"]
    }
  ],
  "updated_at": "2024-01-15T10:30:00Z",
  "updated_by": "user_123",
  "success": true
}

{
  "error": {
    "code": "invalid_tag",
    "message": "Tag 'invalid-tag!' contains invalid characters. Tags must be alphanumeric with underscores only.",
    "details": {
      "invalid_tags": ["invalid-tag!"],
      "valid_pattern": "^[a-zA-Z0-9_]+$"
    }
  }
}