Containers - BevvyTech/BrewskiDocs GitHub Wiki

Containers

Method Path Description
GET /containers List containers for a team with pagination and sorting.
POST /containers Create a new container for a team (owner/admin only).
PATCH /containers/:id Update a container (owner/admin only).
DELETE /containers/:id Delete a container (owner/admin only).
POST /containers/remove-unused Remove containers not linked to priced or stocked beers (owner/admin only).
GET /containers/batch Download the team’s containers as comma-delimited text (owner/admin only).
POST /containers/batch Import comma-delimited text to create/update containers (owner/admin only).

GET /containers

  • Query Parameters:
    • teamId (uuid, required)
    • sort (name | volumeMl | createdAt, default name)
    • direction (asc | desc, default asc)
    • page, pageSize (≤ 200, defaults 1 & 25)
  • Response 200: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "page": 1,
  "pageSize": 25,
  "total": 2,
  "pages": 1,
  "sort": "name",
  "direction": "asc",
  "results": [
    {
      "id": "4fb3...",
      "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
      "name": "30 L Keg",
      "containerType": "keg",
      "volumeMl": 30000,
      "defaultBbeMonths": 6,
      "isDefault": true,
      "isReturnable": true,
      "createdAt": "2025-10-08T09:20:10.000Z",
      "updatedAt": "2025-10-08T09:20:10.000Z"
    },
    {
      "id": "7d91...",
      "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
      "name": "440 ml Can",
      "containerType": "can",
      "volumeMl": 440,
      "defaultBbeMonths": 4,
      "isDefault": false,
      "isReturnable": false,
      "createdAt": "2025-10-08T09:22:14.000Z",
      "updatedAt": "2025-10-08T09:22:14.000Z"
    }
  ]
}

POST /containers

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "name": "9 g Cask",
  "containerType": "cask",
  "volumeMl": 40923,
  "defaultBbeMonths": 9,
  "isDefault": false
}
  • Response 201: 
    {
  "container": {
    "id": "a8c3...",
    "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
    "name": "9 g Cask",
    "containerType": "cask",
    "volumeMl": 40923,
    "defaultBbeMonths": 9,
    "isDefault": false,
    "isReturnable": false,
    "createdAt": "2025-10-08T09:33:12.000Z",
    "updatedAt": "2025-10-08T09:33:12.000Z"
  }
}
  • Notes: If this is the team’s first container it is automatically marked as the default, regardless of the submitted isDefault flag. Selecting isDefault: true will demote every other container for the team. Supply defaultBbeMonths (whole months) to store the team’s default best-before window; omit or set to null to leave unset. Use isReturnable (only honoured for keg containers) to flag whether the stock should be treated as returnable.
  • Errors: 400 (validation), 401 unauthorized, 403 when caller is not owner/admin for the team, 409 if name duplicated within the team.

PATCH /containers/:id

  • Body: any subset of name, containerType, volumeMl, defaultBbeMonths, isDefault, isReturnable. (isReturnable is automatically forced to false for non-keg container types.)
  • Response 200: 
    {
  "container": {
    "id": "4fb3...",
    "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
    "name": "30 L Keg",
    "containerType": "keg",
    "volumeMl": 30000,
    "defaultBbeMonths": 6,
    "isDefault": false,
    "isReturnable": true,
    "createdAt": "2025-10-08T09:20:10.000Z",
    "updatedAt": "2025-10-08T09:45:51.000Z"
  }
}
  • Errors: 400 (validation), 401 unauthorized, 403 when caller is not owner/admin, 404 when container missing, 409 on duplicate name.

DELETE /containers/:id

  • Behavior: Requires authentication and owner/admin membership on the container’s team. If the deleted container was the default, the oldest remaining container (by createdAt) is promoted automatically.
  • Response 204
  • Errors: 401 unauthorized, 403 when caller is not owner/admin, 404 when container missing.

POST /containers/remove-unused

  • Body: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7"
}
  • Behaviour: Owner/admin only. Scans the team’s containers and keeps any container referenced by pricebook items, storefront product variants, multipacks, packaging lots, order items, or order item consumption rows. Deletes the remaining containers in a single transaction; when at least one container survives and no default remains, the oldest survivor becomes the default.
  • Response 200: 
    {
  "removedCount": 3
}
  • Errors: 400 invalid payload, 401 unauthorized, 403 when caller is not owner/admin, 500 if the cleanup fails.

GET /containers/batch

  • Query Parameters: teamId (uuid, required)
  • Response 200: text/csv 
    id,name,containerType,volumeMl,defaultBbeMonths,isDefault,isReturnable
4fb3...,30 L Keg,keg,30000,6,true,true
7d91...,440 ml Can,can,440,4,false,false
  • Errors: 401 unauthorized, 403 when caller is not owner/admin.

POST /containers/batch

  • Query Parameters: teamId (uuid, required when uploading CSV/plain text)
  • Body: Either JSON (legacy) or CSV matching the GET shape. Leave id blank to create a container. Leave defaultBbeMonths blank to clear it. 
    id,name,containerType,volumeMl,defaultBbeMonths,isDefault,isReturnable
,500 ml Bottle,bottle,500,12,false,false
4fb3...,30 L Keg,keg,30000,6,true,true
  • Notes: The optional isReturnable column/field is only honoured for keg containers; all other container types are treated as one way.
  • Response 200: 
    {
  "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
  "created": [
    {
      "id": "d49e...",
      "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
      "name": "500 ml Bottle",
      "containerType": "bottle",
      "volumeMl": 500,
      "defaultBbeMonths": 12,
      "isDefault": false,
      "isReturnable": false,
      "createdAt": "2025-10-08T09:50:01.000Z",
      "updatedAt": "2025-10-08T09:50:01.000Z"
    }
  ],
  "updated": [
    {
      "id": "4fb3...",
      "teamId": "d43c046a-10a1-4f52-bd0a-9bf16f828ab7",
      "name": "30 L Keg",
      "containerType": "keg",
      "volumeMl": 30000,
      "defaultBbeMonths": 6,
      "isDefault": true,
      "isReturnable": true,
      "createdAt": "2025-10-08T09:20:10.000Z",
      "updatedAt": "2025-10-08T09:50:01.000Z"
    }
  ]
}
  • Errors: 400 (validation, empty batch, malformed CSV), 401 unauthorized, 403 when caller is not owner/admin or tries to update another team, 404 when an update id is missing, 409 on duplicate names.
⚠️ **GitHub.com Fallback** ⚠️