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

# Inventory API: Adjust Stock Across Locations

> Record stock movements for any variant and location using signed quantity deltas. Every adjustment creates an immutable ledger entry for full auditability.

The Inventory API gives you precise control over stock levels across all your fulfillment locations. Rather than setting an absolute quantity, you post a signed delta — positive to add stock and negative to remove it. Each adjustment creates an immutable ledger entry, so you always have a complete, auditable history of every stock movement.

<Note>
  All requests require three headers: `Authorization: Bearer YOUR_TOKEN`, `X-Tenant-ID: YOUR_TENANT_ID`, and `X-Org-ID: YOUR_ORG_ID`.
</Note>

***

## Adjust inventory

Post a stock adjustment for a specific product variant at a given location. The `quantity_delta` field is signed:

* **Positive** values add stock (e.g. a goods receipt or purchase order receipt).
* **Negative** values remove stock (e.g. a sales fulfillment or write-off).

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

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider.
</ParamField>

<ParamField header="X-Tenant-ID" type="string" required>
  UUID of your tenant.
</ParamField>

<ParamField header="X-Org-ID" type="string" required>
  UUID of your organization.
</ParamField>

### Body

<ParamField body="variant_id" type="string" required>
  UUID of the product variant whose stock you are adjusting.
</ParamField>

<ParamField body="location_id" type="string" required>
  UUID of the fulfillment location at which the adjustment occurs.
</ParamField>

<ParamField body="quantity_delta" type="integer" required>
  Signed integer indicating the stock change. Use a positive value to add units; use a negative value to remove units. A value of `0` is a no-op.
</ParamField>

### Response

Returns the created ledger entry.

<ResponseField name="id" type="string">
  UUID of the new ledger entry.
</ResponseField>

<ResponseField name="org_id" type="string">
  UUID of the organization.
</ResponseField>

<ResponseField name="tenant_id" type="string">
  UUID of the tenant.
</ResponseField>

<ResponseField name="variant_id" type="string">
  UUID of the adjusted variant.
</ResponseField>

<ResponseField name="location_id" type="string">
  UUID of the adjusted location.
</ResponseField>

<ResponseField name="quantity_delta" type="integer">
  The signed delta that was recorded.
</ResponseField>

<ResponseField name="transaction_type" type="string">
  Type of transaction. API-initiated adjustments are recorded as `adjustment`.
</ResponseField>

<ResponseField name="notes" type="string">
  Human-readable note attached to the entry. API-initiated adjustments use `API Adjustment`.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 timestamp of when the ledger entry was created.
</ResponseField>

***

### Example: Receiving stock

Use a positive `quantity_delta` when stock arrives at a warehouse — for example, when a purchase order is received.

<CodeGroup>
  ```bash cURL — Receive stock theme={null}
  curl -X POST https://api.synq.app/api/v1/inventory/adjust \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "variant_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "location_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
      "quantity_delta": 250
    }'
  ```

  ```json Response — Receive stock theme={null}
  {
    "id": "a9b0c1d2-e3f4-5678-9abc-def012345678",
    "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "variant_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "location_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
    "quantity_delta": 250,
    "transaction_type": "adjustment",
    "notes": "API Adjustment",
    "created_at": "2024-06-12T09:00:00Z"
  }
  ```
</CodeGroup>

***

### Example: Fulfillment deduction

Use a negative `quantity_delta` when units are picked and shipped to fulfill an order.

<CodeGroup>
  ```bash cURL — Fulfillment deduction theme={null}
  curl -X POST https://api.synq.app/api/v1/inventory/adjust \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID" \
    -H "Content-Type: application/json" \
    -d '{
      "variant_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
      "location_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
      "quantity_delta": -2
    }'
  ```

  ```json Response — Fulfillment deduction theme={null}
  {
    "id": "b0c1d2e3-f4a5-6789-bcde-f01234567890",
    "org_id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "variant_id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
    "location_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
    "quantity_delta": -2,
    "transaction_type": "adjustment",
    "notes": "API Adjustment",
    "created_at": "2024-06-12T14:35:00Z"
  }
  ```
</CodeGroup>

<Warning>
  The API does not currently enforce a minimum stock floor. Posting a negative delta that would result in a sub-zero balance is permitted and will be recorded in the ledger. If you need oversell prevention, enforce stock checks in your application logic before calling this endpoint.
</Warning>