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

# How It Works

> Understand how Tag History tracks changes and attributes them to users

## Two Ways Changes Are Tracked

Tag History records tag changes through two methods. The method used determines whether the change is attributed to a specific user.

### 1. Webhooks (Automatic)

Shopify sends the app a notification whenever an order, product, or customer is updated. Tag History compares the new tags to the previously recorded state and saves any additions or removals.

* Works automatically in the background — no action needed from your team
* Captures changes made anywhere: Shopify Admin, other apps, bulk edits, API
* Attribution shows as **"Shopify Admin"** because Shopify doesn't tell us which user made the change

### 2. In-App Extension (With Attribution)

When a team member uses the Tag History block on an order, product, or customer page to add or remove a tag, the change is recorded with their name.

* Shows the actual user name in the history timeline
* Supports optional comments to explain why a tag was changed
* The only way to capture user-level attribution

<Info>
  If you want to know *who* made a tag change, use the Tag History extension block rather than Shopify's native tag field. Both result in the same tag being saved on the entity — the difference is attribution.
</Info>

## What Gets Recorded

Every tag change entry stores:

| Field            | Description                                     |
| ---------------- | ----------------------------------------------- |
| **Entity**       | Which order, product, or customer was changed   |
| **Added tags**   | Tags that were added in this change             |
| **Removed tags** | Tags that were removed in this change           |
| **Changed by**   | User name (if via extension) or "Shopify Admin" |
| **Timestamp**    | When the change occurred                        |
| **Comment**      | Optional note explaining the change (Premium)   |

## User Attribution Explained

The "Changed by" field shows who made the change when we can determine it.

<AccordionGroup>
  <Accordion title="Named user (e.g., 'Jane Smith')" icon="user">
    The change was made through the Tag Historian extension block. The user was logged in to Shopify Admin and their identity was captured.
  </Accordion>

  <Accordion title="&#x22;Shopify Admin&#x22;" icon="store">
    The change was detected via webhook — meaning it was made somewhere else (native Shopify tag field, another app, CSV import, API, bulk edit). We know the tag changed but not who changed it.
  </Accordion>
</AccordionGroup>

## Free Plan Usage Limits

On the Free plan, Tag History records up to **30 tag changes per month**. Once the limit is reached:

* New tag changes are **not recorded** until the 1st of next month
* Existing history remains fully accessible
* A warning banner appears in the dashboard and extension blocks
* You can upgrade to Premium at any time for unlimited tracking

<Note>
  The counter resets automatically on the 1st of each month. Upgrading to Premium removes the limit entirely.
</Note>

## Data Retention

Tag history is stored **indefinitely** while the app is installed. There is no automatic expiry.

All data is permanently and immediately deleted when the app is uninstalled.

## Entities Tracked

Tag History tracks tag changes on all three Shopify entity types:

<CardGroup cols={3}>
  <Card title="Orders" icon="bag-shopping">
    Track fulfillment tags, status tags, and any custom order labels
  </Card>

  <Card title="Products" icon="box">
    Monitor product categorisation, collection tags, and merchandising labels
  </Card>

  <Card title="Customers" icon="users">
    Follow loyalty tags, segment tags, and customer lifecycle labels
  </Card>
</CardGroup>

You can enable or disable tracking for each entity type individually from the [Settings](/features/dashboard#tracking-settings) page.