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

# Tags and Statuses

> Tags and statuses allow brands to label and categorise profiles for operational and incentive purposes.

Omneo provides two mechanisms for labelling profiles: **Tags** and **Statuses**. Both are classification tools, but they serve different purposes and behave differently.

## Tags

**Tags** are short, freeform labels that can be assigned to any profile. They are used for ad hoc categorisation, operational notes, or segmentation.

**Examples:**

* `christmas-campaign-2024`
* `handle-with-care`
* `influencer-referral`
* `vip-waitlist`

Tags are case-sensitive strings. A profile can have zero or many tags. Tags are available in reaction conditions via the `flattened_tags` array, making them useful as filtering criteria in automation logic.

Tags can be:

* Applied manually in CX Manager or Clienteling
* Set programmatically via the API
* Bulk-updated via the import tool
* Used as conditions in reactions and claimable benefit JSON logic

## Statuses

**Statuses** are a special class of label that represent a defined relationship between a profile and the brand. Unlike tags, statuses are configured in CX Manager as named definitions with structured properties.

**Examples:**

* `Staff`: internal employees who receive staff discounts
* `VIP`: high-value customers with elevated entitlements
* `Influencer`: customers with social media reach
* `Stylist`: in-store advisors linked to client profiles
* `Media`: press and media contacts

### How statuses work

A profile can have zero, one, or multiple statuses applied simultaneously. Statuses can be:

* **Customer-facing or internal:** configurable per status definition
* **Ranked:** determining precedence when a customer holds multiple statuses and only one "best" status is needed
* **Grouped:** statuses can be organised into logical or functional groups (for example, grouping all trade-related statuses together)
* **Time-limited:** statuses can be assigned an expiry date, after which they are automatically removed from the profile
* **Manually assigned:** by admin or manager users in CX Manager, or by store staff in Clienteling
* **Programmatically applied:** via API or integration logic (for example, linking an Instagram account with 10k+ followers triggers "Influencer" status)
* **Bulk-updated:** as part of implementation or ongoing data operations

<Warning>
  Adding a status the wrong way removes a profile's other statuses. The profile import and a `PUT` to the profile endpoint both replace the entire status set: they detach any status not present in the payload. To add a status while keeping the ones a profile already holds, use the additive batch status endpoint. See [Statuses (dev guide)](/dev-guides/profiles/statuses).
</Warning>

### Custom fields and metadata

Status definitions can carry custom fields, metadata, and internal or public-facing content. This information travels with the status and is accessible to any logic or presentation system that has access to the profile, including Reactions, Target templates, and consumer-facing surfaces like Profile Portal and Omneo Wallet. This makes statuses a flexible vehicle for delivering contextual content or configuration to different parts of the platform.

### Statuses in incentive logic

A profile's status can modify incentive entitlements:

* VIP status: 30 extra days on rewards and benefits
* Staff status: 40% off benefit on all full-price items
* Influencer status: double Tier Points on all purchases
* Media status: free delivery benefit on online orders

Statuses are available in reaction conditions and target templates via the `flattened_statuses` array.

## Mutation semantics on the main Profile endpoints

<Warning>
  Including `tags` or `statuses` on `POST /v3/profiles` or `PUT /v3/profiles/{profile}` is a **destructive replace** at the link level, not a merge. Tags or statuses not in the supplied list are detached from the profile (the tag and status definitions themselves are not deleted).

  * Omitting the key from the request body leaves the profile's tags or statuses untouched.
  * Sending `tags: []` or `statuses: []` removes every tag or status from the profile.
  * Sending a partial list keeps only what is in that list.

  For add or remove operations on individual tags or statuses, use the dedicated batch endpoints: [batch update tags](/api-reference/profile-tag/batch-update-profile-tags), [batch delete tags](/api-reference/profile-tag/batch-delete-profile-tags), [batch update statuses](/api-reference/profile-status/batch-update-profile-statuses), [batch delete statuses](/api-reference/profile-status/batch-delete-profile-statuses). See [Mutation semantics on POST and PUT](/concepts/profiles/overview#mutation-semantics-on-post-and-put) for the same behaviour on other profile collections.
</Warning>

## Related

* [Profiles](/concepts/profiles/overview)
* [Reactions](/concepts/automation/reactions)
* [Tags and statuses API](/api-reference/profile-tag)