Warehouses and stock

Warehouses, the quantity on hand of each product, and stock adjustments.

Version v1.1, updated 5 October 2026

On this page

Fields
List warehouses
List stock levels
Adjust the stock of a goods item in a warehouse
Related

Warehouses are the places where the company keeps stock, shops included. Stock levels give the quantity on hand per product, warehouse and unit, and adjustments record what changes outside BIRP.

Fields

Send says the field is in responses. Receive says a write accepts it; a reference is sent as an object, such as category for category_id. Totals, VAT, numbers and statuses are computed by BIRP and never received.

Warehouse

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
address	string or null	No	No	Yes	Address, free text.
archived_at	string or null	No	No	Yes	When the warehouse was archived. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
created_at	string	Yes	No	Yes	Creation time. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.
external_ids	array of ExternalId	Yes	No	Yes	Identifiers of the warehouse in external systems.
id	string (uuid)	Yes	No	Yes	Warehouse identifier.
kind	string	Yes	No	Yes	retail: the warehouse of a shop.
name	string	Yes	No	Yes	Name, unique per company.
status	string	Yes	No	Yes	archived when the warehouse was archived in BIRP. One of: active, archived.
updated_at	string	Yes	No	Yes	Last change. ISO 8601 date and time in UTC, with millisecond precision and a Z suffix.

Stock level

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
id	string	Yes	No	Yes	Identifier of the row, stable while the row exists. Treat it as opaque text.
lot_count	number	Yes	No	Yes	Number of lots counted.
product_id	string (uuid)	Yes	No	Yes	Product identifier.
product_kind	string	Yes	No	Yes	Kind of the product. One of: goods, finished_product.
quantity	string or null	No	No	Yes	Quantity on hand in the warehouse, in this unit. Decimal string, at most three decimals, or null; when it is null, quantity_raw gives the quantity as text.
quantity_raw	string	No	No	Yes	The quantity as text, present only when quantity is null.
unit	string	Yes	No	Yes	Unit of the quantity.
warehouse_id	string (uuid) or null	No	No	Yes	Warehouse of the stock, or null when the stock is not assigned to one.

Stock adjustment

Field	Type	Required	Receive (inbound)	Send (outbound)	Notes
created_at	string	Yes	No	Yes	ISO 8601 date and time in UTC.
id	string (uuid)	Yes	No	Yes	Identifier of the adjustment; its movements carry it.
level	StockLevel or null	No	No	Yes	Stock of the product in the warehouse and unit after the adjustment, as GET /v1/stock/levels returns it. Null when nothing is left.
movements	array of StockMovement	Yes	No	Yes	The movements the adjustment wrote.
note	string or null	No	Yes	Yes
product_id	string (uuid)	Yes	No	Yes
quantity	string	Yes	Yes	Yes	Signed decimal string, three decimals.
reason	string	Yes	Yes	Yes	One of: receipt, adjustment, loss.
reference	string or null	No	Yes	Yes
unit	string	Yes	Yes	Yes
warehouse_id	string (uuid)	Yes	No	Yes

List warehouses

Lists the warehouses of the company, shop warehouses included.

Scope: stock:read.
Idempotency: a read; send it as often as you need.

A warehouse of kind retail belongs to a shop.

GET/v1/warehouses

Parameters

limitinteger, in query: Page size, 1 to 200. Default 50.Default 50
cursorstring, in query: next_cursor of the previous page. Pages are ordered by id.Example opaque-cursor-example
updated_sincestring (date-time), in query: Only records changed at or after this time: ISO 8601 date and time with an offset or Z.Example 2026-09-01T00:00:00Z
external_idstring, in query: Identifier in an external system. Requires source.Example 1042
sourcestring, in query: External system of external_id, in lowercase. Requires external_id.Example woocommerce

GET /v1/warehouses

curl "https://api.birp.io/v1/warehouses" \
  -H "Authorization: Bearer $BIRP_API_KEY"

const response = await fetch("https://api.birp.io/v1/warehouses", {
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/warehouses");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/warehouses",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": [
    {
      "address": "Str. Exemplului 4, Chisinau",
      "archived_at": null,
      "created_at": "2026-09-01T07:30:00.000Z",
      "external_ids": [],
      "id": "00000000-0000-4000-8000-000000000041",
      "kind": "warehouse",
      "name": "Main warehouse",
      "status": "active",
      "updated_at": "2026-09-28T14:05:12.417Z"
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 50,
    "next_cursor": null
  }
}

Errors particular to this operation:

422 validation_failed

List stock levels

Lists the quantity on hand of each product, per warehouse and unit.

Scope: stock:read.
Idempotency: a read; send it as often as you need.

Stock levels have no updated_since: read them per warehouse or per product, with the cursor.

GET/v1/stock/levels

Parameters

limitinteger, in query: Page size, 1 to 200. Default 50.Default 50
cursorstring, in query: next_cursor of the previous page. Pages are ordered by id.Example opaque-cursor-example
warehouse_idstring, in query: A warehouse id, or none for stock not assigned to a warehouse.Example 00000000-0000-4000-8000-000000000041
product_idstring (uuid), in query: One product.Example 00000000-0000-4000-8000-000000000011

GET /v1/stock/levels

curl "https://api.birp.io/v1/stock/levels" \
  -H "Authorization: Bearer $BIRP_API_KEY"

const response = await fetch("https://api.birp.io/v1/stock/levels", {
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
  },
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/stock/levels");
curl_setopt_array($ch, [
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import requests

response = requests.request(
    "GET",
    "https://api.birp.io/v1/stock/levels",
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

200 OKJSON

{
  "data": [
    {
      "id": "EXAMPLE-LEVEL-0001",
      "lot_count": 2,
      "product_id": "00000000-0000-4000-8000-000000000011",
      "product_kind": "goods",
      "quantity": "12.5",
      "unit": "kg",
      "warehouse_id": "00000000-0000-4000-8000-000000000041"
    },
    {
      "id": "EXAMPLE-LEVEL-0002",
      "lot_count": 1,
      "product_id": "00000000-0000-4000-8000-000000000012",
      "product_kind": "finished_product",
      "quantity": "30",
      "unit": "pcs",
      "warehouse_id": null
    }
  ],
  "meta": {
    "has_more": false,
    "limit": 50,
    "next_cursor": null
  }
}

Errors particular to this operation:

422 validation_failed

Adjust the stock of a goods item in a warehouse

Records a receipt, a correction or a loss of a goods item in a warehouse, and returns the resulting level.

Scope: stock:write.
Idempotency: Idempotency-Key required. See Idempotency.

receipt takes a quantity above zero, loss one below zero, adjustment either. Adjustments apply to resale goods, in warehouses of kind warehouse.

POST/v1/stock/adjustments

Parameters

Idempotency-Keyrequiredstring, in header: Unique value for this request (for example a UUID), 1 to 128 printable ASCII characters. A retry with the same key and the same request gets the stored response for 24 hours, with Idempotency-Replayed: true; the same key with a different request answers 422 idempotency_key_reused. Required on POST, optional on PUT, PATCH and DELETE.Example 00000000-0000-4000-8000-0000000000a1

Request body

application/json

notestring | null
unitstring: Unit of the quantity. Left out: the default unit of the product.
reasonrequiredstring: receipt: goods received (quantity above zero). adjustment: a correction, such as a stock count (either sign). loss: damage, theft or expiry (quantity below zero).One of receipt, adjustment, loss
productrequiredProductReference: A goods item of the company. Finished products are not adjusted through the API in this version: their stock comes from production.
product.idstring (uuid): BIRP id of the record.
product.skustring: Product SKU.
product.kindstring: With sku only: which kind of product.One of goods, finished_product
product.sourcestring: External system of external_id, in lowercase.
product.external_idstring: Identifier of the record in an external system. Requires source.
quantityrequiredstring: Signed decimal string, at most three decimals, not zero: positive adds stock, negative takes it.
referencestring | null: Reference in the calling system, for example a delivery note or a count id. Kept with the movements.
warehouserequiredReference: An active warehouse of kind warehouse.
warehouse.idstring (uuid): BIRP id of the record.
warehouse.sourcestring: External system of external_id, in lowercase.
warehouse.external_idstring: Identifier of the record in an external system. Requires source.

POST /v1/stock/adjustments

curl -X POST "https://api.birp.io/v1/stock/adjustments" \
  -H "Authorization: Bearer $BIRP_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note":"Weekly count","product":{"sku":"SP-FLOUR-25"},"quantity":"-2.5","reason":"adjustment","reference":"WC-COUNT-2026-10-05","warehouse":{"id":"00000000-0000-4000-8000-000000000041"}}'

const response = await fetch("https://api.birp.io/v1/stock/adjustments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.BIRP_API_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "note": "Weekly count",
    "product": {
      "sku": "SP-FLOUR-25"
    },
    "quantity": "-2.5",
    "reason": "adjustment",
    "reference": "WC-COUNT-2026-10-05",
    "warehouse": {
      "id": "00000000-0000-4000-8000-000000000041"
    }
  }),
});
if (!response.ok) throw new Error(`BIRP API error ${response.status}`);
const result = await response.json();

<?php
$ch = curl_init("https://api.birp.io/v1/stock/adjustments");
curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => "POST",
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("BIRP_API_KEY"),
        "Idempotency-Key: " . bin2hex(random_bytes(16)),
        "Content-Type: application/json",
    ],
    CURLOPT_POSTFIELDS => <<<'JSON'
{
  "note": "Weekly count",
  "product": {
    "sku": "SP-FLOUR-25"
  },
  "quantity": "-2.5",
  "reason": "adjustment",
  "reference": "WC-COUNT-2026-10-05",
  "warehouse": {
    "id": "00000000-0000-4000-8000-000000000041"
  }
}
JSON,
    CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);

import os
import uuid
import requests

response = requests.request(
    "POST",
    "https://api.birp.io/v1/stock/adjustments",
    json={
      "note": "Weekly count",
      "product": {
        "sku": "SP-FLOUR-25"
      },
      "quantity": "-2.5",
      "reason": "adjustment",
      "reference": "WC-COUNT-2026-10-05",
      "warehouse": {
        "id": "00000000-0000-4000-8000-000000000041"
      }
    },
    headers={
        "Authorization": f"Bearer {os.environ['BIRP_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    timeout=10,
)
response.raise_for_status()
result = response.json()

201 CreatedJSON

{
  "data": {
    "created_at": "2026-10-05T09:12:44.120Z",
    "id": "a1b2c3d4-0000-4000-8000-0000000000aa",
    "level": {
      "id": "EXAMPLE-LEVEL-0001",
      "lot_count": 2,
      "product_id": "00000000-0000-4000-8000-000000000011",
      "product_kind": "goods",
      "quantity": "12.5",
      "unit": "kg",
      "warehouse_id": "00000000-0000-4000-8000-000000000041"
    },
    "movements": [
      {
        "id": "b2c3d4e5-0000-4000-8000-0000000000bb",
        "lot_id": "c3d4e5f6-0000-4000-8000-0000000000cc",
        "quantity": "-2.500",
        "type": "adjustment"
      }
    ],
    "note": "Weekly count",
    "product_id": "00000000-0000-4000-8000-000000000011",
    "quantity": "-2.500",
    "reason": "adjustment",
    "reference": "WC-COUNT-2026-10-05",
    "unit": "kg",
    "warehouse_id": "00000000-0000-4000-8000-000000000041"
  }
}

Errors particular to this operation:

409 insufficient_stock
409 sku_ambiguous
422 reference_not_found
422 validation_failed

stock-levels
products
pagination-and-filtering

Fields

List warehouses

List stock levels

Adjust the stock of a goods item in a warehouse

Related