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

# Track and Adjust Inventory Across Locations with Synq

> Learn how Synq tracks stock movements across warehouses and fulfillment locations, and how to adjust inventory levels using the Inventory API.

Synq tracks stock using an inventory ledger — a permanent, append-only record of every movement that has ever touched a SKU. Each time you receive new stock, write off shrinkage, or make a manual correction, Synq records the variant, location, quantity change, and the reason. The current on-hand quantity for any variant at any location is always derived from the sum of those recorded movements. This design gives you a complete, auditable history of your inventory without ever overwriting past data.

## How inventory adjustments work

When you post an adjustment, Synq permanently records a stock movement with the following fields:

* **variant\_id** — the product variant the movement applies to
* **location\_id** — the warehouse or fulfillment center where stock changed
* **quantity\_delta** — a signed integer: positive values add stock, negative values remove it

Each adjustment is written permanently and cannot be modified or deleted.

<Note>
  Inventory adjustments are **permanent**. Once a movement is recorded, it cannot be modified or deleted. To correct a mistake, post a new adjustment that reverses the error.
</Note>

***

## Required headers

Every request to the Synq API requires three headers for tenant isolation and authentication.

| Header          | Description                            |
| --------------- | -------------------------------------- |
| `Authorization` | `Bearer <your_api_token>`              |
| `X-Tenant-ID`   | Your Synq tenant identifier            |
| `X-Org-ID`      | The organization scope for the request |

***

## Adjust inventory

Use `POST /api/v1/inventory/adjust` to record any stock movement for a variant at a specific location. This single endpoint covers all use cases: receiving new goods, removing damaged units, correcting miscounts, and writing off shrinkage.

### Endpoint

```
POST /api/v1/inventory/adjust
```

### Request fields

<ParamField body="variant_id" type="string (UUID)" required>
  The Synq variant UUID for the SKU whose stock you are adjusting.
</ParamField>

<ParamField body="location_id" type="string (UUID)" required>
  The UUID of the warehouse or fulfillment location where stock is changing.
</ParamField>

<ParamField body="quantity_delta" type="integer" required>
  The signed quantity to apply. Use a **positive** integer to add stock (e.g. receiving a shipment), and a **negative** integer to remove stock (e.g. shrinkage or a manual write-off).
</ParamField>

<Tip>
  Use `location_id` to track stock independently per warehouse, retail store, or 3PL fulfillment centre. Synq computes available stock per `variant_id` + `location_id` pair, so you always know exactly how much stock is available at each site — not just globally.
</Tip>

***

## Examples

<CodeGroup>
  ```bash Receive stock (+50 units) theme={null}
  curl -X POST https://api.synq.io/api/v1/inventory/adjust \
    -H "Authorization: Bearer $SYNQ_API_TOKEN" \
    -H "X-Tenant-ID: $SYNQ_TENANT_ID" \
    -H "X-Org-ID: $SYNQ_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "location_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "quantity_delta": 50
    }'
  ```

  ```bash Remove stock (–5 units) theme={null}
  curl -X POST https://api.synq.io/api/v1/inventory/adjust \
    -H "Authorization: Bearer $SYNQ_API_TOKEN" \
    -H "X-Tenant-ID: $SYNQ_TENANT_ID" \
    -H "X-Org-ID: $SYNQ_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "location_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "quantity_delta": -5
    }'
  ```
</CodeGroup>

***

## Response

A successful adjustment returns `200 OK` with the details of the recorded stock movement.

```json Response theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "org_id": "c2d3e4f5-a6b7-8901-bcde-f12345678901",
  "tenant_id": "d3e4f5a6-b7c8-9012-cdef-123456789012",
  "variant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "location_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
  "transaction_type": "adjustment",
  "quantity_delta": 50,
  "reference_id": null,
  "unit_cost": null,
  "notes": "API Adjustment",
  "created_at": "2025-06-01T11:45:00Z"
}
```

### Response fields

<ResponseField name="id" type="string (UUID)">
  The unique identifier of this recorded stock movement.
</ResponseField>

<ResponseField name="org_id" type="string (UUID)">
  The organization this adjustment belongs to.
</ResponseField>

<ResponseField name="tenant_id" type="string (UUID)">
  The tenant this adjustment belongs to.
</ResponseField>

<ResponseField name="variant_id" type="string (UUID)">
  The variant whose stock was adjusted.
</ResponseField>

<ResponseField name="location_id" type="string (UUID)">
  The location where the stock movement occurred.
</ResponseField>

<ResponseField name="transaction_type" type="string">
  The type of movement recorded. API-driven adjustments use `"adjustment"`. Order fulfillment and returns use their own transaction types written automatically by the OMS.
</ResponseField>

<ResponseField name="quantity_delta" type="integer">
  The signed delta recorded for this movement. Positive means stock was added; negative means stock was removed.
</ResponseField>

<ResponseField name="reference_id" type="string | null">
  An optional reference identifier linking this movement to an external record (e.g. a purchase order number). `null` for generic API adjustments.
</ResponseField>

<ResponseField name="unit_cost" type="number | null">
  Cost per unit at the time of the movement, if captured. `null` for generic API adjustments.
</ResponseField>

<ResponseField name="notes" type="string">
  Human-readable note attached to this movement. Defaults to `"API Adjustment"` for entries created via this endpoint.
</ResponseField>

<ResponseField name="created_at" type="string (ISO 8601)">
  UTC timestamp of when this stock movement was recorded.
</ResponseField>

***

## Common use cases

| Scenario                     | `quantity_delta` | Notes                                                   |
| ---------------------------- | ---------------- | ------------------------------------------------------- |
| Receiving a purchase order   | `+N`             | Post one adjustment per variant per location in the PO  |
| Manual stocktake correction  | `+N` or `-N`     | Delta = physical count minus current on-hand total      |
| Shrinkage / damage write-off | `-N`             | Record loss; cannot be undone, only reversed            |
| Return restocking            | `+N`             | Add units back after a return is inspected and accepted |

<Warning>
  Do **not** use this endpoint to reflect inventory consumed by order fulfillment. The Synq OMS automatically reserves and deducts inventory when it processes an order. Manually posting a negative delta on top of a fulfilled order will result in double-deduction.
</Warning>