Customers

Tags and metadata

When to reach for a tag, when to define a custom field, and how to switch.
View as Markdown

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

TagsCustom fields
ShapeFree-form text, one or many per customerTyped (string, number, date, select), one value per field per customer
Define ahead of time?No, you type and it existsYes, configured once in Admin > Custom fields
Best forAd-hoc grouping while you figure out what mattersThings you’ll filter on, report on, or sync from a CRM
FiltersYes, tag:vip in searchYes, field_name:value
API shapeArray of stringsObject keyed by field slug
RenamingRename a tag and every customer using it updatesRename a field slug and your CRM mapping, webhook payload, and API consumers break
ReportsGroup by tag presenceGroup 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 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.

Email help@pivotal.app with a screenshot of where you got stuck and the customer or onboarding id from the URL.