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

# Settings API: Configure Tenant Preferences

> Read and update tenant-level settings: inventory allocation model, automatic purchase orders, low stock thresholds, and inventory costing method.

The Settings API lets you read and update the operational preferences for your tenant. These settings govern how Synq behaves across inventory allocation, purchase order automation, and cost accounting. Changes take effect immediately and are applied to all future transactions. Every update is written to the audit log with the identity of the user who made the change.

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

***

## Get tenant settings

Retrieve the current operational settings for your tenant.

**`GET /api/v1/settings/tenant`**

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

### Response

<ResponseField name="id" type="string">UUID of the settings record.</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="inventory_allocation_model" type="string">
  How inventory is reserved for orders. `HARD` allocates stock at order time; `SOFT` reserves without a hard deduction until fulfillment.
</ResponseField>

<ResponseField name="auto_po_enabled" type="boolean">
  Whether Synq automatically creates purchase orders when stock falls below the low stock threshold.
</ResponseField>

<ResponseField name="default_low_stock_threshold" type="integer">
  Number of units below which Synq flags a variant as low stock (and triggers auto-PO if enabled).
</ResponseField>

<ResponseField name="costing_method" type="string">
  Inventory valuation method. `WAC` uses weighted average cost; `FIFO` uses first-in, first-out.
</ResponseField>

<ResponseField name="updated_by" type="string">UUID of the user who last updated these settings.</ResponseField>
<ResponseField name="created_at" type="string">ISO 8601 creation timestamp.</ResponseField>
<ResponseField name="updated_at" type="string">ISO 8601 last-updated timestamp.</ResponseField>

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.synq.app/api/v1/settings/tenant \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "X-Tenant-ID: YOUR_TENANT_ID" \
    -H "X-Org-ID: YOUR_ORG_ID"
  ```

  ```json Response theme={null}
  {
    "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "org_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "inventory_allocation_model": "HARD",
    "auto_po_enabled": false,
    "default_low_stock_threshold": 10,
    "costing_method": "WAC",
    "updated_by": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-06-01T09:15:00Z"
  }
  ```
</CodeGroup>

***

## Update tenant settings

Update the operational settings for your tenant. You must have the `Admin` role to call this endpoint. All fields are replaced with the values you provide — send the full settings object to avoid unintentional resets.

**`PUT /api/v1/settings/tenant`**

<Warning>
  Only users with the `Admin` role can update settings. All other roles receive `403 Forbidden`.
</Warning>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token from your authentication provider. The calling user must have the `Admin` role.
</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="inventory_allocation_model" type="string" required>
  Inventory reservation strategy. Must be `HARD` or `SOFT`.

  * `HARD` — stock is immediately decremented when an order is placed. Overselling is prevented.
  * `SOFT` — stock is earmarked but not decremented until the order is fulfilled. Useful for high-volume flash sales.

  Defaults to `HARD`.
</ParamField>

<ParamField body="auto_po_enabled" type="boolean" required>
  Set to `true` to have Synq automatically create a draft purchase order whenever a variant's available stock falls at or below `default_low_stock_threshold`.
</ParamField>

<ParamField body="default_low_stock_threshold" type="integer" required>
  The unit count at which a variant is considered low stock. Must be `0` or greater. For example, a value of `10` means any variant with 10 or fewer units on hand is flagged.
</ParamField>

<ParamField body="costing_method" type="string" required>
  How Synq calculates the cost of goods sold. Must be `WAC` (Weighted Average Cost) or `FIFO` (First In, First Out).

  Defaults to `WAC`.
</ParamField>

### Response

Returns the updated settings object.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X PUT https://api.synq.app/api/v1/settings/tenant \
    -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 '{
      "inventory_allocation_model": "HARD",
      "auto_po_enabled": true,
      "default_low_stock_threshold": 20,
      "costing_method": "FIFO"
    }'
  ```

  ```json Response theme={null}
  {
    "id": "e5f6a7b8-c9d0-1234-efab-567890123456",
    "org_id": "f6a7b8c9-d0e1-2345-abcd-678901234567",
    "tenant_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "inventory_allocation_model": "HARD",
    "auto_po_enabled": true,
    "default_low_stock_threshold": 20,
    "costing_method": "FIFO",
    "updated_by": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "created_at": "2024-01-10T08:00:00Z",
    "updated_at": "2024-06-15T14:00:00Z"
  }
  ```
</CodeGroup>