Skip to content
Vinosoft2026-04-01
en/de
API reference navigation

Inventory

Admin

Inventory groups 3 operations on the admin tier.

Admin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

GET

/api/{version}/admin/inventory_levels

The levels of the requested inventory items, optionally narrowed to given locations. Both parameters are comma-separated GUID lists. inventory_item_ids is required and capped at 250 ids; missing or over the cap is a 422. Unparseable ids are dropped silently, so a list of only-garbage ids reads as "required" too.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Query parameters

NameTypeDescription
inventory_item_ids
optional
string
location_ids
optional
string

Responses

curl -X GET \
  'https://<your-shop-domain>/api/2026-04-01/admin/inventory_levels' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>'
Response200example shape
{
  "inventory_levels": [
    {
      "inventory_item_id": "00000000-0000-0000-0000-000000000000",
      "location_id": "00000000-0000-0000-0000-000000000000",
      "available": 1
    }
  ]
}
POST

/api/{version}/admin/inventory_levels/set

Sets the absolute on-hand for one (inventory item, location) pair and returns the level as stored. An unknown item or location is a 404; a missing body or a rejected value is a 422.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Request body

application/json, text/json, application/*+json · optional

SetInventoryLevelRequest

Body for POST inventory_levels/set. Sets the absolute on-hand to Cloudwawi.Shop.Api.V2026_04_01.SetInventoryLevelRequest.Available.

  • inventory_item_idstring (uuid)
  • location_idstring (uuid)
  • availablenumber (double)

Responses

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/admin/inventory_levels/set' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "inventory_item_id": "00000000-0000-0000-0000-000000000000",
  "location_id": "00000000-0000-0000-0000-000000000000",
  "available": 1
}'
Response200example shape
{
  "inventory_level": {
    "inventory_item_id": "00000000-0000-0000-0000-000000000000",
    "location_id": "00000000-0000-0000-0000-000000000000",
    "available": 1
  }
}
POST

/api/{version}/admin/inventory_levels/adjust

Moves the on-hand of one (inventory item, location) pair by available_adjustment (negative to decrease) and returns the resulting level. Same error shape as set.

AuthenticationToken requiredAdmin tier. Requires an RBAC-gated vnstat_ access token, sent as Authorization: Bearer … or X-Vinosoft-Access-Token.

Request body

application/json, text/json, application/*+json · optional

AdjustInventoryLevelRequest

Body for POST inventory_levels/adjust. Changes the on-hand by Cloudwawi.Shop.Api.V2026_04_01.AdjustInventoryLevelRequest.AvailableAdjustment.

  • inventory_item_idstring (uuid)
  • location_idstring (uuid)
  • available_adjustmentnumber (double)

Responses

curl -X POST \
  'https://<your-shop-domain>/api/2026-04-01/admin/inventory_levels/adjust' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer vnstat_<token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "inventory_item_id": "00000000-0000-0000-0000-000000000000",
  "location_id": "00000000-0000-0000-0000-000000000000",
  "available_adjustment": 1
}'
Response200example shape
{
  "inventory_level": {
    "inventory_item_id": "00000000-0000-0000-0000-000000000000",
    "location_id": "00000000-0000-0000-0000-000000000000",
    "available": 1
  }
}

Schemas

AdjustInventoryLevelRequest

Body for POST inventory_levels/adjust. Changes the on-hand by Cloudwawi.Shop.Api.V2026_04_01.AdjustInventoryLevelRequest.AvailableAdjustment.

  • inventory_item_idstring (uuid)
  • location_idstring (uuid)
  • available_adjustmentnumber (double)

ApiErrorResponse

The error envelope every non-2xx response from this API uses. Documentation shape: actions build it as an anonymous object, so this type exists to give the OpenAPI document a schema to point at.

  • errorsstringnullable

    Human-readable description of what went wrong, e.g. Not Found, Invalid page_info.

  • codestringnullable

    Machine-readable error code. Only a few endpoints (checkout) emit one; omitted everywhere else.

InventoryLevelDto

Admin representation of an inventory level (the inventory_levels resource — Shopify inventory_levels convention). Cloudwawi stock is movement-based, so Cloudwawi.Shop.Api.V2026_04_01.InventoryLevelDto.Available is the computed on-hand amount, not a stored column. Keyed by Cloudwawi.Shop.Api.V2026_04_01.InventoryLevelDto.InventoryItemId (the storefront variant id, i.e. Article.Id) and Cloudwawi.Shop.Api.V2026_04_01.InventoryLevelDto.LocationId (ArticleStorageLocation.Id). Serialized snake_case via explicit [JsonPropertyName] because the host's global JSON policy is camelCase.

  • inventory_item_idstring (uuid)
  • location_idstring (uuid)
  • availablenumber (double)

InventoryLevelListResponse

Envelope returned by GET /admin/inventory_levels. This read is filter-bounded rather than cursored: there is no Link header and no page_info, because inventory_item_ids is required and capped at 250 ids per call. Ask for the ids you want.

  • inventory_levelsInventoryLevelDto[]nullable

    One entry per (inventory item, location) pair that has a level. Always present; an empty array when none of the requested items are stocked at any of the requested locations. The response is not padded to one row per requested id — a missing pair means no level, which reads as zero on hand.

InventoryLevelResponse

Envelope returned by POST /admin/inventory_levels/set and POST /admin/inventory_levels/adjust.

SetInventoryLevelRequest

Body for POST inventory_levels/set. Sets the absolute on-hand to Cloudwawi.Shop.Api.V2026_04_01.SetInventoryLevelRequest.Available.

  • inventory_item_idstring (uuid)
  • location_idstring (uuid)
  • availablenumber (double)