> ## 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

# Inventory Management

> Learn how to track stock levels using the Trackstar API

Effective inventory management is crucial for maintaining optimal stock levels and preventing stockouts or overstock situations. This guide shows you how to fetch inventory data and make adjustments using the Trackstar API.

## Overview

The inventory management workflow typically involves:

1. Fetching current stock levels across warehouses
2. Monitoring inventory changes and levels
3. Map between products and associated inventory items

## Getting Inventory Data

Use the [Get Inventory endpoint](/api-reference/wms-api/inventory/get) to retrieve current stock levels across all locations.

### Fetching All Inventory

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://production.trackstarhq.com/wms/inventory \
    -H "x-trackstar-api-key: YOUR_API_KEY" \
    -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
  ```

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

  url = "https://production.trackstarhq.com/wms/inventory"

  headers = {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN",
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/wms/inventory";

  fetch(url, {
    method: "GET",
    headers: {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    }
  })
  .then(response => response.json())
  .then(data => console.log(data));
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://production.trackstarhq.com/wms/inventory";

  $options = [
    "http" => [
      "header" =>
        "x-trackstar-api-key: YOUR_API_KEY\r\n" .
        "x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
      "method" => "GET"
    ]
  ];

  $context = stream_context_create($options);
  $response = file_get_contents($url, false, $context);
  echo $response;
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    url := "https://production.trackstarhq.com/wms/inventory"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
    req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
      panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class TrackstarGetInventoryExample {
    public static void main(String[] args) throws IOException, InterruptedException {
      String url = "https://production.trackstarhq.com/wms/inventory";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-trackstar-api-key", "YOUR_API_KEY")
        .header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Status: " + response.statusCode());
      System.out.println("Body: " + response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  url = URI('https://production.trackstarhq.com/wms/inventory')

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request['x-trackstar-api-key'] = 'YOUR_API_KEY'
  request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'

  response = http.request(request)
  puts "Status: #{response.code}"
  puts "Response: #{response.body}"
  ```
</CodeGroup>

### Sample Response

```json theme={null}
{
  "data": [
    {
      "id": "inv_widget001_main",
      "warehouse_customer_id": "customer_12345",
      "created_date": "2024-01-15T10:00:00Z",
      "updated_date": "2024-01-20T14:30:00Z",
      "name": "Premium Widget",
      "sku": "WIDGET-001",
      "unit_cost": 25.00,
      "active": true,
      "awaiting": 100,
      "onhand": 150,
      "committed": 25,
      "unfulfillable": 5,
      "fulfillable": 120,
      "unsellable": 0,
      "sellable": 150,
      "substitute_skus": [],
      "inventory_by_warehouse_id": {
        "warehouse_main": {
          "onhand": 100,
          "committed": 15,
          "unfulfillable": 3,
          "fulfillable": 82,
          "unsellable": 0,
          "sellable": 100,
          "awaiting": 50
        },
        "warehouse_east": {
          "onhand": 50,
          "committed": 10,
          "unfulfillable": 2,
          "fulfillable": 38,
          "unsellable": 0,
          "sellable": 50,
          "awaiting": 50
        }
      },
      "lots": [
        {
          "lot_id": "LOT-W001-240115",
          "onhand": 75,
          "expiration_date": "2025-01-15"
        }
      ],
      "locations": [
        {
          "location_id": "A-01-15-02",
          "warehouse_id": "warehouse_main",
          "quantity": 75
        },
        {
          "location_id": "B-02-08-01",
          "warehouse_id": "warehouse_main",
          "quantity": 25
        }
      ],
      "trackstar_tags": ["high-priority", {"category": "fast-mover"}],
      "external_system_url": "https://wms.example.com/inventory/inv_widget001_main",
      "additional_fields": {
        "custom_field_1": "value1",
        "warehouse_notes": "Premium product location"
      },
      "measurements": {
        "length": 12.5,
        "width": 8.0,
        "height": 4.2,
        "unit": "in",
        "weight": 2.3,
        "weight_unit": "lb"
      }
    },
    {
      "id": "inv_gadget002_main",
      "warehouse_customer_id": "customer_12345",
      "created_date": "2024-01-10T09:00:00Z",
      "updated_date": "2024-01-18T16:45:00Z",
      "name": "Smart Gadget",
      "sku": "GADGET-002",
      "unit_cost": 45.00,
      "active": true,
      "awaiting": 25,
      "onhand": 75,
      "committed": 10,
      "unfulfillable": 0,
      "fulfillable": 65,
      "unsellable": 0,
      "sellable": 75,
      "substitute_skus": ["GADGET-002A"],
      "inventory_by_warehouse_id": {
        "warehouse_main": {
          "onhand": 75,
          "committed": 10,
          "unfulfillable": 0,
          "fulfillable": 65,
          "unsellable": 0,
          "sellable": 75,
          "awaiting": 25
        }
      },
      "lots": [],
      "locations": [
        {
          "location_id": "C-03-12-01",
          "warehouse_id": "warehouse_main",
          "quantity": 75
        }
      ],
      "trackstar_tags": ["smart-device"],
      "external_system_url": "https://wms.example.com/inventory/inv_gadget002_main",
      "additional_fields": {
        "electronics_category": "consumer",
        "warehouse_notes": "Electronics section"
      },
      "measurements": {
        "length": 6.8,
        "width": 3.4,
        "height": 1.8,
        "unit": "in",
        "weight": 0.8,
        "weight_unit": "lb"
      }
    }
  ],
  "next_token": null,
  "total_count": 2
}
```

## Understanding Inventory Levels

For detailed information about inventory breakdowns, see the [Inventory Info page](/api-reference/wms-api/inventory/info).

## Multi-Location Inventory

Trackstar tracks inventory across multiple warehouses and specific locations within each warehouse.

### Warehouse-Level Inventory

Each inventory item shows totals by warehouse:

```json theme={null}
{
  "inventory_by_warehouse_id": {
    "warehouse_main": {
      "onhand": 100,
      "committed": 15,
      "fulfillable": 85
    },
    "warehouse_east": {
      "onhand": 50,
      "committed": 10,
      "fulfillable": 40
    }
  }
}
```

### Location-Level Details

Specific storage locations within warehouses:

```json theme={null}
{
  "locations": [
    {
      "location_id": "A-01-15-02",
      "warehouse_id": "warehouse_main",
      "quantity": 75
    },
    {
      "location_id": "B-02-08-01",
      "warehouse_id": "warehouse_main",
      "quantity": 25
    }
  ]
}
```

## Mapping Products to Inventory Items

Products and inventory items have a many-to-many relationship in Trackstar. A single product (identified by SKU) can map to multiple inventory items across different warehouses. To accurately get inventory levels for a product, you need to first fetch the product to get its associated inventory items.

### Fetching Product Information

Use the [Get Product endpoint](/api-reference/wms-api/products/get-item) to retrieve a specific product and its inventory item mappings.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://production.trackstarhq.com/wms/products/prod_widget_001 \
    -H "x-trackstar-api-key: YOUR_API_KEY" \
    -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
  ```

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

  url = "https://production.trackstarhq.com/wms/products/prod_widget_001"

  headers = {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/wms/products/prod_widget_001";

  fetch(url, {
    method: "GET",
    headers: {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    }
  })
  .then(response => response.json())
  .then(data => console.log(data));
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://production.trackstarhq.com/wms/products/prod_widget_001";

  $options = [
    "http" => [
      "header" =>
        "x-trackstar-api-key: YOUR_API_KEY\r\n" .
        "x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
      "method" => "GET"
    ]
  ];

  $context = stream_context_create($options);
  $response = file_get_contents($url, false, $context);
  echo $response;
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    url := "https://production.trackstarhq.com/wms/products/prod_widget_001"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
    req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
      panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class TrackstarGetProductExample {
    public static void main(String[] args) throws IOException, InterruptedException {
      String url = "https://production.trackstarhq.com/wms/products/prod_widget_001";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-trackstar-api-key", "YOUR_API_KEY")
        .header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Status: " + response.statusCode());
      System.out.println("Body: " + response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  url = URI('https://production.trackstarhq.com/wms/products/prod_widget_001')

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request['x-trackstar-api-key'] = 'YOUR_API_KEY'
  request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'

  response = http.request(request)
  puts "Status: #{response.code}"
  puts "Response: #{response.body}"
  ```
</CodeGroup>

### Sample Product Response

```json theme={null}
{
  "data": {
    "id": "prod_widget_001",
    "warehouse_customer_id": "customer_12345",
    "created_date": "2024-01-01T00:00:00Z",
    "updated_date": "2024-01-15T10:30:00Z",
    "name": "Premium Widget",
    "sku": "WIDGET-001",
    "gtin": "1234567890123",
    "unit_price": 29.99,
    "inventory_items": [
      {
        "inventory_item_id": "inv_widget001_main",
        "sku": "WIDGET-001",
        "unit_quantity": 1
      },
      {
        "inventory_item_id": "inv_widget001_east",
        "sku": "WIDGET-001",
        "unit_quantity": 1
      }
    ],
    "is_kit": false,
    "active": true,
    "supplier": "ACME Suppliers",
    "supplier_object": {
      "supplier_id": "ACME001",
      "supplier_name": "ACME Suppliers Inc"
    },
    "country_of_origin": "US",
    "harmonized_code": "9999999999",
    "supplier_products": [
      {
        "supplier_id": "ACME001",
        "supplier_name": "ACME Suppliers Inc",
        "external_id": "ACME-WIDGET-001",
        "unit_cost": "25.00"
      }
    ],
    "trackstar_tags": ["premium", {"priority": "high"}],
    "external_system_url": "https://wms.example.com/products/prod_widget_001",
    "additional_fields": {
      "product_category": "widgets",
      "marketing_description": "Our best-selling premium widget"
    }
  }
}
```

### Getting Inventory Levels for Products

Once you have the `inventory_item_id` values from the product response, use the [Get Inventory endpoint](/api-reference/wms-api/inventory/get) to retrieve current stock levels. The `inventory_item_id` from the product endpoint maps directly to the `id` field in the inventory endpoint.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://production.trackstarhq.com/wms/inventory/inv_widget001_main \
    -H "x-trackstar-api-key: YOUR_API_KEY" \
    -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN"
  ```

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

  url = "https://production.trackstarhq.com/wms/inventory/inv_widget001_main"

  headers = {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN",
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/wms/inventory/inv_widget001_main";

  fetch(url, {
    method: "GET",
    headers: {
    "x-trackstar-api-key": "YOUR_API_KEY",
    "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    }
  })
  .then(response => response.json())
  .then(data => console.log(data));
  ```

  ```php PHP theme={null}
  <?php
  $url = "https://production.trackstarhq.com/wms/inventory/inv_widget001_main";

  $options = [
    "http" => [
      "header" =>
        "x-trackstar-api-key: YOUR_API_KEY\r\n" .
        "x-trackstar-access-token: YOUR_ACCESS_TOKEN\r\n",
      "method" => "GET"
    ]
  ];

  $context = stream_context_create($options);
  $response = file_get_contents($url, false, $context);
  echo $response;
  ?>
  ```

  ```go Go theme={null}
  package main

  import (
    "fmt"
    "io"
    "net/http"
  )

  func main() {
    url := "https://production.trackstarhq.com/wms/inventory/inv_widget001_main"

    req, _ := http.NewRequest("GET", url, nil)
    req.Header.Set("x-trackstar-api-key", "YOUR_API_KEY")
    req.Header.Set("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")

    client := &http.Client{}
    resp, err := client.Do(req)
    if err != nil {
      panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
  }
  ```

  ```java Java theme={null}
  import java.io.IOException;
  import java.net.URI;
  import java.net.http.HttpClient;
  import java.net.http.HttpRequest;
  import java.net.http.HttpResponse;

  public class TrackstarGetInventoryItemExample {
    public static void main(String[] args) throws IOException, InterruptedException {
      String url = "https://production.trackstarhq.com/wms/inventory/inv_widget001_main";

      HttpClient client = HttpClient.newHttpClient();
      HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(url))
        .header("x-trackstar-api-key", "YOUR_API_KEY")
        .header("x-trackstar-access-token", "YOUR_ACCESS_TOKEN")
        .GET()
        .build();

      HttpResponse<String> response = client.send(request, HttpResponse.BodyHandlers.ofString());
      System.out.println("Status: " + response.statusCode());
      System.out.println("Body: " + response.body());
    }
  }
  ```

  ```ruby Ruby theme={null}
  require 'net/http'
  require 'uri'

  url = URI('https://production.trackstarhq.com/wms/inventory/inv_widget001_main')

  http = Net::HTTP.new(url.host, url.port)
  http.use_ssl = true

  request = Net::HTTP::Get.new(url)
  request['x-trackstar-api-key'] = 'YOUR_API_KEY'
  request['x-trackstar-access-token'] = 'YOUR_ACCESS_TOKEN'

  response = http.request(request)
  puts "Status: #{response.code}"
  puts "Response: #{response.body}"
  ```
</CodeGroup>

### Sample Inventory Item Response

```json theme={null}
{
  "data": {
    "id": "inv_widget001_main",
    "warehouse_customer_id": "customer_12345",
    "created_date": "2024-01-15T10:00:00Z",
    "updated_date": "2024-01-20T14:30:00Z",
    "name": "Premium Widget",
    "sku": "WIDGET-001",
    "unit_cost": 25.00,
    "active": true,
    "awaiting": 50,
    "onhand": 100,
    "committed": 15,
    "unfulfillable": 3,
    "fulfillable": 82,
    "unsellable": 0,
    "sellable": 100,
    "substitute_skus": [],
    "inventory_by_warehouse_id": {
      "warehouse_main": {
        "onhand": 100,
        "committed": 15,
        "unfulfillable": 3,
        "fulfillable": 82,
        "unsellable": 0,
        "sellable": 100,
        "awaiting": 50
      }
    },
    "lots": [
      {
        "lot_id": "LOT-W001-240115",
        "onhand": 75,
        "expiration_date": "2025-01-15"
      }
    ],
    "locations": [
      {
        "location_id": "A-01-15-02",
        "warehouse_id": "warehouse_main",
        "quantity": 75
      },
      {
        "location_id": "B-02-08-01",
        "warehouse_id": "warehouse_main",
        "quantity": 25
      }
    ],
    "trackstar_tags": ["high-priority", {"category": "fast-mover"}],
    "external_system_url": "https://wms.example.com/inventory/inv_widget001_main",
    "additional_fields": {
      "custom_field_1": "value1",
      "warehouse_notes": "Premium product location"
    },
    "measurements": {
      "length": 12.5,
      "width": 8.0,
      "height": 4.2,
      "unit": "in",
      "weight": 2.3,
      "weight_unit": "lb"
    }
  }
}
```

### Complete Product-to-Inventory Workflow

1. **Fetch the product** using the [Get Product endpoint](/api-reference/wms-api/products/get-item)
2. **Extract inventory item IDs** from the `inventory_items` array
3. **Fetch inventory levels** for each `inventory_item_id` using the [Get Inventory Item endpoint](/api-reference/wms-api/inventory/get-item)


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