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

# Data model

> How workspaces, items, locations, balances, transfers, and movements relate to each other.

Whether you use the dashboard or the [API](/api-reference/introduction), this page explains how Retrac structures your data.

## Overview

```mermaid theme={null}
flowchart TB
  WS[Workspace] --> Items[Items]
  WS --> Tags[Tags]
  WS --> Loc[Locations]
  Items --> Bal[Inventory balances]
  Loc --> Bal
  Bal --> Mov[Movements ledger]
  WS --> Trf[Transfers]
  Trf --> Mov
```

Everything belongs to a **workspace**. Within a workspace you define **items** (your product catalog), **locations** (where stock lives), and **tags** (optional organization). **Inventory balances** store the current on-hand quantity for each item at each location. Every change to stock creates an **inventory movement** — an append-only audit record.

## Workspaces

A workspace is your company's inventory environment: one catalog, one team, one billing plan, and one set of usage limits.

* Each person can belong to multiple workspaces (e.g. separate businesses or departments).
* The workspace **slug** appears in your dashboard URL: `app.retrac.co/{slug}/inventory`.
* Find the workspace **ID** under **Settings → General** when using the API.

<Accordion title="Workspace fields (API)">
  <ResponseField name="id" type="string" required>
    The unique ID of the workspace.
  </ResponseField>

  <ResponseField name="name" type="string" required>
    The name of the workspace.
  </ResponseField>

  <ResponseField name="slug" type="string" required>
    The slug of the workspace.
  </ResponseField>

  <ResponseField name="logo" type="string | null" required>
    The logo of the workspace.
  </ResponseField>

  <ResponseField name="usage" type="number" required>
    The transfers usage of the workspace.
  </ResponseField>

  <ResponseField name="usageLimit" type="number" required>
    The usage limit of the workspace.
  </ResponseField>

  <ResponseField name="itemsUsage" type="number" required>
    The items usage of the workspace.
  </ResponseField>

  <ResponseField name="itemsLimit" type="number" required>
    The items limit of the workspace.
  </ResponseField>

  <ResponseField name="suppliersUsage" type="number" required>
    The suppliers usage of the workspace.
  </ResponseField>

  <ResponseField name="suppliersLimit" type="number" required>
    The suppliers limit of the workspace.
  </ResponseField>

  <ResponseField name="storagesLimit" type="number" required>
    The storage units limit of the workspace.
  </ResponseField>

  <ResponseField name="tagsLimit" type="number" required>
    The tags limit of the workspace.
  </ResponseField>

  <ResponseField name="usersLimit" type="number" required>
    The users limit of the workspace.
  </ResponseField>

  <ResponseField name="plan" type="string" required>
    The plan of the workspace.
  </ResponseField>

  <ResponseField name="stripeId" type="string | null" required>
    The Stripe ID of the workspace.
  </ResponseField>

  <ResponseField name="billingCycleStart" type="number" required>
    The date and time when the billing cycle starts for the workspace.
  </ResponseField>

  <ResponseField name="createdAt" type="string" required>
    The date and time when the workspace was created.
  </ResponseField>

  <ResponseField name="users" type="object[]" required>
    The role of the authenticated user in the workspace.

    <Expandable title="properties">
      <ResponseField name="users.role" type="string" required>
        The role of the authenticated user in the workspace.
      </ResponseField>
    </Expandable>
  </ResponseField>
</Accordion>

## Items

An item is a product or SKU in your catalog. Items are **not** tied to a single quantity — stock is tracked per location via balances.

| Field               | Purpose                                |
| ------------------- | -------------------------------------- |
| **Item code (SKU)** | Unique identifier within the workspace |
| **Description**     | Human-readable name or details         |
| **Cost**            | Unit cost for reporting                |
| **Supplier**        | Optional vendor reference              |
| **Tags**            | Optional colored labels for filtering  |

<Accordion title="Item fields (API)">
  <ResponseField name="id" type="string" required>
    The unique ID of the item.
  </ResponseField>

  <ResponseField name="sku" type="string" required>
    The code/SKU of the item.
  </ResponseField>

  <ResponseField name="description" type="string" required>
    The description of the item.
  </ResponseField>

  <ResponseField name="quantity" type="number" required>
    The quantity of the item.
  </ResponseField>

  <ResponseField name="cost" type="number" required>
    The cost of the item.
  </ResponseField>

  <ResponseField name="tagId" type="string | null" required>
    The unique ID of the tag assigned to the item. This field is deprecated
    – use `tags` instead.
  </ResponseField>

  <ResponseField name="tags" type="object[] | null" required>
    The tags assigned to the item.

    <Expandable title="properties">
      <ResponseField name="tags.id" type="string" required>
        The unique ID of the tag.
      </ResponseField>

      <ResponseField name="tags.name" type="string" required>
        The name of the tag.
      </ResponseField>

      <ResponseField name="tags.color" type="string" required>
        The color of the tag.
      </ResponseField>
    </Expandable>
  </ResponseField>

  <ResponseField name="userId" type="string" required>
    The user ID of the creator of the item.
  </ResponseField>

  <ResponseField name="workspaceId" type="string" required>
    The workspace ID of the item.
  </ResponseField>

  <ResponseField name="createdAt" type="string" required>
    The date and time when the item was created.
  </ResponseField>

  <ResponseField name="updatedAt" type="string" required>
    The date and time when the item was last updated.
  </ResponseField>

  <ResponseField name="projectId" type="string" required>
    The project ID of the item. This field is deprecated – use `workspaceId`
    instead.
  </ResponseField>
</Accordion>

## Locations

Locations represent physical or logical places where stock is held:

* **Warehouse** — main storage
* **Van / Truck** — mobile stock
* **Site** — job site or retail floor
* **Other** — anything else

Each workspace has a **default location** (created automatically as "Inventory"). New items can receive opening stock at the location you have selected on the inventory page.

## Inventory balances

The balance for an item at a location is the **on-hand quantity** right now. Balances change when you:

* Set opening stock or **adjust stock**
* Complete a **transfer** (out from source, in at destination)
* **Revert** a transfer (owner only)

Balances are always derived from the movement ledger — you cannot edit history, only add new movements.

## Transfers

A transfer moves quantity from one location to another. In Retrac, transfers are **instant**: when you create a transfer, stock moves immediately and the transfer is marked **completed**.

* A transfer has one source and one destination location.
* It can include multiple line items, each with its own quantity.
* **Workspace owners** can revert a completed transfer, which restores stock and writes reversal movements.

## Movements (audit ledger)

Every stock change creates a movement record. Movement types include:

| Type                                         | Meaning                                  |
| -------------------------------------------- | ---------------------------------------- |
| `opening`                                    | Initial or adjusted on-hand quantity set |
| `transfer_out` / `transfer_in`               | Stock leaving or arriving via a transfer |
| `transfer_revert_out` / `transfer_revert_in` | Stock restored after a reverted transfer |
| `adjustment_plus` / `adjustment_minus`       | Manual quantity corrections              |
| `receipt` / `issue` / `return`               | Reserved for future flows                |

View movements under **Inventory → Movements**. They are read-only.

## Tags

Tags are workspace-scoped labels with a name and color. Assign one or more tags to an item to filter the inventory list.

<Accordion title="Tag fields (API)">
  <ResponseField name="id" type="string" required>
    The unique ID of the tag.
  </ResponseField>

  <ResponseField name="name" type="string" required>
    The name of the tag.
  </ResponseField>

  <ResponseField name="color" type="string" required>
    The color of the tag.
  </ResponseField>
</Accordion>

## Usage limits

Plans enforce limits on:

* **Total items** — cumulative count; does not reset monthly
* **Transfers** — counted per billing cycle
* **Locations, tags, and users** — workspace caps

See [Billing & plans](/dashboard/billing/introduction) for current limits per plan.