Tags are user-defined labels for organizing references. They are scoped to your organization, unique by name, and can be managed via the API or applied inline during reference creation.

Creating tags

Tags can be created explicitly or inline.

Explicit creation via POST /tags:

POST /tags
{
  "name": "priority:high"
}

Inline creation by name when tagging a reference. If the tag name doesn't already exist, it is created automatically.

Tagging references

At creation time

Include a tags array when creating a reference. Each entry is either { id } (existing tag) or { name } (upsert by name):

POST /references
{
  "container_id": "MEDU8381210",
  "carrier_code": "MSCU",
  "tags": [
    { "id": "existing-tag-uuid" },
    { "name": "priority:high" },
    { "name": "region/apac" }
  ]
}

Tags are validated before the reference is saved. If any tag is invalid, the entire request is rejected.

After creation

Add tags to an existing reference via POST /references/{referenceId}/tags:

POST /references/{referenceId}/tags
{
  "tags": [
    { "name": "expedited" }
  ]
}

This is idempotent -- adding a tag that is already associated with the reference has no effect.

Removing tags

Remove a single tag from a reference via DELETE /references/{referenceId}/tags/{tagId}. Removing a tag association does not delete the tag itself.

Querying references by tag

Filter the reference list using tag_ids or tag_names query parameters.

GET /references?tag_names=priority:high&tag_names=expedited
GET /references?tag_ids=uuid1&tag_ids=uuid2

To list all references for a specific tag, use GET /tags/{tagId}/references.

Tags in webhooks

Webhook payloads include a reference_tags field at the top level containing the reference's current tags at the time the webhook fires:

{
  "reference_id": "...",
  "reference_tags": [
    { "id": "tag-uuid", "name": "priority:high" }
  ],
  "status": "data_received",
  "payload": { ... }
}

If a reference has no tags, reference_tags is an empty array.

Tag propagation

When a bill of lading or booking number reference creates child container references, the parent's tags are automatically applied to each child. This is a one-time snapshot -- subsequent tag changes on the parent or child are independent.

Tag naming

We recommend adopting a consistent naming convention across your organization. Here are some common patterns:

Pattern	Examples
Key-value pairs	`priority:high`, `priority:low`, `env:staging`
Hierarchical paths	`region/apac`, `region/emea`, `team/ops`
Simple labels	`expedited`, `fragile`, `vip`
Identifiers	`customer_abc`, `po_12345`