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

# Eaglecart Inventory API: Track & Adjust Stock Levels

> Full reference for the Eaglecart Inventory API — query stock levels, update quantities, and create auditable stock adjustments with examples.

The Inventory API gives you real-time visibility into stock levels across all your locations, and lets you update quantities and record stock movements programmatically. Use it to sync inventory from warehouse management systems, trigger reorder workflows when stock runs low, or reconcile counts after physical stock takes.

> [!WARNING]
>
> Inventory adjustments are permanent and cannot be undone through the API. Every adjustment is written to the store's audit log with a timestamp, the user or API key that made the change, and the reason you provide. Review adjustments carefully before submitting them.

> [!TIP]
>
> Query `GET /inventory?low_stock=true` to retrieve only variants whose inventory has fallen below your configured reorder threshold. Subscribe a webhook to this query pattern or poll it on a schedule to build automated reorder alerts without scanning your entire catalog.

***

## The Inventory Level Object

**variant\_id** `string`

The ID of the product variant this inventory record belongs to.

**sku** `string`

The SKU of the variant.

**location\_id** `string`

The ID of the location (warehouse, store, or fulfillment center) holding this stock.

**location\_name** `string`

Human-readable name of the location.

**quantity** `integer`

Current on-hand quantity at this location.

**reserved\_quantity** `integer`

Quantity reserved for open, unfulfilled orders at this location.

**available\_quantity** `integer`

Quantity available for new orders (`quantity` minus `reserved_quantity`).

**updated\_at** `string`

ISO 8601 timestamp of the last inventory update for this record.

***

## List Inventory Levels

Retrieve inventory levels across all variants and locations. Use filters to narrow results to a specific location, SKU, or low-stock items.

`GET /inventory`

**location\_id** `string`

Filter results to inventory held at this location ID only.

**sku** `string`

Filter to the variant with this exact SKU value.

**low\_stock** `boolean`

Set to `true` to return only variants whose available quantity is at or below your store's configured reorder threshold.

**limit** `integer`

Number of records to return per page. Defaults to `20`. Maximum is `100`.

**page** `integer`

Page number to retrieve. Defaults to `1`.

```bash cURL theme={null}
curl "https://api.eaglecart.com/v1/inventory?location_id=loc_01HWRH001&low_stock=true" \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/inventory?location_id=loc_01HWRH001&low_stock=true',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const data = await response.json();
```

```json Response theme={null}
{
  "data": [
    {
      "variant_id": "var_01HDEF789",
      "sku": "TEE-M-BLK",
      "location_id": "loc_01HWRH001",
      "location_name": "Main Warehouse",
      "quantity": 5,
      "reserved_quantity": 3,
      "available_quantity": 2,
      "updated_at": "2024-06-11T08:00:00Z"
    }
  ],
  "meta": { "page": 1, "limit": 20, "total": 1 }
}
```

***

## Get Inventory for a Variant

Retrieve inventory levels for a single variant across all locations.

`GET /inventory/:variant_id`

**variant\_id** `string` *required*

The unique ID of the product variant.

```bash cURL theme={null}
curl https://api.eaglecart.com/v1/inventory/var_01HDEF789 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx"
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/inventory/var_01HDEF789',
  { headers: { 'Authorization': 'Bearer ec_live_xxxxxxxxxxxx' } }
);
const inventory = await response.json();
```

```json Response theme={null}
{
  "variant_id": "var_01HDEF789",
  "sku": "TEE-M-BLK",
  "locations": [
    {
      "location_id": "loc_01HWRH001",
      "location_name": "Main Warehouse",
      "quantity": 5,
      "reserved_quantity": 3,
      "available_quantity": 2,
      "updated_at": "2024-06-11T08:00:00Z"
    },
    {
      "location_id": "loc_01HWRH002",
      "location_name": "East Fulfilment Center",
      "quantity": 18,
      "reserved_quantity": 0,
      "available_quantity": 18,
      "updated_at": "2024-06-10T16:45:00Z"
    }
  ]
}
```

***

## Update Inventory Quantity

Set the on-hand quantity for a variant at a specific location. Use this to sync a verified count from your warehouse system. This call sets an absolute quantity — use the `POST /inventory/adjust` endpoint if you need to record a relative delta with a reason.

`PATCH /inventory/:variant_id`

**variant\_id** `string` *required*

The unique ID of the variant whose inventory you are updating.

**location\_id** `string` *required*

The ID of the location at which to update the quantity.

**quantity** `integer` *required*

The new absolute on-hand quantity. Must be zero or greater.

```bash cURL theme={null}
curl -X PATCH https://api.eaglecart.com/v1/inventory/var_01HDEF789 \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc_01HWRH001",
    "quantity": 50
  }'
```

```javascript JavaScript theme={null}
const response = await fetch(
  'https://api.eaglecart.com/v1/inventory/var_01HDEF789',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      location_id: 'loc_01HWRH001',
      quantity: 50
    })
  }
);
const updated = await response.json();
```

```json Response theme={null}
{
  "variant_id": "var_01HDEF789",
  "sku": "TEE-M-BLK",
  "location_id": "loc_01HWRH001",
  "location_name": "Main Warehouse",
  "quantity": 50,
  "reserved_quantity": 3,
  "available_quantity": 47,
  "updated_at": "2024-06-11T16:00:00Z"
}
```

***

## Create a Stock Adjustment

Record one or more relative inventory movements at a location. Each item in the adjustment specifies a `variant_id`, a `delta` (positive to add stock, negative to remove it), and a `reason`. All items in the request are applied atomically.

`POST /inventory/adjust`

**location\_id** `string` *required*

The ID of the location where the stock movement occurred.

**items** `array` *required*

An array of stock movement objects. Each item must include `variant_id`, `delta`, and `reason`.

**item fields**

**variant\_id** `string` *required*

The ID of the variant being adjusted.

**delta** `integer` *required*

The quantity change to apply. Use a positive number to add stock and a negative number to remove it.

**reason** `string` *required*

A human-readable reason for the adjustment (e.g. `Damaged goods`, `Supplier delivery`, `Stock take correction`). This is stored permanently in the audit log.

```bash cURL theme={null}
curl -X POST https://api.eaglecart.com/v1/inventory/adjust \
  -H "Authorization: Bearer ec_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "location_id": "loc_01HWRH001",
    "items": [
      {
        "variant_id": "var_01HDEF789",
        "delta": 20,
        "reason": "Supplier delivery — PO-2024-089"
      },
      {
        "variant_id": "var_01HDEF790",
        "delta": -3,
        "reason": "Damaged goods removed from stock"
      }
    ]
  }'
```

```javascript JavaScript theme={null}
const response = await fetch('https://api.eaglecart.com/v1/inventory/adjust', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ec_live_xxxxxxxxxxxx',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    location_id: 'loc_01HWRH001',
    items: [
      {
        variant_id: 'var_01HDEF789',
        delta: 20,
        reason: 'Supplier delivery — PO-2024-089'
      },
      {
        variant_id: 'var_01HDEF790',
        delta: -3,
        reason: 'Damaged goods removed from stock'
      }
    ]
  })
});
const adjustment = await response.json();
```

```json Response theme={null}
{
  "id": "adj_01HADJ001",
  "location_id": "loc_01HWRH001",
  "location_name": "Main Warehouse",
  "created_at": "2024-06-11T17:00:00Z",
  "items": [
    {
      "variant_id": "var_01HDEF789",
      "sku": "TEE-M-BLK",
      "delta": 20,
      "quantity_before": 30,
      "quantity_after": 50,
      "reason": "Supplier delivery — PO-2024-089"
    },
    {
      "variant_id": "var_01HDEF790",
      "sku": "TEE-L-BLK",
      "delta": -3,
      "quantity_before": 12,
      "quantity_after": 9,
      "reason": "Damaged goods removed from stock"
    }
  ]
}
```

***

## Error Handling

The Inventory API uses standard HTTP status codes. All error responses include a JSON body with a `code` field and a human-readable `message`.

| Status | Code | What it means | How to fix it |
| - | - | - | - |
| `400 Bad Request` | `invalid_params` | A required field is missing or invalid (e.g. negative `quantity` on a set-quantity call, or missing `reason` on an adjustment). | Check the `message` field for the specific validation failure and correct your request. |
| `401 Unauthorized` | `missing_api_key` / `invalid_api_key` | No `Authorization` header was sent, or the key is revoked. | Add a valid `Authorization: Bearer <key>` header. |
| `403 Forbidden` | `insufficient_scope` | Your key does not have `read:inventory` or `write:inventory` as required. | Re-generate your key with the correct scopes in **Settings → Developer → API Keys**. |
| `404 Not Found` | `variant_not_found` / `location_not_found` | The variant ID or location ID provided does not exist in your store. | Confirm both IDs are correct using `GET /inventory` or the Products API. |
| `422 Unprocessable Entity` | `quantity_below_zero` | Applying the requested delta would result in a negative quantity. | Adjust the `delta` so the resulting quantity stays at zero or above. |
| `429 Too Many Requests` | `rate_limit_exceeded` | You have exceeded 1,000 requests per minute. | Wait until `X-RateLimit-Reset` and retry with exponential backoff. |
| `500 Internal Server Error` | `internal_error` | An unexpected server error occurred. | Retry after a short delay. If the problem persists, contact Eaglecart support. |


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