---
title: "Upsert a bin"
method: POST
path: "/public/v1/bins"
tags: ["Bin"]
---

# Upsert a bin

`POST /public/v1/bins`

Create or update a single bin. Pass `id` to update the matching bin; omit `id` to create a new one. A create responds 201 with the new bin; an update responds 200 with the updated bin. Both responses carry the full bin, including its server-assigned `id` and timestamps.

A bin is a named sub-location used by bin inventory tracking — packages, batches, plants, plant groups and assembly outputs are associated to a bin to record where within a location they physically sit. This endpoint only names and renames the bin itself; it never moves, creates, or consumes inventory, and it does not change which packages, batches or plants are associated to a bin. Renaming a bin is reflected everywhere that bin is already referenced.

Names are unique per company, case-insensitively — `Cooler` and `cooler` collide — and cannot contain commas. A create or update that would collide with an existing name, or that includes a comma, is rejected with a 400 and a human-readable message.

Bins only exist for companies that have bin inventory tracking enabled; if it is disabled the request is rejected. Updates are scoped to your company — an `id` for a bin you do not own is treated as not found.

Required permission: `settings_permissions_bins`.

## Request body

- object
  - `id` string — The bin's ID. Provide it to update that bin (only `name` can change); omit it to create a new bin. An ID for a bin outside your company returns 404.
  - `name` string, required — The bin's name. Required on both create and update. Must be unique within your company (compared case-insensitively) and cannot contain a comma; violating either returns a 400. This is the only editable field on update.

## Response `200`

The updated bin

## Other responses

- `201` — The created bin
- `400` — Invalid parameters
- `401` — Missing or invalid API token
- `403` — The API token lacks the required permission
- `404` — Not Found

---

[API](https://skmtc.dev/distru/apis/distru-api.md) · [All operations](https://skmtc.dev/distru/apis/distru-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/distru/distru-api/revisions/eb775b7b6ee0/schema)