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

# Create transfer

> Moves stock from one store to another. Debits from_store_id and credits to_store_id atomically. Returns HTTP 202.

<ParamField header="x-api-key" type="string" required>
  API key with `inventory:write` scope.
</ParamField>

<ParamField path="vendorId" type="string" required>
  Vendor UUID.
</ParamField>

<ParamField body="idempotency_key" type="string" required>
  Idempotency key (1–128 chars).
</ParamField>

<ParamField body="external_user_id" type="string" required>
  Actor for audit trail.
</ParamField>

<ParamField body="from_store_id" type="string" required>
  UUID of the source store.
</ParamField>

<ParamField body="to_store_id" type="string" required>
  UUID of the destination store.
</ParamField>

<ParamField body="external_reference" type="string">
  Optional reference number for your system.
</ParamField>

<ParamField body="initiated_at" type="string">
  ISO 8601 timestamp of when the transfer was physically initiated.
</ParamField>

<ParamField body="notes" type="string">
  Optional notes (max 500 chars).
</ParamField>

<ParamField body="metadata" type="object">
  Free-form extra data.
</ParamField>

<ParamField body="lines" type="object[]" required>
  Items being transferred (1–500 lines):

  <Expandable title="line fields">
    <ParamField body="item_id" type="string" required>UUID of the item.</ParamField>
    <ParamField body="qty" type="number" required>Quantity in display unit.</ParamField>
    <ParamField body="qty_base" type="number" required>Quantity in base unit.</ParamField>
    <ParamField body="base_unit_id" type="string" required>Base unit UUID.</ParamField>
    <ParamField body="unit_id" type="string">Display unit UUID.</ParamField>
    <ParamField body="unit_label" type="string">Display unit label.</ParamField>
    <ParamField body="unit_to_base_factor" type="number" required>Conversion factor.</ParamField>
    <ParamField body="lot_id" type="string">Lot UUID.</ParamField>
    <ParamField body="metadata" type="object">Extra data per line.</ParamField>
  </Expandable>
</ParamField>

<ResponseField name="tracking_id" type="string">Polling token.</ResponseField>
<ResponseField name="inventory_transaction_id" type="string">Transaction UUID.</ResponseField>
<ResponseField name="transfer_id" type="string">Created transfer UUID.</ResponseField>
<ResponseField name="idempotent" type="boolean">`true` if duplicate.</ResponseField>

<RequestExample>
  ```json theme={null}
  {
    "idempotency_key": "xfer-2026-08-07-001",
    "external_user_id": "user_manager",
    "from_store_id": "str_main_01...",
    "to_store_id": "str_satelite_01...",
    "external_reference": "TRF-2026-0042",
    "lines": [
      {
        "item_id": "itm_chicken_01...",
        "qty": 5,
        "qty_base": 5000,
        "base_unit_id": "unit_g_01...",
        "unit_id": "unit_kg_01...",
        "unit_label": "kg",
        "unit_to_base_factor": 1000
      }
    ]
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 202 theme={null}
  {
    "tracking_id": "trk_01j5k...",
    "inventory_transaction_id": "txn_01j5k...",
    "transfer_id": "xfr_01j5k...",
    "idempotent": false
  }
  ```
</ResponseExample>