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

# Cart Order Fulfillment

> Sync products, pull orders, create shipments, and adjust inventory using the Cart API

This guide covers the end-to-end workflow for managing orders from cart platforms (e.g. Shopify, Amazon, Etsy) using the Trackstar Cart API.

## Overview

The cart order fulfillment workflow typically involves:

1. Syncing your product catalog
2. Pulling in orders as they arrive
3. Pushing back shipment and tracking information after fulfillment
4. Adjusting inventory levels in the cart platform

## 1. Sync Products

Use the [Get Products endpoint](/api-reference/cart-api/products/get) to pull the product catalog from your customer's cart platform.

<Tip>
  Every variant and parent product are listed in this endpoint. A variant will have a `parent_product_id` pointing to its parent. Parent products are indicated by having their `parent_product_id` set to the same value as their `id`. The source of truth for price and inventory levels is on the variants, not the parent product.
</Tip>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET https://production.trackstarhq.com/cart/products \
    -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/cart/products"

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

  response = requests.get(url, headers=headers)
  data = response.json()

  for product in data["data"]:
      is_variant = product["parent_product_id"] != product["id"]
      print(f"{product['name']} (SKU: {product['sku']}, variant: {is_variant})")
  ```

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

  const response = await fetch(url, {
    headers: {
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    }
  });

  const { data } = await response.json();

  for (const product of data) {
    const isVariant = product.parent_product_id !== product.id;
    console.log(`${product.name} (SKU: ${product.sku}, variant: ${isVariant})`);
  }
  ```
</CodeGroup>

## 2. Pull Orders

Use the [Get Orders endpoint](/api-reference/cart-api/orders/get) to pull orders as they come in. You can filter by date to get only recent orders.

For real-time notifications, subscribe to the `cart-order.created` [webhook](/how-to-guides/webhooks) event.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://production.trackstarhq.com/cart/orders?created_date[gte]=2026-04-01T00:00:00Z" \
    -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/cart/orders"

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

  params = {
      "created_date[gte]": "2026-04-01T00:00:00Z"
  }

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

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/cart/orders?created_date[gte]=2026-04-01T00:00:00Z";

  const response = await fetch(url, {
    headers: {
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    }
  });

  const orders = await response.json();
  ```
</CodeGroup>

### Order Statuses

| Status | Definition |
| :- | :- |
| `open` | Order has been placed. |
| `confirmed` | Order has been confirmed by the cart system. |
| `processing` | Order is being processed by the warehouse. |
| `partially_fulfilled` | Order has been partially fulfilled. |
| `fulfilled` | Order has been fulfilled and shipped. |
| `backordered` | Order cannot be fulfilled due to lack of inventory. |
| `exception` | There is an issue with the order. |
| `cancelled` | Order has been cancelled. |

## 3. Create Order Shipment

After fulfilling an order, use the [Create Shipment endpoint](/api-reference/cart-api/orders/create-shipment) to push tracking information back to the cart platform.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://production.trackstarhq.com/cart/orders/ORDER_ID/shipments \
    -H "Content-Type: application/json" \
    -H "x-trackstar-api-key: YOUR_API_KEY" \
    -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
    -d '{
      "tracking_number": "1Z999AA1234567890",
      "tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
      "carrier_name": "FedEx",
      "shipping_method_name": "FedEx Ground"
    }'
  ```

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

  url = "https://production.trackstarhq.com/cart/orders/ORDER_ID/shipments"

  headers = {
      "Content-Type": "application/json",
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }

  payload = {
      "tracking_number": "1Z999AA1234567890",
      "tracking_url": "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
      "carrier_name": "FedEx",
      "shipping_method_name": "FedEx Ground"
  }

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

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/cart/orders/ORDER_ID/shipments";

  const response = await fetch(url, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    },
    body: JSON.stringify({
      tracking_number: "1Z999AA1234567890",
      tracking_url: "https://www.fedex.com/apps/fedextrack/?tracknumbers=1Z999AA1234567890",
      carrier_name: "FedEx",
      shipping_method_name: "FedEx Ground"
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## 4. Adjust Inventory

Use the [Adjust Inventory endpoint](/api-reference/cart-api/products/adjust) to update inventory levels in the cart platform. This is useful for syncing stock changes that happen outside the cart (e.g. warehouse adjustments, returns processing).

The `adjustment_type` field controls how the `quantity` value is applied:

* `"increase"` — add to the current stock level
* `"decrease"` — subtract from the current stock level
* `"exact"` — set the stock level to this exact quantity

<Note>
  Inventory can only be adjusted on variant products, not parent products. Use the `parent_product_id` field to identify variants (see Step 1).
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://production.trackstarhq.com/cart/products/PRODUCT_ID/adjust-inventory \
    -H "Content-Type: application/json" \
    -H "x-trackstar-api-key: YOUR_API_KEY" \
    -H "x-trackstar-access-token: YOUR_ACCESS_TOKEN" \
    -d '{
      "quantity": 50,
      "adjustment_type": "exact",
      "warehouse_id": "warehouse_main"
    }'
  ```

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

  url = "https://production.trackstarhq.com/cart/products/PRODUCT_ID/adjust-inventory"

  headers = {
      "Content-Type": "application/json",
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
  }

  payload = {
      "quantity": 50,
      "adjustment_type": "exact",
      "warehouse_id": "warehouse_main"
  }

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

  ```javascript JavaScript theme={null}
  const url = "https://production.trackstarhq.com/cart/products/PRODUCT_ID/adjust-inventory";

  const response = await fetch(url, {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      "x-trackstar-api-key": "YOUR_API_KEY",
      "x-trackstar-access-token": "YOUR_ACCESS_TOKEN"
    },
    body: JSON.stringify({
      quantity: 50,
      adjustment_type: "exact",
      warehouse_id: "warehouse_main"
    })
  });

  const data = await response.json();
  console.log(data);
  ```
</CodeGroup>

## Real-Time Updates

Use [webhooks](/how-to-guides/webhooks) to get notified in real time:

| Event | Description |
| :- | :- |
| `cart-order.created` | A new order has been placed. |
| `cart-order.updated` | An order has been updated (status change, etc.). |
| `cart-order.shipment.created` | A shipment has been created for an order. |
| `cart-product.created` | A new product has been added to the catalog. |
| `cart-product.updated` | A product has been updated (price, inventory, etc.). |


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