openapi: 3.1.0 info: title: Beam API version: 1.0.0 license: name: Proprietary identifier: LicenseRef-Proprietary description: "Use the Beam API to connect your business systems to your Beam Organization.\r\nManage products and stock, submit inbound or outbound orders, and follow the\r\nwork your team performs in Beam. This API is for applications running on a server.\r\n\r\nBase URL: **`https://connect.beamtracking.com`**. Requests and responses use JSON.\r\nFor a shorter setup guide, see [Connect your own systems with the API](/en/docs/api/aan-de-slag).\r\n\r\n## Get connected\r\n\r\n1. In Beam, open **Organization settings > API keys > New API key**. You need\r\n Organization administrator access and may be asked to sign in again.\r\n2. Choose a name, the access level your integration needs, and a lifetime of\r\n 30, 90, 180 or 365 days.\r\n3. Save the key in your server's secret store. Beam shows it only once.\r\n Also copy the Organization ID from the displayed Organization path.\r\n4. Replace the placeholders below and request your locations:\r\n\r\n```bash\r\ncurl 'https://connect.beamtracking.com/v1/organizations/YOUR_ORGANIZATION_ID/locations' \\\r\n -H 'Authorization: Bearer YOUR_API_KEY'\r\n```\r\n\r\nA successful response contains an `items` array. Save the relevant `locationId`\r\nfor stock, order and task requests. An empty array means no locations were returned.\r\n\r\n## Choose an access level\r\n\r\nChoose the least access your integration needs. Each endpoint lists the access\r\nlevels that can use it.\r\n\r\n| Access level | What your integration can do |\r\n| --- | --- |\r\n| Read only | Read products, locations, inventory and orders. |\r\n| Inventory sync | Read products and locations; read and update inventory. |\r\n| Order sync | Read products, locations and inventory; read and update orders; read and manage tasks. |\r\n| Full API access | Use all operations in this reference, including creating and updating products and locations. |\r\n\r\nTask reads require **Order sync** or **Full API access**. **Read only** does not\r\ninclude task access. **Order sync** does not include inventory changes.\r\n\r\n## Authenticate and manage keys\r\n\r\nSend `Authorization: Bearer YOUR_API_KEY` with every request. A key belongs to\r\none Organization and cannot access another. Never embed it in a website or mobile\r\napp. Browser requests are not supported; call Beam from your server.\r\n\r\n- **Rotate:** creates a new key value with the same lifetime. The old value stops\r\n working immediately, so update your integration as part of the rotation.\r\n- **Disable:** stops access. **Enable** restores it, although a previously\r\n refused key can take up to five minutes to work again.\r\n- **Revoke:** permanently stops access.\r\n- **Expiry:** the key stops working at its expiry date. Beam warns 30 days ahead.\r\n\r\n## Understand the records\r\n\r\n- An **item** is a product in your catalog. `QUANTITY` tracks stock by count;\r\n `SERIALIZED` tracks individual units. The quantity endpoints here do not replace\r\n individual-unit workflows.\r\n- A **location** is a site, such as a warehouse. Inside it, **layout groups**\r\n represent floor plans (`MAP`), areas (`ZONE`) and racks (`GRID`). A **spot**\r\n identifies a storage position within a group.\r\n- An **inventory position** records stock for an item at a location and spot.\r\n- An **order** contains the goods you plan to receive or send. Its lines track\r\n planned and processed quantities.\r\n- A **task** is work to perform or review. A **batch**, also called a round,\r\n groups tasks in execution order. A **wave** groups related work.\r\n\r\nUse Beam IDs returned by the API in ID fields. Keep your own order numbers and\r\nline identifiers in `reference` and `externalReference`.\r\n\r\n## Read all pages\r\n\r\nList endpoints accept `pageSize` from 1 to 50, with a default of 25. Pass the\r\nreturned `cursor` to the next request, keeping the other filters unchanged.\r\nStop when the cursor is null or absent. Do not infer completion from the number\r\nof items in a page, and do not parse or modify a cursor.\r\n\r\nOrder lists return summaries without lines and require a location and one of\r\n`DRAFT`, `OPEN` or `IN_PROGRESS`. Save order IDs so you can retrieve individual\r\norders after completion or cancellation.\r\n\r\n## Write safely\r\n\r\nEvery write requires an `Idempotency-Key` containing a UUID. Generate a new\r\nUUID for a new request. If a request times out or needs retrying, resend the\r\nsame request with the same key. Beam returns its original result without\r\napplying the change twice. Reusing the key with a different body returns\r\n`409 IDEMPOTENCY_KEY_REUSED`.\r\n\r\nUpdates requiring `If-Match` also need the record's latest `ETag`, including\r\nquotes, such as `\"revision-3\"`. If you read a record from a list, use its\r\n`revision` to form that value. A conflicting update returns `409`: read the\r\nrecord again, reconsider your change and submit the revised request with a new\r\nidempotency key.\r\n\r\nFor example, after reading an item's current revision:\r\n\r\n```bash\r\ncurl -X PATCH 'https://connect.beamtracking.com/v1/organizations/YOUR_ORGANIZATION_ID/items/YOUR_ITEM_ID' \\\r\n -H 'Authorization: Bearer YOUR_API_KEY' \\\r\n -H 'Content-Type: application/json' \\\r\n -H 'Idempotency-Key: 76df4c54-592e-4a89-90aa-3812a140a08d' \\\r\n -H 'If-Match: \"revision-3\"' \\\r\n -d '{\"name\":\"Black folding chair\"}'\r\n```\r\n\r\nReplace the IDs, key and revision with your own values, and generate a new UUID\r\nfor your request. The examples throughout this reference use fictional data.\r\n\r\n**Stock corrections set a total**, rather than add a quantity. Setting `quantity`\r\nto 120 means 120 units, not 120 extra units. Use the inventory-move endpoint\r\nwhen goods actually move between locations.\r\n\r\n**Order updates replace the whole plan.** Include every intended line. Omitting\r\nan existing unexecuted line cancels it. Do not split one plan across requests.\r\nWork already performed can prevent a requested change.\r\n\r\n## Follow background processing\r\n\r\nSome writes are accepted before all work has finished:\r\n\r\n- **Orders:** `202` means the plan is processing. The response contains\r\n `activeJobId` and an empty `lines` array. Poll the get-order endpoint using\r\n the order ID and location until `activeJobId` is null or absent, then check\r\n the actual lines and status. Further writes during processing return `ORDER_BUSY`.\r\n- **Batch edits:** even a `200` response can contain a `job`. Read the returned\r\n task again and check `authorityJobId`; read the batch's remaining steps to\r\n inspect the result. For moves, check both the source and destination batches.\r\n- **Batch cancellation:** `childrenComplete: false` means processing continues.\r\n Read the batch task until cancellation finishes and inspect member statuses.\r\n\r\nThere is no job-status endpoint in this reference. Do not treat acceptance,\r\na partial member list or the disappearance of a background-work ID alone as\r\nproof that your intended result was achieved. Check the resulting records.\r\nPoll with a delay, respect the rate limit and set an application timeout. If\r\nprocessing does not finish, contact Beam support with the record ID, any job ID\r\nand the request ID; avoid repeatedly submitting the same change with new keys.\r\n\r\n## Handle errors\r\n\r\nMost errors use `application/problem+json` with a stable `code`, an HTTP `status`,\r\na `title` and a `requestId`. Optional `detail` provides more context. Use `code`\r\nfor program logic and include `requestId` when contacting Beam support.\r\nSome authentication failures instead return `application/json` with `message`.\r\n\r\n| Status | What to do |\r\n| --- | --- |\r\n| `400` | Check required fields, formats and allowed values (`VALIDATION_FAILED`). |\r\n| `401` | Add the Authorization header. The body is `{\"message\":\"Unauthorized\"}`. |\r\n| `403` | Check the key's validity, access level and Organization. The body can be `{\"message\":\"Forbidden\"}` or a problem response with `FORBIDDEN`. |\r\n| `404` | Check the record ID and its Organization and location. |\r\n| `409` | Read `code`, refresh the affected records and resolve the conflict before retrying. |\r\n| `413` | Reduce the body size (`PAYLOAD_TOO_LARGE`). Do not split a complete order plan across requests. |\r\n| `429` | Wait for the seconds specified in `Retry-After` (`RATE_LIMITED`). |\r\n| `503` | Retry after the delay in `Retry-After` (`DEPENDENCY_UNAVAILABLE`). |\r\n\r\n## Limits and compatibility\r\n\r\n- Each API key allows 20 requests per second, with bursts of up to 100.\r\n- Retry `429` and `503` with increasing delays and honor `Retry-After`.\r\n Reuse the original idempotency key when retrying a write.\r\n- Request bodies are limited to 256 KiB. JSON field names use camelCase.\r\n- Optional response fields and new endpoints can be added within this API\r\n version. Ignore response fields you do not recognize.\r\n- This API does not provide webhooks or streaming. Poll the records you need\r\n at an interval that fits your use case and the rate limit.\r\n" x-logo: url: /logo/beam_logo_text.svg href: /en/docs/api altText: Beam servers: - url: https://connect.beamtracking.com description: Production security: - beamApiKey: [] tags: - name: Catalog description: Products, sites and storage layouts. - name: Inventory description: Read stock, correct quantities and record movements between locations. - name: Orders description: Create inbound and outbound orders, update their plans and follow progress. - name: Tasks description: Create and follow work, and group tasks into ordered batches. paths: /v1/organizations/{organizationId}/items: parameters: - $ref: '#/components/parameters/OrganizationId' get: tags: - Catalog operationId: listItems summary: List items x-beam-permission: catalog:read parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/ItemPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve the items in your Organization. An item describes a product, such as a folding chair; it is not an individual physical unit. Follow `cursor` to retrieve all pages. **Access levels:** Read only, Inventory sync, Order sync, Full API access. post: tags: - Catalog operationId: createItem summary: Create an item x-beam-permission: catalog:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ItemCreate' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Item' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Create a product before adding its stock or using it in an order. Supply its article code, name and tracking mode. Save the returned `itemId` for subsequent requests. **Access levels:** Full API access. /v1/organizations/{organizationId}/items/{itemId}: parameters: - $ref: '#/components/parameters/OrganizationId' - name: itemId in: path required: true schema: $ref: '#/components/schemas/Identifier' get: tags: - Catalog operationId: getItem summary: Get an item x-beam-permission: catalog:read responses: '200': description: Requested records and their current state. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Item' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve an item by its Beam ID. Save the response's `ETag` if you intend to update it. **Access levels:** Read only, Inventory sync, Order sync, Full API access. patch: tags: - Catalog operationId: updateItem summary: Update an item description: |- Change the supplied item fields; omitted fields keep their current values. Send the `ETag` from your last read in `If-Match`. Sending values that already match the item returns its current revision without changing it. Use a new `Idempotency-Key` for each new request, even if the previous request left the item unchanged; reuse a key only to retry that same request. **Access levels:** Full API access. x-beam-permission: catalog:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ItemUpdate' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Item' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/locations: parameters: - $ref: '#/components/parameters/OrganizationId' get: tags: - Catalog operationId: listLocations summary: List locations x-beam-permission: locations:read parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/LocationPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve your Organization's sites, such as warehouses or branches. Storage areas, racks and shelf positions within a site are layout groups and spots. Follow `cursor` to retrieve all pages. **Access levels:** Read only, Inventory sync, Order sync, Full API access. post: tags: - Catalog operationId: createLocation summary: Create a location x-beam-permission: locations:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocationCreate' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Location' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Create a site with a code and name. To place it beneath another location, supply `parentLocationId`. Use layout groups and spots for storage positions within a site. **Access levels:** Full API access. /v1/organizations/{organizationId}/locations/{locationId}: parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LocationId' get: tags: - Catalog operationId: getLocation summary: Get a location x-beam-permission: locations:read responses: '200': description: Requested records and their current state. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Location' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve a location by its Beam ID. Save its `ETag` before updating it. Check `status` to see whether the location is active. **Access levels:** Read only, Inventory sync, Order sync, Full API access. patch: tags: - Catalog operationId: updateLocation summary: Update a location x-beam-permission: locations:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocationUpdate' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Location' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Update the location's name or parent. Omitted fields keep their current values. Send its latest `ETag` in `If-Match`. **Access levels:** Full API access. /v1/organizations/{organizationId}/locations/{locationId}/spot-groups: parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LocationId' get: tags: - Catalog operationId: listSpotGroups summary: List layout groups x-beam-permission: locations:read parameters: - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/SpotGroupPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve the floor plans, areas and racks within a location. A `MAP` represents a floor plan, a `ZONE` an area and a `GRID` a rack. Follow `cursor` to retrieve all pages. **Access levels:** Read only, Inventory sync, Order sync, Full API access. post: tags: - Catalog operationId: createSpotGroup summary: Create a layout group x-beam-permission: locations:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpotGroupCreate' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/SpotGroup' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Add a floor plan (`MAP`), area (`ZONE`) or rack (`GRID`) to a location. Supply `parentSpotGroupId` when the group belongs inside another group. Use the returned `spotGroupId` when creating storage spots. **Access levels:** Full API access. /v1/organizations/{organizationId}/locations/{locationId}/spot-groups/{spotGroupId}: parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LocationId' - $ref: '#/components/parameters/SpotGroupId' patch: tags: - Catalog operationId: updateSpotGroup summary: Update a layout group x-beam-permission: locations:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpotGroupUpdate' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/SpotGroup' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Update the supplied layout-group fields. Obtain the group's current `revision` from the layout-group listing and send it as `If-Match: "revision-"`. **Access levels:** Full API access. /v1/organizations/{organizationId}/locations/{locationId}/spots: parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LocationId' get: tags: - Catalog operationId: listSpots summary: List storage spots x-beam-permission: locations:read parameters: - $ref: '#/components/parameters/SpotGroupIdQuery' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/SpotPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve storage positions within a location. Supply `spotGroupId` to restrict the result to one layout group. Follow `cursor` to retrieve all pages. **Access levels:** Read only, Inventory sync, Order sync, Full API access. post: tags: - Catalog operationId: createSpot summary: Create a storage spot x-beam-permission: locations:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpotCreate' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Spot' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Add a named storage position to an existing layout group. Save the returned `spotId` to identify stock held there. **Access levels:** Full API access. /v1/organizations/{organizationId}/locations/{locationId}/spots/{spotId}: parameters: - $ref: '#/components/parameters/OrganizationId' - $ref: '#/components/parameters/LocationId' - $ref: '#/components/parameters/SpotId' patch: tags: - Catalog operationId: updateSpot summary: Update a storage spot x-beam-permission: locations:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SpotUpdate' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Spot' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Update the supplied label, code, barcode or layout details. Obtain the spot's current `revision` from the spot listing and send it as `If-Match: "revision-"`. **Access levels:** Full API access. /v1/organizations/{organizationId}/inventory-positions: parameters: - $ref: '#/components/parameters/OrganizationId' get: tags: - Inventory operationId: listInventoryPositions summary: List inventory positions x-beam-permission: inventory:read parameters: - $ref: '#/components/parameters/LocationIdQuery' - $ref: '#/components/parameters/ItemIdQuery' - $ref: '#/components/parameters/SpotIdQuery' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/InventoryPositionPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Read stock at the required `locationId`. With no item or spot filter, follow `cursor` to retrieve the location's positions. Supplying `itemId` without `spotId` returns only that item's default storage position, not all its stock across spots. Supply both IDs to read that item at a specific spot, or list the location's positions to find all spots. **Access levels:** Read only, Inventory sync, Order sync, Full API access. post: tags: - Inventory operationId: createInventoryPosition summary: Create an inventory position x-beam-permission: inventory:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InventoryPositionCreate' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/InventoryPosition' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Create a stock record for an item at a location, optionally at a specific storage spot. The initial quantity is zero. Save its `positionId` and `ETag`, then use the quantity endpoint to set its stock level. **Access levels:** Inventory sync, Full API access. /v1/organizations/{organizationId}/inventory-positions/{positionId}/quantity: parameters: - $ref: '#/components/parameters/OrganizationId' - name: positionId in: path required: true schema: $ref: '#/components/schemas/Identifier' put: tags: - Inventory operationId: reconcileInventoryQuantity summary: Set an inventory quantity x-beam-permission: inventory:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InventoryQuantity' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/InventoryPosition' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Set the position to the supplied total quantity, rather than adding or subtracting that amount. Include a reason and the current `ETag` in `If-Match`. Use this to correct stock records; use the inventory-move endpoint when goods physically move between locations. **Access levels:** Inventory sync, Full API access. /v1/organizations/{organizationId}/inventory-moves: parameters: - $ref: '#/components/parameters/OrganizationId' post: tags: - Inventory operationId: moveInventory summary: Move inventory between locations description: |- Record a physical movement of stock from one location's default storage position to another's. Source and destination locations must differ. Read both inventory positions first and supply their current revisions in `expectedSourceRevision` and `expectedDestinationRevision`. Beam updates both positions together and returns them. Do not simulate a movement with two separate quantity corrections. Use a quantity correction if you are only correcting a record. **Access levels:** Inventory sync, Full API access. x-beam-permission: inventory:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InventoryMove' responses: '200': description: Updated record or records. content: application/json: schema: $ref: '#/components/schemas/InventoryMoveResult' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/orders: parameters: - $ref: '#/components/parameters/OrganizationId' get: tags: - Orders operationId: listOrders summary: List orders x-beam-permission: orders:read parameters: - $ref: '#/components/parameters/LocationIdQuery' - name: status in: query required: true schema: type: string enum: - DRAFT - OPEN - IN_PROGRESS - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/OrderPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve order summaries for a location and one required status: `DRAFT`, `OPEN` or `IN_PROGRESS`. The list does not include order lines or support filtering for completed or cancelled orders. Retrieve a known order by ID to read its lines or follow it after completion. **Access levels:** Read only, Order sync, Full API access. post: tags: - Orders operationId: createOrder summary: Create an order x-beam-permission: orders:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderPlan' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Order' '202': description: Order accepted for background processing. The response has activeJobId set and an empty lines array. Read the order again to check progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Create an inbound or outbound order with its complete list of planned lines. Use your system's order reference and a stable `externalReference` for each line. A `201` response contains the order; a `202` response means processing continues in the background. Follow the background-processing guidance before making another change. **Access levels:** Order sync, Full API access. /v1/organizations/{organizationId}/orders/{orderId}: parameters: - $ref: '#/components/parameters/OrganizationId' - name: orderId in: path required: true schema: $ref: '#/components/schemas/Identifier' get: tags: - Orders operationId: getOrder summary: Get an order x-beam-permission: orders:read parameters: - $ref: '#/components/parameters/LocationIdQuery' responses: '200': description: Requested records and their current state. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve a known order using its `orderId` and `locationId`, including its lines and current status. Save its `ETag` before changing the plan. After a `202` response, poll this endpoint until `activeJobId` is empty, then check the resulting lines and status. **Access levels:** Read only, Order sync, Full API access. put: tags: - Orders operationId: reconcileOrderPlan summary: Update an order's complete plan description: |- Send the complete desired order plan, not just changed lines. An unexecuted line omitted from the plan is cancelled, so do not split one plan across requests. Include the current `ETag` in `If-Match`. Changes remain subject to work already performed on the order. An unchanged plan can return the current revision or be accepted for background processing (`202`). Whitespace and country-code case are normalized before comparison. Use a new `Idempotency-Key` for a changed request; reuse a key only to retry the same request. **Access levels:** Order sync, Full API access. x-beam-permission: orders:write parameters: - $ref: '#/components/parameters/LocationIdQuery' - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/OrderPlan' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Order' '202': description: Order accepted for background processing. The response has activeJobId set and an empty lines array. Read the order again to check progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Order' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/tasks: parameters: - $ref: '#/components/parameters/OrganizationId' post: tags: - Tasks operationId: createTask summary: Create a task description: |- Create work that a person needs to review or carry out, linked to an item, location, inventory position or order. Supply a clear title and the target's Beam ID. Order-line picking and receiving tasks are managed by Beam; creating duplicate order work is refused with `TASK_ACTIVE_WORK_EXISTS`. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskPlan' responses: '201': description: Record created. Save its ID for subsequent requests. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Task' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/tasks/{taskId}: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' get: tags: - Tasks operationId: getTask summary: Get a task description: |- Read a task's status, assignment and current revision. Supply the `locationId` used when it was created. Save its `ETag` before changing it. For a batch, this also lets you check whether background work still holds it through `authorityJobId`. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/LocationIdQuery' responses: '200': description: Requested records and their current state. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Task' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Problem' default: $ref: '#/components/responses/Problem' patch: tags: - Tasks operationId: transitionTask summary: Update a task's status or assignment description: |- Change a task to `OPEN`, `ASSIGNED`, `IN_PROGRESS` or `CANCELLED`, subject to its current state. `ASSIGNED` and `IN_PROGRESS` assign or start work for the API client making the request. Stock actions require ownership of the task or its batch. Completing physical work completes its task; this endpoint cannot set `COMPLETED`. A task already in an active batch follows that batch. For a batch that has not been claimed, `CANCELLED` with `parentTaskId: null` cancels and removes the task. `OPEN` with `parentTaskId: null` removes it as standalone work only while its order remains open; otherwise Beam returns `TASK_ORDER_CLOSED`. Supply its location and current `ETag`. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskTransition' responses: '200': description: Updated record or records. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/Task' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/tasks/{taskId}/cancel-batch: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' post: tags: - Tasks operationId: cancelTaskBatch summary: Cancel a task batch description: |- Cancel a batch using its latest `ETag` and `batchRevision`. Choose `RELEASE_MEMBERS` to return its tasks to standalone open work, or `CANCEL_MEMBERS` to cancel them. Tasks belonging to an already closed order follow that order's outcome; inspect their individual statuses. A `200` response with `childrenComplete: false` means cancellation is still processing. The batch remains open while that work runs. Read the batch task again to follow completion; do not treat HTTP success alone as completed cancellation. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskBatchCancellation' responses: '200': description: Request accepted. Check the returned state; background processing may still be in progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/TaskBatchTransition' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/orders/{orderId}/line-work: parameters: - $ref: '#/components/parameters/OrganizationId' - name: orderId in: path required: true schema: $ref: '#/components/schemas/Identifier' get: tags: - Tasks operationId: orderLineWork summary: Get tasks for order lines x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/LocationIdQuery' - $ref: '#/components/parameters/PageSize' - $ref: '#/components/parameters/Cursor' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/OrderLineWorkPage' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' description: |- Retrieve a page of order lines with their tasks and the batches they belong to. A batch is a group of tasks performed as one round of work. A line's task can be null if work has not yet started. Follow `cursor` to retrieve all pages. **Access levels:** Order sync, Full API access. /v1/organizations/{organizationId}/task-batch-policy: parameters: - $ref: '#/components/parameters/OrganizationId' get: tags: - Tasks operationId: taskBatchPolicy summary: Get task-batch limits description: |- Read the maximum batch size, the number of members allowed in one edit, the number that may be created in one edit, and the allowed task kinds. Check these limits before assembling or changing a batch; they can differ from the maximum sizes in the schemas. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/LocationIdQuery' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/TaskBatchPolicy' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/task-batches: parameters: - $ref: '#/components/parameters/OrganizationId' post: tags: - Tasks operationId: assembleTaskBatch summary: Create a task batch description: |- Group existing open tasks and new tasks into one ordered batch. Each member identifies either an existing task and its current revision, or the work to create. Read the task-batch policy first and keep the request within its limits. When `job` is present in the response, the batch is still being prepared and cannot start yet. Follow the background-processing guidance and check the resulting task and steps. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskBatchAssembly' responses: '200': description: Request accepted. Check the returned state; background processing may still be in progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/TaskBatchEdit' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/task-batches/{taskId}/members: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' post: tags: - Tasks operationId: addTaskBatchMembers summary: Add tasks to a batch description: |- Add existing or new tasks to a batch that has not been claimed. Omit placement fields to append, or provide `beforeTaskId` or `afterTaskId` to place them next to a member. Read the policy limits first. An imported batch accepts additions only from the integration that created it, and only picking tasks. An integration cannot change an order of work that a person has fixed. A response containing `job` means processing continues. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskBatchAddition' responses: '200': description: Request accepted. Check the returned state; background processing may still be in progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/TaskBatchEdit' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/task-batches/{taskId}/detach: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' post: tags: - Tasks operationId: detachTaskBatchMembers summary: Remove tasks from a batch description: |- Remove open tasks from a batch and return them to standalone work. Use `KEEP_WAVE` to keep them in the same work wave, or `LEAVE_WAVE` to remove that grouping. A task whose step is running cannot be detached until that step finishes. A response containing `job` means processing continues. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskBatchDetachment' responses: '200': description: Request accepted. Check the returned state; background processing may still be in progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/TaskBatchEdit' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/task-batches/{taskId}/move: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' post: tags: - Tasks operationId: moveTaskBatchMembers summary: Move tasks to another batch description: |- Move open tasks to a destination batch that has not been claimed. Supply the current source and destination revisions and each member's revision. Each task is removed from its old batch and added to the new one together. A response containing `job` means processing continues; check both batches afterward. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskBatchMove' responses: '200': description: Request accepted. Check the returned state; background processing may still be in progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/TaskBatchEdit' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/task-batches/{taskId}/reorder: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' post: tags: - Tasks operationId: reorderTaskBatchMember summary: Reorder a task within a batch description: |- Place one task before or after another task in the same batch. Supply the batch's current revisions and the member to move. An integration cannot reorder a batch whose order of work a person has fixed. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/IfMatch' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TaskBatchReorder' responses: '200': description: Request accepted. Check the returned state; background processing may still be in progress. headers: ETag: $ref: '#/components/headers/ETag' content: application/json: schema: $ref: '#/components/schemas/TaskBatchEdit' '400': $ref: '#/components/responses/Problem' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' default: $ref: '#/components/responses/Problem' /v1/organizations/{organizationId}/task-batches/{taskId}/steps: parameters: - $ref: '#/components/parameters/OrganizationId' - name: taskId in: path required: true schema: $ref: '#/components/schemas/Identifier' get: tags: - Tasks operationId: listTaskBatchSteps summary: List remaining tasks in a batch description: |- Retrieve remaining tasks in execution order. Completed or cancelled members are not included. Follow `cursor` for more pages. If membership or order changes during pagination, Beam returns `TASK_BATCH_ORDER_CHANGED`; discard the cursor and restart from the first page. **Access levels:** Order sync, Full API access. x-beam-permission: tasks:write parameters: - $ref: '#/components/parameters/LocationIdQuery' - $ref: '#/components/parameters/Cursor' - $ref: '#/components/parameters/PageSize' responses: '200': description: Requested records and their current state. content: application/json: schema: $ref: '#/components/schemas/TaskBatchStepPage' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/Problem' default: $ref: '#/components/responses/Problem' components: securitySchemes: beamApiKey: type: http scheme: bearer bearerFormat: Beam API key description: 'The API key created in Beam: `Authorization: Bearer `.' parameters: OrganizationId: name: organizationId in: path required: true schema: $ref: '#/components/schemas/Identifier' description: Your Beam Organization ID, shown in the Organization path when you create an API key. LocationId: name: locationId in: path required: true schema: $ref: '#/components/schemas/Identifier' description: The Beam location ID returned by the locations endpoint. SpotGroupId: name: spotGroupId in: path required: true schema: $ref: '#/components/schemas/Identifier' description: The Beam layout-group ID returned when listing or creating groups. SpotId: name: spotId in: path required: true schema: $ref: '#/components/schemas/Identifier' description: The Beam storage-spot ID returned when listing or creating spots. SpotGroupIdQuery: name: spotGroupId in: query schema: $ref: '#/components/schemas/Identifier' description: Restrict results to this layout group. SpotIdQuery: name: spotId in: query schema: $ref: '#/components/schemas/Identifier' description: Restrict results to this storage spot. LocationIdQuery: name: locationId in: query required: true schema: $ref: '#/components/schemas/Identifier' description: The location containing the records. Required even when an individual order or task ID is supplied. ItemIdQuery: name: itemId in: query schema: $ref: '#/components/schemas/Identifier' description: Item to read. Without `spotId`, the inventory endpoint returns only this item's default storage position. Cursor: name: cursor in: query schema: type: string maxLength: 4096 description: The cursor returned by the previous page. Omit for the first page. Keep other filters unchanged and do not interpret or modify the cursor. PageSize: name: pageSize in: query schema: type: integer minimum: 1 maximum: 50 default: 25 description: Maximum number of records to request per page, from 1 to 50. Defaults to 25. IdempotencyKey: name: Idempotency-Key in: header required: true schema: type: string format: uuid description: A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request. IfMatch: name: If-Match in: header required: true schema: type: string pattern: ^"revision-[1-9][0-9]*"$ description: The latest ETag of the record, including quotes, for example `"revision-3"`. If using a list result, format its `revision` as `"revision-"`. headers: ETag: description: The record's revision, for example `"revision-3"`. Send this value unchanged in `If-Match` when updating the record. schema: type: string pattern: ^"revision-[1-9][0-9]*"$ responses: Problem: description: The request could not be completed. Use `code` to choose the next action and include `requestId` when contacting Beam support. Authentication failures may instead return a JSON object containing `message`. headers: Retry-After: description: Seconds to wait before retrying a rate-limited or temporarily unavailable request. schema: type: integer minimum: 1 content: application/problem+json: schema: $ref: '#/components/schemas/Problem' Unauthorized: description: The Authorization header is missing. content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: message: Unauthorized Forbidden: description: The API key is invalid, expired, disabled or revoked (`application/json`), or it lacks this route's permission or access to this Organization (`application/problem+json`). content: application/json: schema: $ref: '#/components/schemas/GatewayError' example: message: Forbidden application/problem+json: schema: $ref: '#/components/schemas/Problem' schemas: Identifier: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$ Epc: description: A container's Electronic Product Code (EPC), in uppercase. Dot and colon characters are allowed for GS1 URN values. type: string pattern: ^[A-Z0-9][A-Z0-9._:-]{2,127}$ RevisionFields: type: object required: - revision - createdAt - updatedAt properties: revision: type: integer minimum: 1 createdAt: type: string format: date-time updatedAt: type: string format: date-time OperationalRevisionFields: type: object required: - revision - updatedAt properties: revision: type: integer minimum: 1 createdAt: type: string format: date-time updatedAt: type: string format: date-time Item: allOf: - $ref: '#/components/schemas/OperationalRevisionFields' - type: object required: - organizationId - itemId - name - articleCode - trackingMode - status properties: organizationId: $ref: '#/components/schemas/Identifier' itemId: $ref: '#/components/schemas/Identifier' name: type: string minLength: 1 maxLength: 256 articleCode: type: string minLength: 1 maxLength: 128 productCode: type: - string - 'null' maxLength: 128 sku: type: - string - 'null' maxLength: 128 barcode: type: - string - 'null' maxLength: 128 category: type: - string - 'null' maxLength: 128 subCategory: type: - string - 'null' maxLength: 128 trackingMode: type: string enum: - QUANTITY - SERIALIZED description: '`QUANTITY` tracks a total count; `SERIALIZED` tracks individual units. The quantity-write endpoints in this reference are for quantity stock, not individual-unit movements.' status: type: string enum: - ACTIVE - ARCHIVED description: A product in your catalog. Use its Beam `itemId` in inventory and order requests. examples: - organizationId: org_example itemId: item_chair name: Folding chair articleCode: CHAIR-001 trackingMode: QUANTITY status: ACTIVE revision: 1 createdAt: '2026-11-05T09:00:00Z' updatedAt: '2026-11-05T09:00:00Z' ItemCreate: type: object additionalProperties: false required: - name - articleCode - trackingMode properties: name: type: string minLength: 1 maxLength: 256 articleCode: type: string minLength: 1 maxLength: 128 productCode: type: - string - 'null' maxLength: 128 sku: type: - string - 'null' maxLength: 128 barcode: type: - string - 'null' maxLength: 128 category: type: - string - 'null' maxLength: 128 subCategory: type: - string - 'null' maxLength: 128 trackingMode: type: string enum: - QUANTITY - SERIALIZED description: Choose `QUANTITY` for stock tracked by count or `SERIALIZED` for individually identified units. examples: - name: Folding chair articleCode: CHAIR-001 trackingMode: QUANTITY sku: CHAIR-BLACK ItemUpdate: type: object additionalProperties: false minProperties: 1 properties: name: type: string minLength: 1 maxLength: 256 productCode: type: - string - 'null' maxLength: 128 sku: type: - string - 'null' maxLength: 128 barcode: type: - string - 'null' maxLength: 128 category: type: - string - 'null' maxLength: 128 subCategory: type: - string - 'null' maxLength: 128 examples: - name: Black folding chair ItemPage: type: object required: - items properties: items: type: array maxItems: 50 items: $ref: '#/components/schemas/Item' cursor: type: - string - 'null' maxLength: 4096 Location: allOf: - $ref: '#/components/schemas/OperationalRevisionFields' - type: object required: - organizationId - locationId - code - name - status properties: organizationId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' code: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 256 parentLocationId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' status: type: string enum: - PROVISIONING - UPDATING - ACTIVE - ARCHIVING - SUSPENDED - ARCHIVED description: A site, such as a warehouse or branch. Use layout groups and spots for storage areas within it. examples: - organizationId: org_example locationId: loc_warehouse code: WH-01 name: Main warehouse status: ACTIVE revision: 1 createdAt: '2026-11-05T09:00:00Z' updatedAt: '2026-11-05T09:00:00Z' LocationCreate: type: object additionalProperties: false required: - code - name properties: code: type: string minLength: 1 maxLength: 128 name: type: string minLength: 1 maxLength: 256 parentLocationId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' examples: - code: WH-01 name: Main warehouse LocationUpdate: type: object additionalProperties: false minProperties: 1 properties: name: type: string minLength: 1 maxLength: 256 parentLocationId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' LocationPage: type: object required: - items properties: items: type: array maxItems: 50 items: $ref: '#/components/schemas/Location' cursor: type: - string - 'null' maxLength: 4096 SpotGroup: allOf: - $ref: '#/components/schemas/OperationalRevisionFields' - type: object required: - organizationId - locationId - spotGroupId - mapGroupId - groupType - name - status properties: organizationId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' spotGroupId: $ref: '#/components/schemas/Identifier' parentSpotGroupId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' mapGroupId: $ref: '#/components/schemas/Identifier' groupType: type: string minLength: 1 maxLength: 64 description: 'The layout-group type: `MAP` for a floor plan, `ZONE` for an area or `GRID` for a rack. Existing data can also contain the deprecated values `HEADER`, `SECTION` or `RACK`.' name: type: string minLength: 1 maxLength: 256 code: type: - string - 'null' maxLength: 128 barcode: type: - string - 'null' maxLength: 128 attributes: $ref: '#/components/schemas/LayoutJsonNullable' sortOrder: type: - integer - 'null' status: type: string enum: - ACTIVE - ARCHIVED description: A floor plan, area or rack within a location. A spot belongs to a layout group. SpotGroupType: type: string enum: - MAP - ZONE - GRID - HEADER description: Use `MAP` for a floor plan, `ZONE` for an area and `GRID` for a rack. `HEADER` is deprecated; do not use it for new layouts. LayoutJson: type: object maxProperties: 50 additionalProperties: true description: Layout details as a JSON object. Use the supported layout structure for your Beam setup; an arbitrary object is not a guarantee that the layout is valid. LayoutJsonNullable: oneOf: - $ref: '#/components/schemas/LayoutJson' - type: 'null' SpotGroupPage: type: object required: - items properties: items: type: array maxItems: 50 items: $ref: '#/components/schemas/SpotGroup' cursor: type: - string - 'null' maxLength: 4096 SpotGroupCreate: type: object additionalProperties: false required: - groupType - name properties: parentSpotGroupId: $ref: '#/components/schemas/Identifier' groupType: $ref: '#/components/schemas/SpotGroupType' name: type: string minLength: 1 maxLength: 256 code: type: string minLength: 1 maxLength: 128 attributes: $ref: '#/components/schemas/LayoutJson' sortOrder: type: integer SpotGroupUpdate: type: object additionalProperties: false minProperties: 1 properties: name: type: string minLength: 1 maxLength: 256 parentSpotGroupId: $ref: '#/components/schemas/Identifier' groupType: $ref: '#/components/schemas/SpotGroupType' attributes: $ref: '#/components/schemas/LayoutJson' sortOrder: type: integer Spot: allOf: - $ref: '#/components/schemas/OperationalRevisionFields' - type: object required: - organizationId - locationId - spotGroupId - spotId - label - isDefault - status properties: organizationId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' spotGroupId: $ref: '#/components/schemas/Identifier' mapGroupId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' spotId: $ref: '#/components/schemas/Identifier' label: type: string minLength: 1 maxLength: 256 code: type: - string - 'null' maxLength: 128 barcode: type: - string - 'null' maxLength: 128 coordinates: $ref: '#/components/schemas/LayoutJsonNullable' attributes: $ref: '#/components/schemas/LayoutJsonNullable' isDefault: type: boolean status: type: string enum: - ACTIVE - ARCHIVED description: A storage position within a layout group, such as a shelf compartment. SpotPage: type: object required: - items properties: items: type: array maxItems: 250 items: $ref: '#/components/schemas/Spot' cursor: type: - string - 'null' maxLength: 4096 SpotCreate: type: object additionalProperties: false required: - spotGroupId - label properties: spotGroupId: $ref: '#/components/schemas/Identifier' label: type: string minLength: 1 maxLength: 256 code: type: string minLength: 1 maxLength: 128 barcode: type: string minLength: 1 maxLength: 128 coordinates: $ref: '#/components/schemas/LayoutJson' attributes: $ref: '#/components/schemas/LayoutJson' SpotUpdate: type: object additionalProperties: false minProperties: 1 properties: label: type: string minLength: 1 maxLength: 256 code: type: string minLength: 1 maxLength: 128 barcode: type: string minLength: 1 maxLength: 128 coordinates: $ref: '#/components/schemas/LayoutJson' attributes: $ref: '#/components/schemas/LayoutJson' InventoryPosition: allOf: - $ref: '#/components/schemas/OperationalRevisionFields' - type: object required: - organizationId - positionId - itemId - locationId - quantity - availableQuantity - status - unitOfMeasure properties: organizationId: $ref: '#/components/schemas/Identifier' positionId: $ref: '#/components/schemas/Identifier' itemId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' spotId: $ref: '#/components/schemas/Identifier' spotGroupId: $ref: '#/components/schemas/Identifier' isUnplaced: type: boolean description: Whether the stock has no specific assigned storage spot. quantity: type: integer minimum: 0 description: Total recorded stock quantity at this position. availableQuantity: type: integer minimum: 0 description: Quantity available for use, which can differ from the total stock quantity. status: type: string enum: - ACTIVE - ARCHIVED unitOfMeasure: type: string minLength: 1 maxLength: 32 description: Stock for an item at a location and storage spot. Use `positionId` to update its quantity. examples: - organizationId: org_example positionId: pos_chair itemId: item_chair locationId: loc_warehouse quantity: 120 availableQuantity: 120 unitOfMeasure: pcs status: ACTIVE revision: 2 updatedAt: '2026-11-05T09:05:00Z' InventoryPositionPage: type: object required: - items properties: items: type: array maxItems: 50 items: $ref: '#/components/schemas/InventoryPosition' cursor: type: - string - 'null' maxLength: 4096 InventoryPositionCreate: type: object additionalProperties: false required: - itemId - locationId - unitOfMeasure properties: itemId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' spotId: $ref: '#/components/schemas/Identifier' description: Storage spot for this stock. If omitted, Beam uses the location's default spot. unitOfMeasure: type: string minLength: 1 maxLength: 32 description: Unit used for quantities, for example `pcs`. Use a consistent unit for the item and its stock. examples: - itemId: item_chair locationId: loc_warehouse unitOfMeasure: pcs InventoryMove: type: object additionalProperties: false required: - itemId - sourceLocationId - destinationLocationId - quantity - expectedSourceRevision - expectedDestinationRevision - reason properties: itemId: $ref: '#/components/schemas/Identifier' sourceLocationId: $ref: '#/components/schemas/Identifier' destinationLocationId: $ref: '#/components/schemas/Identifier' quantity: type: integer minimum: 1 maximum: 2147483647 expectedSourceRevision: type: integer minimum: 1 maximum: 2147483647 expectedDestinationRevision: type: integer minimum: 1 maximum: 2147483647 reason: type: string minLength: 1 maxLength: 256 description: A physical stock movement between locations. Read both positions first to obtain their revisions. examples: - itemId: item_chair sourceLocationId: loc_warehouse destinationLocationId: loc_shop quantity: 10 expectedSourceRevision: 2 expectedDestinationRevision: 1 reason: Restock the shop InventoryMoveResult: type: object additionalProperties: false required: - source - destination properties: source: $ref: '#/components/schemas/InventoryPosition' destination: $ref: '#/components/schemas/InventoryPosition' InventoryQuantity: type: object additionalProperties: false required: - itemId - locationId - quantity - reason properties: itemId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' spotId: $ref: '#/components/schemas/Identifier' description: Storage spot of the position being corrected. Use the same item, location and spot as the target position. quantity: type: integer minimum: 0 maximum: 2147483647 reason: type: string minLength: 1 maxLength: 256 description: An absolute stock quantity and the reason for the correction. This replaces the quantity; it is not a delta. examples: - itemId: item_chair locationId: loc_warehouse quantity: 120 reason: Confirmed stock count AddressSnapshot: type: object additionalProperties: false required: - line1 - city - postalCode - countryCode properties: line1: type: string minLength: 1 maxLength: 256 line2: type: - string - 'null' maxLength: 256 city: type: string minLength: 1 maxLength: 128 region: type: - string - 'null' maxLength: 128 postalCode: type: string minLength: 1 maxLength: 32 countryCode: type: string pattern: ^[A-Z]{2}$ CounterpartySnapshot: type: object additionalProperties: false required: - reference - displayName properties: reference: type: string minLength: 1 maxLength: 128 displayName: type: string minLength: 1 maxLength: 256 ShipToSnapshot: type: object additionalProperties: false required: - name - address properties: name: type: string minLength: 1 maxLength: 256 company: type: - string - 'null' maxLength: 256 address: $ref: '#/components/schemas/AddressSnapshot' OrderLinePlan: type: object additionalProperties: false required: - externalReference - itemId - plannedQuantity - unitOfMeasure properties: externalReference: type: string minLength: 1 maxLength: 128 description: Your stable identifier for this line. Reuse it when updating the same line. itemId: $ref: '#/components/schemas/Identifier' plannedQuantity: type: integer minimum: 1 maximum: 2147483647 unitOfMeasure: type: string minLength: 1 maxLength: 32 description: One desired order line. Keep its `externalReference` stable when updating the same line. OrderPlan: type: object additionalProperties: false required: - locationId - direction - reference - counterparty - lines properties: locationId: $ref: '#/components/schemas/Identifier' direction: type: string enum: - INBOUND - OUTBOUND reference: type: string minLength: 1 maxLength: 128 description: Your order reference, such as an order number. The returned `orderId` is Beam's identifier for later requests. counterparty: $ref: '#/components/schemas/CounterpartySnapshot' shipTo: oneOf: - $ref: '#/components/schemas/ShipToSnapshot' - type: 'null' attributes: description: Additional order information as a JSON object. When supplied, it replaces the entire attributes object; omitting it keeps the current attributes. A cancellation does not change these attributes. Beam displays `externalNumber` beside the order reference. type: object maxProperties: 50 additionalProperties: true desiredStatus: type: string enum: - DRAFT - OPEN - CANCELLED description: Use `DRAFT` to hold a plan before work starts, `OPEN` to activate a draft, or `CANCELLED` to cancel an unexecuted order. Empty plans are supported for draft or cancellation requests. Existing execution can prevent a status change. lines: description: The complete set of desired order lines, up to 80 per request. An existing unexecuted line omitted here is cancelled without a stock-shortage record. Do not split one plan across requests. Beam may accept the plan with `202` and apply it in the background. type: array minItems: 0 maxItems: 80 items: $ref: '#/components/schemas/OrderLinePlan' description: The complete desired order plan. Send all intended lines when creating or updating it. examples: - locationId: loc_warehouse direction: OUTBOUND reference: SO-2026-1042 counterparty: reference: CUSTOMER-001 displayName: Example Events desiredStatus: OPEN lines: - externalReference: SO-2026-1042-1 itemId: item_chair plannedQuantity: 10 unitOfMeasure: pcs OrderLine: allOf: - $ref: '#/components/schemas/RevisionFields' - type: object required: - lineId - externalReference - itemId - plannedQuantity - executedQuantity - unitOfMeasure - status properties: lineId: $ref: '#/components/schemas/Identifier' externalReference: type: string maxLength: 128 itemId: $ref: '#/components/schemas/Identifier' plannedQuantity: type: integer minimum: 0 executedQuantity: type: integer minimum: 0 shortQuantity: description: Quantity that could not be fulfilled, including unavailable stock and quantities left outstanding when an order was completed short. For a partly fulfilled line whose remainder is released, `plannedQuantity` can be reduced to the fulfilled quantity; this field preserves the shortage. Zero or absent when there was no shortage. Quantities removed because they were no longer needed, lines omitted from a replacement plan and open lines cancelled with an order do not count as shortages. type: - integer - 'null' minimum: 0 unitOfMeasure: type: string maxLength: 32 status: type: string enum: - PLANNED - PARTIAL - COMPLETED - CANCELLED Order: allOf: - $ref: '#/components/schemas/RevisionFields' - type: object required: - organizationId - orderId - locationId - direction - reference - status - counterparty - lines properties: organizationId: $ref: '#/components/schemas/Identifier' orderId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' direction: type: string enum: - INBOUND - OUTBOUND reference: type: string maxLength: 128 status: type: string enum: - DRAFT - OPEN - IN_PROGRESS - COMPLETED - CANCELLED counterparty: $ref: '#/components/schemas/CounterpartySnapshot' shipTo: oneOf: - $ref: '#/components/schemas/ShipToSnapshot' - type: 'null' attributes: description: Additional order information as a JSON object, or null. type: - object - 'null' additionalProperties: true goodsLifecycleVersion: description: Indicates whether goods-custody information is available. Version `1` means it is available; null means custody is unknown. Do not interpret unknown custody as zero goods outstanding. type: - integer - 'null' pendingHandoverQuantity: description: Number of picked units still awaiting handover. Completing a task does not by itself confirm that goods were handed over. type: - integer - 'null' minimum: 0 rentalStartsAt: description: Planned rental departure time in UTC, or null for other orders. This is a planning date, not confirmation that goods have departed. type: - string - 'null' format: date-time rentalEndsAt: description: Planned rental return time in UTC, or null for other orders. type: - string - 'null' format: date-time outstandingReturnQuantity: description: Number of units handed over and still expected back, for rentals or announced sales returns. Null means no return quantity has been recorded for this order; it does not mean zero outstanding. type: - integer - 'null' minimum: 0 openLineCount: description: Number of lines not yet `COMPLETED` or `CANCELLED`. Null means the count is not available; do not treat it as zero. type: - integer - 'null' minimum: 0 executionState: description: Progress of the order's work, separately from the order's `status`. Null means progress is not available. oneOf: - $ref: '#/components/schemas/OrderExecutionState' - type: 'null' shortReason: description: Reason recorded when the order was completed with a shortage. Null if its current completion did not leave a shortage. oneOf: - $ref: '#/components/schemas/OrderShortReason' - type: 'null' activeJobId: description: Identifies background work that is still changing the order. While set, further writes return `ORDER_BUSY`. Poll the order until this is null, then check the resulting state before continuing. oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' lines: description: Order lines, including cancelled lines, up to the documented response limit. A `202` response has an empty array while `activeJobId` is set; this does not mean the order has no planned lines. type: array maxItems: 399 items: $ref: '#/components/schemas/OrderLine' description: An inbound or outbound order with its planned and processed quantities. OrderSummary: description: An order summary without its lines. Use the get-order endpoint with its `orderId` and `locationId` to retrieve line details. allOf: - $ref: '#/components/schemas/RevisionFields' - type: object required: - organizationId - orderId - locationId - direction - reference - status - lineCount properties: organizationId: $ref: '#/components/schemas/Identifier' orderId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' direction: type: string enum: - INBOUND - OUTBOUND reference: type: string maxLength: 128 status: type: string enum: - DRAFT - OPEN - IN_PROGRESS - COMPLETED - CANCELLED counterparty: oneOf: - $ref: '#/components/schemas/CounterpartySnapshot' - type: 'null' shipTo: oneOf: - $ref: '#/components/schemas/ShipToSnapshot' - type: 'null' lineCount: type: integer minimum: 0 description: Number of order lines. Retrieve the individual order to read them. rentalStartsAt: description: Planned rental departure time in UTC, or null for other orders. This is a planning date, not confirmation that goods have departed. type: - string - 'null' format: date-time rentalEndsAt: description: Planned rental return time in UTC, or null for other orders. type: - string - 'null' format: date-time outstandingReturnQuantity: description: Number of units handed over and still expected back, for rentals or announced sales returns. Null means no return quantity has been recorded for this order; it does not mean zero outstanding. type: - integer - 'null' minimum: 0 openLineCount: description: Number of lines not yet `COMPLETED` or `CANCELLED`. Null means the count is not available; do not treat it as zero. type: - integer - 'null' minimum: 0 executionState: description: Progress of the order's work, separately from the order's `status`. Null means progress is not available. oneOf: - $ref: '#/components/schemas/OrderExecutionState' - type: 'null' shortReason: description: Reason recorded when the order was completed with a shortage. Null if its current completion did not leave a shortage. oneOf: - $ref: '#/components/schemas/OrderShortReason' - type: 'null' OrderExecutionState: description: |- Progress of the work, independently of the order's status: - `NONE`: no quantity has been processed. - `PARTIAL`: some quantity has been processed and at least one line remains open. - `FULL`: every line is completed or cancelled and some quantity was processed. - `SHORT`: every line is closed and at least one has a shortage, including a line closed as unavailable before any quantity was processed. Finished picking or receiving does not always complete the order. Completion depends on a person's action or your Organization's automatic-completion settings. An order with a shortage requires a person to complete it with a reason. type: string enum: - NONE - PARTIAL - FULL - SHORT OrderShortReason: description: |- Reason for completing an order with a shortage: - `OUT_OF_STOCK`: insufficient stock was available. - `NOT_FOUND`: the expected stock could not be found. - `DAMAGED`: the stock was damaged and could not be shipped. type: string enum: - OUT_OF_STOCK - NOT_FOUND - DAMAGED TaskTransition: type: object additionalProperties: false required: - locationId - status properties: locationId: $ref: '#/components/schemas/Identifier' assignment: type: - object - 'null' additionalProperties: true description: Assignment changes as a JSON object. Use fields supported by the task's workflow. parentTaskId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' description: Batch containing the task. Null requests removal from its batch, subject to the state restrictions described above. status: type: string enum: - OPEN - ASSIGNED - IN_PROGRESS - CANCELLED roundExecution: type: boolean description: Whether this transition starts execution as a batch round. Use only when starting a batch workflow. expectedBatchRevision: type: integer minimum: 1 description: Current batch revision when a change affects batch membership. This is distinct from the task revision sent in `If-Match`. description: The requested status and any assignment or batch-membership changes. Only the listed statuses can be requested. TaskBatchCancellation: type: object additionalProperties: false required: - locationId - expectedBatchRevision - memberDisposition properties: locationId: $ref: '#/components/schemas/Identifier' expectedBatchRevision: type: integer minimum: 1 memberDisposition: type: string enum: - RELEASE_MEMBERS - CANCEL_MEMBERS TaskWorkSourcePlan: type: object additionalProperties: false required: - kind - sourceId properties: kind: type: string enum: - STOCKTAKE - INTEGRATION - MANUAL sourceId: $ref: '#/components/schemas/Identifier' TaskPlan: type: object additionalProperties: false required: - locationId - title - targetType - targetId properties: locationId: $ref: '#/components/schemas/Identifier' title: type: string minLength: 1 maxLength: 256 targetType: type: string enum: - ORDER - ORDER_LINE - INVENTORY_POSITION - LOCATION - ITEM targetRootId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' description: The parent record's Beam ID when the target belongs to another record, such as the order ID for an order-line target. targetId: $ref: '#/components/schemas/Identifier' expectedTargetRevision: type: integer minimum: 1 expectedTargetRootRevision: type: integer minimum: 1 taskKind: type: string enum: - PICK - BATCH - RECEIVE - PUTAWAY - COUNT - MOVE - REVIEW - OTHER taskType: type: - string - 'null' maxLength: 64 assignment: type: - object - 'null' additionalProperties: true description: Assignment details as a JSON object. Use only fields supported by your task workflow; this is not a general-purpose notes field. workSource: oneOf: - $ref: '#/components/schemas/TaskWorkSourcePlan' - type: 'null' parentTaskId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' description: A task linked to a Beam record. Use the record's Beam ID, not an external reference. examples: - locationId: loc_warehouse title: Review the stock discrepancy targetType: INVENTORY_POSITION targetId: pos_chair taskKind: REVIEW Task: allOf: - $ref: '#/components/schemas/RevisionFields' - type: object required: - organizationId - taskId - locationId - title - targetType - targetId - status properties: organizationId: $ref: '#/components/schemas/Identifier' taskId: $ref: '#/components/schemas/Identifier' locationId: $ref: '#/components/schemas/Identifier' title: type: string maxLength: 256 targetType: type: string enum: - ORDER - ORDER_LINE - INVENTORY_POSITION - LOCATION - ITEM - CONTAINER targetRootId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' targetId: anyOf: - $ref: '#/components/schemas/Identifier' - $ref: '#/components/schemas/Epc' targetRevision: type: - integer - 'null' minimum: 1 targetRootRevision: type: - integer - 'null' minimum: 1 taskKind: oneOf: - type: string enum: - PICK - BATCH - RECEIVE - PUTAWAY - COUNT - MOVE - REVIEW - OTHER - type: 'null' taskType: type: - string - 'null' maxLength: 64 assignment: type: - object - 'null' additionalProperties: true workSource: oneOf: - $ref: '#/components/schemas/TaskWorkSource' - type: 'null' requirements: oneOf: - $ref: '#/components/schemas/TaskRequirements' - type: 'null' authorityJobId: type: - string - 'null' description: Background work currently holding this task, or null when none is holding it. assigneePrincipal: oneOf: - type: object required: - type - id properties: type: type: string enum: - API_CLIENT - SERVICE id: type: string - type: 'null' description: The API client or service assigned to the task, if applicable. assigneeMembershipId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' assigneeUserId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' parentTaskId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' batchRevision: type: - integer - 'null' minimum: 1 description: Current version of the batch's membership or ordering. Use this in batch-edit requests alongside the task's `ETag`. childCount: type: - integer - 'null' minimum: 0 batchRank: type: - string - 'null' maxLength: 64 description: Ordering value within a batch. Treat it as opaque; use batch endpoints to change the order. waveId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' description: ID of the work wave grouping this task with other work, if any. memberKinds: type: - array - 'null' items: type: string enum: - PICK - PUTAWAY - MOVE completedMemberCount: type: - integer - 'null' minimum: 0 cancelledMemberCount: type: - integer - 'null' minimum: 0 activeStepTaskId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' description: ID of the step currently being performed in this batch, if any. roundExecution: type: - boolean - 'null' batchRelease: oneOf: - $ref: '#/components/schemas/TaskBatchRelease' - type: 'null' status: type: string enum: - OPEN - ASSIGNED - IN_PROGRESS - COMPLETED - CANCELLED description: Work to carry out or review. A task can stand alone or belong to a batch. TaskSourceFact: type: object additionalProperties: false required: - executionId - orderId - lineId - itemId - positionId - quantity properties: executionId: $ref: '#/components/schemas/Identifier' orderId: $ref: '#/components/schemas/Identifier' lineId: $ref: '#/components/schemas/Identifier' itemId: $ref: '#/components/schemas/Identifier' positionId: $ref: '#/components/schemas/Identifier' quantity: type: integer minimum: 1 TaskWorkSource: type: object additionalProperties: false description: Describes what created the task. Responses may include work sources created by Beam itself. When creating a task, use only the kinds listed in `TaskWorkSourcePlan`. Detailed facts for an `INVENTORY_INGRESS` source are not included. required: - kind - sourceId - executionIds - facts properties: kind: type: string enum: - ORDER_RECEIPTS - INVENTORY_INGRESS - CONTAINER_CARRIER - STOCKTAKE - INTEGRATION - IMPORT - MANUAL sourceId: $ref: '#/components/schemas/Identifier' executionIds: type: array maxItems: 1000 items: $ref: '#/components/schemas/Identifier' facts: type: array maxItems: 1000 items: $ref: '#/components/schemas/TaskSourceFact' containerEpc: oneOf: - $ref: '#/components/schemas/Epc' - type: 'null' TaskRequirementSourceFence: type: object additionalProperties: false required: - itemId - revision properties: itemId: $ref: '#/components/schemas/Identifier' revision: type: integer minimum: 1 description: The item and revision used to determine the task's requirements. Treat this as reference information. TaskRequirements: type: object additionalProperties: false required: - requiredCapabilityIds - minimumWorkers - verified - sourceFences properties: requiredCapabilityIds: type: array maxItems: 64 items: $ref: '#/components/schemas/Identifier' minimumWorkers: type: integer minimum: 1 verified: type: boolean sourceRevision: type: - integer - 'null' minimum: 1 sourceFences: type: array maxItems: 80 items: $ref: '#/components/schemas/TaskRequirementSourceFence' description: Item revisions used to determine these requirements. Clients do not need to calculate or update them. description: Capabilities and worker count required to carry out a task. These are returned for information; this API does not provide endpoints to edit capabilities. TaskBatchPolicy: type: object additionalProperties: false required: - maximumMembers - maximumEditMembers - maximumCreatedMembers - importedMemberKinds properties: maximumMembers: type: integer minimum: 1 maximum: 1000 maximumEditMembers: type: integer minimum: 1 maximumCreatedMembers: type: integer minimum: 0 importedMemberKinds: type: array items: type: string enum: - PICK - PUTAWAY - MOVE description: Your Organization's limits for creating and editing batches. Check these before preparing a request. TaskBatchWorkPlan: type: object additionalProperties: false required: - title - targetType - targetId - taskKind properties: title: type: string minLength: 1 maxLength: 256 targetType: type: string enum: - ORDER - ORDER_LINE - INVENTORY_POSITION targetRootId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' targetId: $ref: '#/components/schemas/Identifier' expectedTargetRevision: type: integer minimum: 1 expectedTargetRootRevision: type: integer minimum: 1 taskKind: type: string enum: - PICK - PUTAWAY - MOVE taskType: type: - string - 'null' maxLength: 64 assignment: type: - object - 'null' additionalProperties: true TaskBatchMemberPlan: type: object additionalProperties: false description: 'Choose one form: supply `taskId` and `expectedRevision` for an existing task, or `create` for new work. Do not combine the forms.' properties: taskId: $ref: '#/components/schemas/Identifier' expectedRevision: type: integer minimum: 1 create: $ref: '#/components/schemas/TaskBatchWorkPlan' TaskBatchMemberRef: type: object additionalProperties: false required: - taskId - expectedRevision properties: taskId: $ref: '#/components/schemas/Identifier' expectedRevision: type: integer minimum: 1 TaskBatchAssembly: type: object additionalProperties: false required: - locationId - title - members properties: workSource: $ref: '#/components/schemas/TaskWorkSourcePlan' assignment: type: - object - 'null' additionalProperties: true locationId: $ref: '#/components/schemas/Identifier' title: type: string minLength: 1 maxLength: 256 waveId: $ref: '#/components/schemas/Identifier' members: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/TaskBatchMemberPlan' TaskBatchAddition: type: object additionalProperties: false required: - locationId - expectedBatchRevision - members properties: locationId: $ref: '#/components/schemas/Identifier' expectedBatchRevision: type: integer minimum: 1 members: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/TaskBatchMemberPlan' afterTaskId: $ref: '#/components/schemas/Identifier' beforeTaskId: $ref: '#/components/schemas/Identifier' TaskBatchDetachment: type: object additionalProperties: false required: - locationId - expectedBatchRevision - members properties: locationId: $ref: '#/components/schemas/Identifier' expectedBatchRevision: type: integer minimum: 1 members: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/TaskBatchMemberRef' waveDisposition: type: string enum: - KEEP_WAVE - LEAVE_WAVE TaskBatchMove: type: object additionalProperties: false required: - locationId - expectedBatchRevision - targetTaskId - expectedTargetRevision - expectedTargetBatchRevision - members properties: locationId: $ref: '#/components/schemas/Identifier' expectedBatchRevision: type: integer minimum: 1 targetTaskId: $ref: '#/components/schemas/Identifier' expectedTargetRevision: type: integer minimum: 1 expectedTargetBatchRevision: type: integer minimum: 1 members: type: array minItems: 1 maxItems: 1000 items: $ref: '#/components/schemas/TaskBatchMemberRef' afterTaskId: $ref: '#/components/schemas/Identifier' beforeTaskId: $ref: '#/components/schemas/Identifier' TaskBatchReorder: type: object additionalProperties: false required: - locationId - expectedBatchRevision - memberTaskId properties: locationId: $ref: '#/components/schemas/Identifier' expectedBatchRevision: type: integer minimum: 1 memberTaskId: $ref: '#/components/schemas/Identifier' expectedMemberRevision: type: integer minimum: 1 afterTaskId: $ref: '#/components/schemas/Identifier' beforeTaskId: $ref: '#/components/schemas/Identifier' TaskBatchJob: type: object required: - jobId - status properties: jobId: $ref: '#/components/schemas/Identifier' status: type: string totalItems: type: - integer - 'null' minimum: 0 processedItems: type: - integer - 'null' minimum: 0 failureCode: type: - string - 'null' description: Failure code, when returned. Include it and the job ID when contacting Beam support. description: Background processing information returned when a batch edit is accepted. This reference has no job-status endpoint. Read the affected task and its steps to check the resulting state; contact Beam support if processing does not finish. TaskBatchEdit: type: object required: - task - members - memberTotal - membersComplete properties: task: $ref: '#/components/schemas/Task' members: type: array maxItems: 50 items: $ref: '#/components/schemas/Task' memberTotal: type: integer minimum: 0 membersComplete: type: boolean description: Whether `members` contains the complete set for this response. Do not infer that background processing finished from this field; also check `job` and the affected task. targetTask: oneOf: - $ref: '#/components/schemas/Task' - type: 'null' job: oneOf: - $ref: '#/components/schemas/TaskBatchJob' - type: 'null' description: Result of a batch edit. `job` indicates background processing. `members` can contain only part of the affected tasks; use `memberTotal` and `membersComplete` to interpret it. TaskBatchStep: type: object required: - taskId - targetType - targetId - title - createdAt properties: taskId: $ref: '#/components/schemas/Identifier' batchRank: type: - string - 'null' maxLength: 64 description: Opaque ordering value. The endpoint already returns steps in their execution order. targetType: type: string targetRootId: oneOf: - $ref: '#/components/schemas/Identifier' - type: 'null' targetId: anyOf: - $ref: '#/components/schemas/Identifier' - $ref: '#/components/schemas/Epc' taskKind: type: - string - 'null' taskType: type: - string - 'null' title: type: string createdAt: type: string format: date-time task: oneOf: - $ref: '#/components/schemas/Task' - type: 'null' description: The task's current details, or null if unavailable. description: A remaining step in a batch, with its associated task when available. TaskBatchStepPage: type: object required: - items - batchRevision properties: items: type: array items: $ref: '#/components/schemas/TaskBatchStep' cursor: type: - string - 'null' batchRevision: type: integer minimum: 1 TaskBatchRelease: type: object required: - parentTaskId - releasedAt properties: parentTaskId: $ref: '#/components/schemas/Identifier' workSourceKind: type: - string - 'null' workSourceId: type: - string - 'null' releasedAt: type: string format: date-time releasedByUserId: type: - string - 'null' description: Information about a task's release from its previous batch. TaskBatchTransition: type: object additionalProperties: false required: - task - children properties: task: $ref: '#/components/schemas/Task' children: type: array maxItems: 1000 items: $ref: '#/components/schemas/Task' childTotal: type: integer minimum: 0 description: Total number of members when cancellation was requested. The `children` array returns at most 50 of them. childrenComplete: type: boolean description: True when all members have been processed. False means background cancellation continues and the batch remains open until it finishes. Read the batch task again to check its status. description: Result of cancelling a batch. Check `childrenComplete` and the batch's status before assuming cancellation finished. OrderPage: type: object required: - items properties: items: type: array maxItems: 50 items: $ref: '#/components/schemas/OrderSummary' cursor: type: - string - 'null' maxLength: 4096 OrderLineWork: type: object required: - lineId - task - roundTaskId - round properties: lineId: $ref: '#/components/schemas/Identifier' task: description: The line's task, or null if it has not been created yet. For older orders it may be created when work first starts. oneOf: - $ref: '#/components/schemas/Task' - type: 'null' roundTaskId: type: - string - 'null' round: oneOf: - $ref: '#/components/schemas/Task' - type: 'null' OrderLineWorkPage: type: object required: - orderId - items - cursor properties: orderId: $ref: '#/components/schemas/Identifier' cursor: type: - string - 'null' items: type: array items: $ref: '#/components/schemas/OrderLineWork' Problem: type: object additionalProperties: false required: - type - title - status - code - requestId properties: type: type: string format: uri title: type: string maxLength: 128 status: type: integer enum: - 400 - 401 - 403 - 404 - 409 - 413 - 429 - 503 detail: type: string maxLength: 512 code: type: string pattern: ^[A-Z][A-Z0-9_]{2,63}$ requestId: type: string maxLength: 128 examples: - type: https://docs.beamtracking.com/problems/rate_limited title: RATE LIMITED status: 429 code: RATE_LIMITED requestId: request_example GatewayError: type: object required: - message properties: message: type: string