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

> ## Agent Instructions
> Trackstar is a unified REST API for WMS, cart, and carrier systems. Base URL: https://production.trackstarhq.com. There is no SDK; call the API with plain HTTP.
> Send x-trackstar-api-key on every request. Endpoints scoped to one connection also need x-trackstar-access-token. Read both from environment variables and never print them.
> Reads return data Trackstar has already synced from the connected system. Writes (POST, PUT, PATCH, DELETE) are forwarded to the connected system immediately.
> A new connection has no data until its initial sync finishes. Wait for the connection.historical-sync-completed webhook, or poll GET /connections/{connection_id} and check historical_sync_completed.
> List endpoints page with page_token and next_token (limit is capped at 1000). Repeat every filter on every page. Filters use field[operator]=value, for example created_date[gte]=2026-01-01T00:00:00Z.
> Write bodies must not contain null or empty strings; omit the field instead. Call GET /integrations/{integration_type}/{integration_name}/write-info first to learn the exact fields an integration accepts.
> To test without real credentials, POST /sandbox/generate-sandbox/{wms|cart|carrier} with the API key returns a sandbox access token. Start at https://docs.trackstarhq.com/how-to-guides/build-with-ai.md and install the skills with: npx skills add https://docs.trackstarhq.com

# Trackstar Tags

> Tagging objects in Trackstar

Trackstar allows you to tag objects with custom metadata that isn't synced into the underlying integration. This is useful for
adding fields that don't fit into the integration's schema, or for adding additional context to objects.

Tags are supported across WMS, Cart, and Carrier integrations.

## The Trackstar Tag Object

A tag can be either a string or a dictionary with one key-value pair. e.g.

* A string: `"tag1"`
* A dictionary: `{"tag1": "value1"}`

## Setting Tags

To create a tag, make a `PUT` request to `/{integration_type}/{object_type}/{object_id}/trackstar-tags`. The request body includes a list of tags to add to the object.

*Note, because this is a `PUT` request, the tags will be replaced with the new list.*

### Supported Endpoints

| Integration | Endpoint |
| :- | :- |
| WMS | `/wms/inventory/{inventory_id}/trackstar-tags` |
| WMS | `/wms/products/{product_id}/trackstar-tags` |
| WMS | `/wms/orders/{order_id}/trackstar-tags` |
| WMS | `/wms/inbound-shipments/{inbound_shipment_id}/trackstar-tags` |
| WMS | `/wms/returns/{return_id}/trackstar-tags` |
| WMS | `/wms/warehouses/{warehouse_id}/trackstar-tags` |
| Cart | `/cart/orders/{order_id}/trackstar-tags` |
| Cart | `/cart/products/{product_id}/trackstar-tags` |
| Cart | `/cart/warehouses/{warehouse_id}/trackstar-tags` |
| Carrier | `/carrier/invoice-line-items/{invoice_line_item_id}/trackstar-tags` |

### Example

<CodeGroup>
  ```bash cURL theme={null}

  curl --request PUT \
    --url https://production.trackstarhq.com/cart/orders/{order_id}/trackstar-tags \
    --header 'Content-Type: application/json' \
    --header 'x-trackstar-access-token: <x-trackstar-access-token>' \
    --header 'x-trackstar-api-key: <x-trackstar-api-key>' \
    --data '{
    "trackstar_tags": [
      "tag1",
      "tag2",
      {
        "tag3": "value3"
      }
    ]
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://production.trackstarhq.com/cart/orders/{order_id}/trackstar-tags"

  payload = {"trackstar_tags": ["tag1", "tag2", {"tag3": "value3"}]}
  headers = {
      "x-trackstar-api-key": "<x-trackstar-api-key>",
      "x-trackstar-access-token": "<x-trackstar-access-token>",
      "Content-Type": "application/json"
  }

  response = requests.request("PUT", url, json=payload, headers=headers)
  ```
</CodeGroup>

## Getting Tags

Once you've added tags to an object, they will be returned in the `trackstar_tags` field of the object's response from any `GET` request.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.