Skip to main content
Whether you use the dashboard or the API, this page explains how Retrac structures your data.

​
Overview

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.
​
id
string
required
The unique ID of the workspace.
​
name
string
required
The name of the workspace.
​
slug
string
required
The slug of the workspace.
The logo of the workspace.
​
usage
number
required
The transfers usage of the workspace.
​
usageLimit
number
required
The usage limit of the workspace.
​
itemsUsage
number
required
The items usage of the workspace.
​
itemsLimit
number
required
The items limit of the workspace.
​
suppliersUsage
number
required
The suppliers usage of the workspace.
​
suppliersLimit
number
required
The suppliers limit of the workspace.
​
storagesLimit
number
required
The storage units limit of the workspace.
​
tagsLimit
number
required
The tags limit of the workspace.
​
usersLimit
number
required
The users limit of the workspace.
​
plan
string
required
The plan of the workspace.
​
stripeId
string | null
required
The Stripe ID of the workspace.
​
billingCycleStart
number
required
The date and time when the billing cycle starts for the workspace.
​
createdAt
string
required
The date and time when the workspace was created.
​
users
object[]
required
The role of the authenticated user in the workspace.

​
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.
FieldPurpose
Item code (SKU)Unique identifier within the workspace
DescriptionHuman-readable name or details
CostUnit cost for reporting
SupplierOptional vendor reference
TagsOptional colored labels for filtering
​
id
string
required
The unique ID of the item.
​
sku
string
required
The code/SKU of the item.
​
description
string
required
The description of the item.
​
quantity
number
required
The quantity of the item.
​
cost
number
required
The cost of the item.
​
tagId
string | null
required
The unique ID of the tag assigned to the item. This field is deprecated – use tags instead.
​
tags
object[] | null
required
The tags assigned to the item.
​
userId
string
required
The user ID of the creator of the item.
​
workspaceId
string
required
The workspace ID of the item.
​
createdAt
string
required
The date and time when the item was created.
​
updatedAt
string
required
The date and time when the item was last updated.
​
projectId
string
required
The project ID of the item. This field is deprecated – use workspaceId instead.

​
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:
TypeMeaning
openingInitial or adjusted on-hand quantity set
transfer_out / transfer_inStock leaving or arriving via a transfer
transfer_revert_out / transfer_revert_inStock restored after a reverted transfer
adjustment_plus / adjustment_minusManual quantity corrections
receipt / issue / returnReserved 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.
​
id
string
required
The unique ID of the tag.
​
name
string
required
The name of the tag.
​
color
string
required
The color of the tag.

​
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 for current limits per plan.