> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pivotal.app/llms.txt.
> For full documentation content, see https://docs.pivotal.app/llms-full.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pivotal.app/_mcp/server.

# Tags and metadata

Pivotal gives you two ways to attach extra information to a Customer: tags and custom fields. They look similar in the UI and both surface in filters, search, and the API, but they behave differently enough that picking the wrong one creates pain later. Use this page to pick the right tool on the first try.

## Side by side

|                       | Tags                                                            | Custom fields                                                                      |
| --------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| Shape                 | Free-form text, one or many per customer                        | Typed (string, number, date, select), one value per field per customer             |
| Define ahead of time? | No, you type and it exists                                      | Yes, configured once in **Admin > Custom fields**                                  |
| Best for              | Ad-hoc grouping while you figure out what matters               | Things you'll filter on, report on, or sync from a CRM                             |
| Filters               | Yes, `tag:vip` in [search](/product/customers/search-customers) | Yes, `field_name:value`                                                            |
| API shape             | Array of strings                                                | Object keyed by field slug                                                         |
| Renaming              | Rename a tag and every customer using it updates                | Rename a field slug and your CRM mapping, webhook payload, and API consumers break |
| Reports               | Group by tag presence                                           | Group by field value, plot trends across selects                                   |

## When to use a tag

Reach for a tag when you're still figuring out what the category is, or when the label is one of many a customer might have. Examples:

* `pilot`, `beta-user`, `case-study-candidate`
* `expansion-opportunity`, `referenceable`
* `gtm-q3-campaign`

Tags are cheap. Create them as you go, delete them when they stop being useful, and don't worry about reusing them.

## When to use a custom field

Reach for a custom field when the label has a clear type, exactly one value per customer, and you'll filter or report on it. Examples:

* `region` as a select with values `na`, `emea`, `apac`
* `arr` as a number
* `contract_start` as a date
* `industry` as a string synced from HubSpot

## Promoting a tag to a custom field

Once a tag stabilizes into a real category (a region, a tier), promote it:

1. Open **Admin > Custom fields** and create the new field with the right type and options.
2. Filter the Customers list by the tag you're replacing.
3. Bulk-select, **Edit selected**, set the new custom field. See [edit customer details](/product/customers/edit-customer-details) for the bulk-edit flow.
4. Once everyone has the field set, remove the tag from **Admin > Tags**. Deleting a tag is a soft delete; you can restore for 30 days.

## The gotcha: renaming a custom field slug

Renaming the **label** of a custom field is safe and updates everywhere. Renaming the **slug** (under the field's advanced settings) breaks anything that references the old slug, including HubSpot field mappings, webhook payload keys, and API integrations. If you have to do it, change the consumer first, then change the slug, then re-run the affected syncs.

## Related

* [Edit customer details](/product/customers/edit-customer-details)
* [Search customers](/product/customers/search-customers)
* [Field mapping](/product/integrations/field-mapping)

Email **[help@pivotal.app](mailto:help@pivotal.app)** with a screenshot of where you got stuck and the customer or onboarding id from the URL.