> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stateset.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tag Customer

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

### Body

<ParamField body="customer_id" type="string">
  The unique identifier of the customer
</ParamField>

<ParamField body="tags_to_add" type="array">
  Array of tags to add to the customer
</ParamField>

<ParamField body="tags_to_remove" type="array">
  Array of tags to remove from the customer
</ParamField>

<ParamField body="tag_metadata" type="object">
  Optional metadata for tags

  <Expandable title="properties">
    <ParamField body="category" type="string">
      Tag category (e.g., "loyalty", "segment", "preference", "behavior")
    </ParamField>

    <ParamField body="source" type="string">
      Source of the tag (e.g., "manual", "automatic", "import", "rule\_based")
    </ParamField>

    <ParamField body="expiry_date" type="string">
      Optional expiry date for time-limited tags
    </ParamField>
  </Expandable>
</ParamField>

### Response

<ResponseField name="id" type="string">
  The customer ID
</ResponseField>

<ResponseField name="current_tags" type="array">
  Array of all current tags on the customer
</ResponseField>

<ResponseField name="tags_added" type="array">
  Tags that were successfully added
</ResponseField>

<ResponseField name="tags_removed" type="array">
  Tags that were successfully removed
</ResponseField>

<ResponseField name="tag_count" type="number">
  Total number of tags on the customer
</ResponseField>

<ResponseField name="segments" type="array">
  Customer segments based on current tags
</ResponseField>

<ResponseField name="updated_at" type="string">
  Timestamp when tags were last updated
</ResponseField>

<ResponseField name="success" type="boolean">
  Indicates whether the operation was successful
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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"
      }
  }'
  ```

  ```graphQL GraphQL theme={null}
  mutation customerTagMutation {
    customerTag(
      customerId: "${customerId}",
      tagsToAdd: ${tagsToAdd},
      tagsToRemove: ${tagsToRemove},
      tagMetadata: ${tagMetadata}
    ) {
      customer {
        id
        current_tags
        segments
        tag_count
      }
      userErrors {
        field
        message
      }
    }
  }
  ```

  ```js Node.js theme={null}
  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'
    }
  });
  ```

  ```python Python theme={null}
  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'
    }
  })
  ```

  ```ruby Ruby theme={null}
  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'
    }
  })
  ```

  ```go Go theme={null}
  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'
    }
  })
  ```

  ```java Java theme={null}
  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'
    }
  });
  ```

  ```php PHP theme={null}
  $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'
    ]
  ]);
  ```

  ```csharp C# theme={null}
  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'
    }
  });
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "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
  }
  ```

  ```json Error Response theme={null}
  {
    "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_]+$"
      }
    }
  }
  ```
</ResponseExample>