What do external IDs do on tiers and label types?

External IDs let you refer to tiers and label types in the API using your own system's identifiers instead of Plain's internal IDs such as ti_01xxx... or lt_01xxx.... The externalId field is optional on both. Leave it blank if you do not need it.

• Tiers: use the externalId anywhere the API accepts a TierIdentifier, such as when adding or removing tier members, without looking up the internal Plain ID first.
• Label types: fetch a label type by its externalId with the labelTypeByExternalId GraphQL query.

Naming rules

Plain does not enforce a naming convention. An external ID must be:

• Unique within your workspace, so every lookup is unambiguous
• Between 1 and 500 characters
• Stable. Renaming an external ID breaks any code that references it.

  Use values that already exist in your system, such as billing plan slugs like starter, pro and enterprise, or internal tier keys. Simple lowercase strings like billing and slash-separated values like tier/starter or success/package/scale both work.

What external IDs do not affect

• Display names. The name shown in Plain comes from the name field, not the external ID.
• Tier assignment. An external ID does not add any companies or tenants to a tier. You still add members through the API or the UI.
• SLA targets. SLA rules are tied to the tier itself, not to the external ID.

Related documentation

• Manage label types
• Tiers & SLAs