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

# Short URL field

> A field that mints a short branded link for each record, redirects clicks to a destination URL held by another field, and records every click for analytics.

<Info>
  A Short URL field mints a short branded link for every record, such as `https://go.acme.example/aB3xK9q2`. When someone opens the link, they are redirected to a destination URL held by another field, and the click is recorded. See those clicks under [Analytics](/guides/analytics).

  The link reads like `bit.ly`, but the slug policy is declared on the field and the destination comes from your own data, so the short link is stable while the destination can still change up to approval.
</Info>

## When to use it

* You want a short, shareable link for every record: marketing campaigns, print collateral, social posts.
* The destination is already a field on the taxonomy, usually a [Tagged URL](/reference/fields/tagged-url) carrying your UTM parameters, and you want a short link in front of it.
* You want click tracking. Every visit to the short link is recorded and shows up in [Analytics](/guides/analytics).
* You want one place to retarget without reprinting: the short link's slug and domain are fixed once approved, but you can still edit the destination afterward.

<Warning>
  Don't use this when a plain [URL field](/reference/fields/url) is enough. If you don't need a branded short link or click tracking, you don't need a Short URL field.
</Warning>

## How it works

A short link is a `domain` plus a `slug` (the part after the slash) that redirects to a destination URL. You choose the destination by pointing the field at another field with `destination_url_field`, and you choose how the slug is filled with `slug_mode`.

The link is provisioned as a draft while a submission is being built, so you can preview and edit it. It goes live only when the submission is approved. From that moment on, the link's domain, slug, and live state are frozen and can no longer change. You can still update the destination URL on a live link, so changing the destination field retargets the same short link without reprinting anything.

For how each slug mode behaves in the builder and on approval, see [Short URL slug modes](/recipes/short-url-slug-modes).

## Settings reference

| Setting                 | Required | Default                          | Description                                                                                                                                                                           |
| ----------------------- | -------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `destination_url_field` | Yes      | None                             | Field ID of the destination. Must reference a [URL](/reference/fields/url) or [Tagged URL](/reference/fields/tagged-url) field. Its resolved value is where the short link redirects. |
| `slug_mode`             | No       | `auto_editable`                  | How the slug is filled. One of `auto_editable`, `auto_only`, `manual_only`. See the table below.                                                                                      |
| `domain`                | No       | Account default shortener domain | The domain to mint links on. Omit it (or leave it empty) to use your account's default shortener domain. To use a branded domain, add and verify it first, then set it here.          |
| `slug_size`             | No       | `10`                             | Length of the auto-generated slug, between 4 and 50. Only meaningful in `auto_editable` and `auto_only`. Leave it out in `manual_only`.                                               |

The top-level `required` flag lives on the field itself, not inside `settings`. On top of any field-level uniqueness, Terminus Hub always enforces that each `domain` plus `slug` pair is unique, so two records can never hold the same short link.

### Slug modes at a glance

| `slug_mode`               | Who fills the slug                           |        Editable in the builder?       |
| ------------------------- | -------------------------------------------- | :-----------------------------------: |
| `auto_editable` (default) | Generated automatically, you can override it | Yes, pre-filled with a generated slug |
| `auto_only`               | Generated automatically, you cannot edit it  |             No, read-only             |
| `manual_only`             | You type it                                  |         Yes, you must enter it        |

<Note>
  `derived` slug mode (taking the slug from another field) is not available. Use one of the three modes above.
</Note>

## Example

In the Campaign URL Builder, a Short URL field sits in front of the UTM-tagged destination:

```yaml theme={null}
name: short_url
type: short_url
settings:
  destination_url_field: tagged_url
  slug_mode: auto_editable
  slug_size: 8
```

`destination_url_field` points at the upstream Tagged URL field, so the short link redirects to the already-tagged campaign URL. With `slug_mode: auto_editable`, the builder drafts a random eight-character slug when you create the submission, and you can overwrite it before approval.

For a submission with `campaign_name = "Black Friday 2026"`, you might draft:

```text theme={null}
https://go.acme.example/aB3xK9q2
```

If you replace the slug with `blkfri26` before approving, the approved record's short link becomes `https://go.acme.example/blkfri26`. After approval that slug is frozen. Opening either link redirects to the full Tagged URL and records the click for analytics.

## Gotchas

* **`auto_editable` lets people edit the slug, `auto_only` does not.** That difference drives the builder: an `auto_only` field is read-only and shows "(will be generated on save)", while `auto_editable` shows an editable input pre-filled with a generated slug. If you want "auto" to also mean "users can't touch it," choose `auto_only`.
* **Auto-generated slugs can change until you edit them.** As long as you have not edited the slug yourself, the builder may generate a fresh random slug each time it saves, retrying if the random slug collides with an existing link on the same domain. The slug you see in the draft is not final until you type your own or approve. Once you edit it, your value sticks.
* **A short link is frozen after approval.** After the submission is approved, the link's domain, slug, and live state cannot change. To retarget an approved link, change the destination URL field, not the slug. Fixing a typo in a slug means a new link.
* **At most one Short URL field per taxonomy.** A taxonomy that references two Short URL fields is rejected. If you need multiple short links per record (for example on different domains), use separate taxonomies.
* **`slug_size` only applies to the auto modes.** It controls the length of an auto-generated slug. In `manual_only` the slug length is bounded only by the character rule, so leave `slug_size` out.
* **Slugs are URL-safe only.** A slug must be present and use letters, numbers, hyphens, and underscores. Spaces, slashes, emoji, and other punctuation are rejected.
* **The destination must be an `http` or `https` URL.** The redirect target comes from the linked URL or Tagged URL field and must use a supported web protocol.
* **A custom `domain` must be one you have added and verified.** Leave `domain` unset to use your account's default shortener domain. To serve links from a branded domain, add and verify it first, then set the field's `domain` to it.
* **For QR codes, point the QR field at the Short URL field, not a raw URL.** A [QR Code](/reference/fields/qr-code) field can target any field, but scans are only tracked separately from clicks when its source is a Short URL field.

## Related

* [QR Code field](/reference/fields/qr-code): wraps a Short URL so scans are tracked as their own click type.
* [Short URL slug modes](/recipes/short-url-slug-modes): a deeper look at choosing a `slug_mode`.
* [Analytics](/guides/analytics): where the clicks on your short links are reported.
* [Tagged URL field](/reference/fields/tagged-url): the usual destination for a Short URL.