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

# Upsert Tags

<Info>
  Scope required: `tags.write`
</Info>

This endpoint allows for bulk upserting of tag values for specified users. If
a tag with the specified key does not exist for the user / merchant pair, a new
tag record is created with the specified values. If a tag with the specified
key already exists, the tag values are updated. A maximum of 500 `user_ids` can
be specified per API request.

Currently, tags are merchant/user-scoped. This means that they are accessible
to be managed by all integration partners a given merchant enables. Given this,
for tags that are integration-specific and not general purpose user profile
attributes, we recommend integration partners prefix tag keys with the name of
your organization to avoid key usage conflicts between integrations enabled for
a given merchant.

eg:

* `thanx-custom-tag`, rather than `custom-tag`, would be preferred for tags
  that are integration specific
* `allergens` should still be used, if it's expected that the tag be leveraged
  as a general-purpose user profile attribute

Tag keys are case-insensitive — `Employee` and `employee` are treated as the same
key (writing one overwrites the other's values), so use a consistent
lowercase-with-hyphens convention.

### Parameters

<ParamField body="merchant_id" type="string">
  Merchant ID
</ParamField>

<ParamField body="user_ids" type="array<string>">
  User IDs (500 max per request)
</ParamField>

<Warning>
  `user_ids` must be each user's Thanx identifier — the value returned as `id` by
  [Get Users](/partner/users/get-users). An ID copied from a dashboard URL or a
  customer-data/SFTP export is a **different encoding** and will not match: the
  request returns `201` with **zero tags written** and no error. Confirm one test
  user lands before running a bulk write.
</Warning>

<ParamField body="key" type="string">
  Tag key
</ParamField>

<ParamField body="values" type="array(string)">
  Array of tag values (50 max)
</ParamField>

### Response

<RequestExample>
  ```bash theme={null}
  curl https://api.thanxsandbox.com/partner/tags \
    -X PUT \
    -H 'X-ClientId: {client_id}' \
    -H 'Accept-Version: v4.0' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {access_token}' \
    -d '{
      "merchant_id": "weroifs",
      "user_ids": [
        "wroeiu2304hfwf",
        "73bf1f46769dwr"
      ],
      "key": "allergens",
      "values": [
        "gluten",
        "soy",
        "dairy",
        "honey"
      ]
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {}
  ```
</ResponseExample>