Beam
API docs by Redocly

Beam API (1.0.0)

Download OpenAPI specification:

License: LicenseRef-Proprietary

Use the Beam API to connect your business systems to your Beam Organization. Manage products and stock, submit inbound or outbound orders, and follow the work your team performs in Beam. This API is for applications running on a server.

Base URL: https://connect.beamtracking.com. Requests and responses use JSON. For a shorter setup guide, see Connect your own systems with the API.

Get connected

  1. In Beam, open Organization settings > API keys > New API key. You need Organization administrator access and may be asked to sign in again.
  2. Choose a name, the access level your integration needs, and a lifetime of 30, 90, 180 or 365 days.
  3. Save the key in your server's secret store. Beam shows it only once. Also copy the Organization ID from the displayed Organization path.
  4. Replace the placeholders below and request your locations:
curl 'https://connect.beamtracking.com/v1/organizations/YOUR_ORGANIZATION_ID/locations' \
  -H 'Authorization: Bearer YOUR_API_KEY'

A successful response contains an items array. Save the relevant locationId for stock, order and task requests. An empty array means no locations were returned.

Choose an access level

Choose the least access your integration needs. Each endpoint lists the access levels that can use it.

Access level What your integration can do
Read only Read products, locations, inventory and orders.
Inventory sync Read products and locations; read and update inventory.
Order sync Read products, locations and inventory; read and update orders; read and manage tasks.
Full API access Use all operations in this reference, including creating and updating products and locations.

Task reads require Order sync or Full API access. Read only does not include task access. Order sync does not include inventory changes.

Authenticate and manage keys

Send Authorization: Bearer YOUR_API_KEY with every request. A key belongs to one Organization and cannot access another. Never embed it in a website or mobile app. Browser requests are not supported; call Beam from your server.

  • Rotate: creates a new key value with the same lifetime. The old value stops working immediately, so update your integration as part of the rotation.
  • Disable: stops access. Enable restores it, although a previously refused key can take up to five minutes to work again.
  • Revoke: permanently stops access.
  • Expiry: the key stops working at its expiry date. Beam warns 30 days ahead.

Understand the records

  • An item is a product in your catalog. QUANTITY tracks stock by count; SERIALIZED tracks individual units. The quantity endpoints here do not replace individual-unit workflows.
  • A location is a site, such as a warehouse. Inside it, layout groups represent floor plans (MAP), areas (ZONE) and racks (GRID). A spot identifies a storage position within a group.
  • An inventory position records stock for an item at a location and spot.
  • An order contains the goods you plan to receive or send. Its lines track planned and processed quantities.
  • A task is work to perform or review. A batch, also called a round, groups tasks in execution order. A wave groups related work.

Use Beam IDs returned by the API in ID fields. Keep your own order numbers and line identifiers in reference and externalReference.

Read all pages

List endpoints accept pageSize from 1 to 50, with a default of 25. Pass the returned cursor to the next request, keeping the other filters unchanged. Stop when the cursor is null or absent. Do not infer completion from the number of items in a page, and do not parse or modify a cursor.

Order lists return summaries without lines and require a location and one of DRAFT, OPEN or IN_PROGRESS. Save order IDs so you can retrieve individual orders after completion or cancellation.

Write safely

Every write requires an Idempotency-Key containing a UUID. Generate a new UUID for a new request. If a request times out or needs retrying, resend the same request with the same key. Beam returns its original result without applying the change twice. Reusing the key with a different body returns 409 IDEMPOTENCY_KEY_REUSED.

Updates requiring If-Match also need the record's latest ETag, including quotes, such as "revision-3". If you read a record from a list, use its revision to form that value. A conflicting update returns 409: read the record again, reconsider your change and submit the revised request with a new idempotency key.

For example, after reading an item's current revision:

curl -X PATCH 'https://connect.beamtracking.com/v1/organizations/YOUR_ORGANIZATION_ID/items/YOUR_ITEM_ID' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 76df4c54-592e-4a89-90aa-3812a140a08d' \
  -H 'If-Match: "revision-3"' \
  -d '{"name":"Black folding chair"}'

Replace the IDs, key and revision with your own values, and generate a new UUID for your request. The examples throughout this reference use fictional data.

Stock corrections set a total, rather than add a quantity. Setting quantity to 120 means 120 units, not 120 extra units. Use the inventory-move endpoint when goods actually move between locations.

Order updates replace the whole plan. Include every intended line. Omitting an existing unexecuted line cancels it. Do not split one plan across requests. Work already performed can prevent a requested change.

Follow background processing

Some writes are accepted before all work has finished:

  • Orders: 202 means the plan is processing. The response contains activeJobId and an empty lines array. Poll the get-order endpoint using the order ID and location until activeJobId is null or absent, then check the actual lines and status. Further writes during processing return ORDER_BUSY.
  • Batch edits: even a 200 response can contain a job. Read the returned task again and check authorityJobId; read the batch's remaining steps to inspect the result. For moves, check both the source and destination batches.
  • Batch cancellation: childrenComplete: false means processing continues. Read the batch task until cancellation finishes and inspect member statuses.

There is no job-status endpoint in this reference. Do not treat acceptance, a partial member list or the disappearance of a background-work ID alone as proof that your intended result was achieved. Check the resulting records. Poll with a delay, respect the rate limit and set an application timeout. If processing does not finish, contact Beam support with the record ID, any job ID and the request ID; avoid repeatedly submitting the same change with new keys.

Handle errors

Most errors use application/problem+json with a stable code, an HTTP status, a title and a requestId. Optional detail provides more context. Use code for program logic and include requestId when contacting Beam support. Some authentication failures instead return application/json with message.

Status What to do
400 Check required fields, formats and allowed values (VALIDATION_FAILED).
401 Add the Authorization header. The body is {"message":"Unauthorized"}.
403 Check the key's validity, access level and Organization. The body can be {"message":"Forbidden"} or a problem response with FORBIDDEN.
404 Check the record ID and its Organization and location.
409 Read code, refresh the affected records and resolve the conflict before retrying.
413 Reduce the body size (PAYLOAD_TOO_LARGE). Do not split a complete order plan across requests.
429 Wait for the seconds specified in Retry-After (RATE_LIMITED).
503 Retry after the delay in Retry-After (DEPENDENCY_UNAVAILABLE).

Limits and compatibility

  • Each API key allows 20 requests per second, with bursts of up to 100.
  • Retry 429 and 503 with increasing delays and honor Retry-After. Reuse the original idempotency key when retrying a write.
  • Request bodies are limited to 256 KiB. JSON field names use camelCase.
  • Optional response fields and new endpoints can be added within this API version. Ignore response fields you do not recognize.
  • This API does not provide webhooks or streaming. Poll the records you need at an interval that fits your use case and the rate limit.

Catalog

Products, sites and storage layouts.

List items

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

query Parameters
cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Create an item

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
name
required
string [ 1 .. 256 ] characters
articleCode
required
string [ 1 .. 128 ] characters
productCode
string or null <= 128 characters
sku
string or null <= 128 characters
barcode
string or null <= 128 characters
category
string or null <= 128 characters
subCategory
string or null <= 128 characters
trackingMode
required
string
Enum: "QUANTITY" "SERIALIZED"

Choose QUANTITY for stock tracked by count or SERIALIZED for individually identified units.

Responses

Request samples

Content type
application/json
{
  • "name": "Folding chair",
  • "articleCode": "CHAIR-001",
  • "trackingMode": "QUANTITY",
  • "sku": "CHAIR-BLACK"
}

Response samples

Content type
application/json
{
  • "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"
}

Get an item

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

itemId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Responses

Response samples

Content type
application/json
{
  • "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"
}

Update an item

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

itemId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 256 ] characters
productCode
string or null <= 128 characters
sku
string or null <= 128 characters
barcode
string or null <= 128 characters
category
string or null <= 128 characters
subCategory
string or null <= 128 characters

Responses

Request samples

Content type
application/json
{
  • "name": "Black folding chair"
}

Response samples

Content type
application/json
{
  • "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"
}

List locations

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

query Parameters
cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Create a location

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
code
required
string [ 1 .. 128 ] characters
name
required
string [ 1 .. 256 ] characters
Identifier (string) or null

Responses

Request samples

Content type
application/json
{
  • "code": "WH-01",
  • "name": "Main warehouse"
}

Response samples

Content type
application/json
{
  • "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"
}

Get a location

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

Responses

Response samples

Content type
application/json
{
  • "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"
}

Update a location

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 256 ] characters
Identifier (string) or null

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parentLocationId": "string"
}

Response samples

Content type
application/json
{
  • "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"
}

List layout groups

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

query Parameters
cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Create a layout group

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
parentSpotGroupId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
groupType
required
string (SpotGroupType)
Enum: "MAP" "ZONE" "GRID" "HEADER"

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.

name
required
string [ 1 .. 256 ] characters
code
string [ 1 .. 128 ] characters
object (LayoutJson) <= 50 properties

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.

sortOrder
integer

Responses

Request samples

Content type
application/json
{
  • "parentSpotGroupId": "string",
  • "groupType": "MAP",
  • "name": "string",
  • "code": "string",
  • "attributes": { },
  • "sortOrder": 0
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "locationId": "string",
  • "spotGroupId": "string",
  • "parentSpotGroupId": "string",
  • "mapGroupId": "string",
  • "groupType": "string",
  • "name": "string",
  • "code": "string",
  • "barcode": "string",
  • "attributes": { },
  • "sortOrder": 0,
  • "status": "ACTIVE"
}

Update a layout group

Update the supplied layout-group fields. Obtain the group's current revision from the layout-group listing and send it as If-Match: "revision-<revision>".

Access levels: Full API access.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

spotGroupId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam layout-group ID returned when listing or creating groups.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
non-empty
name
string [ 1 .. 256 ] characters
parentSpotGroupId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
groupType
string (SpotGroupType)
Enum: "MAP" "ZONE" "GRID" "HEADER"

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.

object (LayoutJson) <= 50 properties

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.

sortOrder
integer

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "parentSpotGroupId": "string",
  • "groupType": "MAP",
  • "attributes": { },
  • "sortOrder": 0
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "locationId": "string",
  • "spotGroupId": "string",
  • "parentSpotGroupId": "string",
  • "mapGroupId": "string",
  • "groupType": "string",
  • "name": "string",
  • "code": "string",
  • "barcode": "string",
  • "attributes": { },
  • "sortOrder": 0,
  • "status": "ACTIVE"
}

List storage spots

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

query Parameters
spotGroupId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Restrict results to this layout group.

cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Create a storage spot

Add a named storage position to an existing layout group. Save the returned spotId to identify stock held there.

Access levels: Full API access.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
spotGroupId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
label
required
string [ 1 .. 256 ] characters
code
string [ 1 .. 128 ] characters
barcode
string [ 1 .. 128 ] characters
object (LayoutJson) <= 50 properties

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.

object (LayoutJson) <= 50 properties

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.

Responses

Request samples

Content type
application/json
{
  • "spotGroupId": "string",
  • "label": "string",
  • "code": "string",
  • "barcode": "string",
  • "coordinates": { },
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "locationId": "string",
  • "spotGroupId": "string",
  • "mapGroupId": "string",
  • "spotId": "string",
  • "label": "string",
  • "code": "string",
  • "barcode": "string",
  • "coordinates": { },
  • "attributes": { },
  • "isDefault": true,
  • "status": "ACTIVE"
}

Update a storage spot

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-<revision>".

Access levels: Full API access.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam location ID returned by the locations endpoint.

spotId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The Beam storage-spot ID returned when listing or creating spots.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
non-empty
label
string [ 1 .. 256 ] characters
code
string [ 1 .. 128 ] characters
barcode
string [ 1 .. 128 ] characters
object (LayoutJson) <= 50 properties

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.

object (LayoutJson) <= 50 properties

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.

Responses

Request samples

Content type
application/json
{
  • "label": "string",
  • "code": "string",
  • "barcode": "string",
  • "coordinates": { },
  • "attributes": { }
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "locationId": "string",
  • "spotGroupId": "string",
  • "mapGroupId": "string",
  • "spotId": "string",
  • "label": "string",
  • "code": "string",
  • "barcode": "string",
  • "coordinates": { },
  • "attributes": { },
  • "isDefault": true,
  • "status": "ACTIVE"
}

Inventory

Read stock, correct quantities and record movements between locations.

List inventory positions

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

itemId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Item to read. Without spotId, the inventory endpoint returns only this item's default storage position.

spotId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Restrict results to this storage spot.

cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Create an inventory position

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
itemId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
spotId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Storage spot for this stock. If omitted, Beam uses the location's default spot.

unitOfMeasure
required
string [ 1 .. 32 ] characters

Unit used for quantities, for example pcs. Use a consistent unit for the item and its stock.

Responses

Request samples

Content type
application/json
{
  • "itemId": "item_chair",
  • "locationId": "loc_warehouse",
  • "unitOfMeasure": "pcs"
}

Response samples

Content type
application/json
{
  • "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"
}

Set an inventory quantity

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

positionId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
itemId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
spotId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Storage spot of the position being corrected. Use the same item, location and spot as the target position.

quantity
required
integer [ 0 .. 2147483647 ]
reason
required
string [ 1 .. 256 ] characters

Responses

Request samples

Content type
application/json
{
  • "itemId": "item_chair",
  • "locationId": "loc_warehouse",
  • "quantity": 120,
  • "reason": "Confirmed stock count"
}

Response samples

Content type
application/json
{
  • "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"
}

Move inventory between locations

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
itemId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
sourceLocationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
destinationLocationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
quantity
required
integer [ 1 .. 2147483647 ]
expectedSourceRevision
required
integer [ 1 .. 2147483647 ]
expectedDestinationRevision
required
integer [ 1 .. 2147483647 ]
reason
required
string [ 1 .. 256 ] characters

Responses

Request samples

Content type
application/json
{
  • "itemId": "item_chair",
  • "sourceLocationId": "loc_warehouse",
  • "destinationLocationId": "loc_shop",
  • "quantity": 10,
  • "expectedSourceRevision": 2,
  • "expectedDestinationRevision": 1,
  • "reason": "Restock the shop"
}

Response samples

Content type
application/json
{
  • "source": {
    },
  • "destination": {
    }
}

Orders

Create inbound and outbound orders, update their plans and follow progress.

List orders

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

status
required
string
Enum: "DRAFT" "OPEN" "IN_PROGRESS"
cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string"
}

Create an order

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
direction
required
string
Enum: "INBOUND" "OUTBOUND"
reference
required
string [ 1 .. 128 ] characters

Your order reference, such as an order number. The returned orderId is Beam's identifier for later requests.

required
object (CounterpartySnapshot)
ShipToSnapshot (object) or null
object <= 50 properties

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.

desiredStatus
string
Enum: "DRAFT" "OPEN" "CANCELLED"

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.

required
Array of objects (OrderLinePlan) [ 0 .. 80 ] items

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.

Responses

Request samples

Content type
application/json
{
  • "locationId": "loc_warehouse",
  • "direction": "OUTBOUND",
  • "reference": "SO-2026-1042",
  • "counterparty": {
    },
  • "desiredStatus": "OPEN",
  • "lines": [
    ]
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "orderId": "string",
  • "locationId": "string",
  • "direction": "INBOUND",
  • "reference": "string",
  • "status": "DRAFT",
  • "counterparty": {
    },
  • "shipTo": {
    },
  • "attributes": { },
  • "goodsLifecycleVersion": 0,
  • "pendingHandoverQuantity": 0,
  • "rentalStartsAt": "2019-08-24T14:15:22Z",
  • "rentalEndsAt": "2019-08-24T14:15:22Z",
  • "outstandingReturnQuantity": 0,
  • "openLineCount": 0,
  • "executionState": "NONE",
  • "shortReason": "OUT_OF_STOCK",
  • "activeJobId": "string",
  • "lines": [
    ]
}

Get an order

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

orderId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

Responses

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "orderId": "string",
  • "locationId": "string",
  • "direction": "INBOUND",
  • "reference": "string",
  • "status": "DRAFT",
  • "counterparty": {
    },
  • "shipTo": {
    },
  • "attributes": { },
  • "goodsLifecycleVersion": 0,
  • "pendingHandoverQuantity": 0,
  • "rentalStartsAt": "2019-08-24T14:15:22Z",
  • "rentalEndsAt": "2019-08-24T14:15:22Z",
  • "outstandingReturnQuantity": 0,
  • "openLineCount": 0,
  • "executionState": "NONE",
  • "shortReason": "OUT_OF_STOCK",
  • "activeJobId": "string",
  • "lines": [
    ]
}

Update an order's complete plan

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

orderId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
direction
required
string
Enum: "INBOUND" "OUTBOUND"
reference
required
string [ 1 .. 128 ] characters

Your order reference, such as an order number. The returned orderId is Beam's identifier for later requests.

required
object (CounterpartySnapshot)
ShipToSnapshot (object) or null
object <= 50 properties

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.

desiredStatus
string
Enum: "DRAFT" "OPEN" "CANCELLED"

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.

required
Array of objects (OrderLinePlan) [ 0 .. 80 ] items

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.

Responses

Request samples

Content type
application/json
{
  • "locationId": "loc_warehouse",
  • "direction": "OUTBOUND",
  • "reference": "SO-2026-1042",
  • "counterparty": {
    },
  • "desiredStatus": "OPEN",
  • "lines": [
    ]
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "orderId": "string",
  • "locationId": "string",
  • "direction": "INBOUND",
  • "reference": "string",
  • "status": "DRAFT",
  • "counterparty": {
    },
  • "shipTo": {
    },
  • "attributes": { },
  • "goodsLifecycleVersion": 0,
  • "pendingHandoverQuantity": 0,
  • "rentalStartsAt": "2019-08-24T14:15:22Z",
  • "rentalEndsAt": "2019-08-24T14:15:22Z",
  • "outstandingReturnQuantity": 0,
  • "openLineCount": 0,
  • "executionState": "NONE",
  • "shortReason": "OUT_OF_STOCK",
  • "activeJobId": "string",
  • "lines": [
    ]
}

Tasks

Create and follow work, and group tasks into ordered batches.

Create a task

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
title
required
string [ 1 .. 256 ] characters
targetType
required
string
Enum: "ORDER" "ORDER_LINE" "INVENTORY_POSITION" "LOCATION" "ITEM"
Identifier (string) or null

The parent record's Beam ID when the target belongs to another record, such as the order ID for an order-line target.

targetId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedTargetRevision
integer >= 1
expectedTargetRootRevision
integer >= 1
taskKind
string
Enum: "PICK" "BATCH" "RECEIVE" "PUTAWAY" "COUNT" "MOVE" "REVIEW" "OTHER"
taskType
string or null <= 64 characters
object or null

Assignment details as a JSON object. Use only fields supported by your task workflow; this is not a general-purpose notes field.

TaskWorkSourcePlan (object) or null
Identifier (string) or null

Responses

Request samples

Content type
application/json
{
  • "locationId": "loc_warehouse",
  • "title": "Review the stock discrepancy",
  • "targetType": "INVENTORY_POSITION",
  • "targetId": "pos_chair",
  • "taskKind": "REVIEW"
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "taskId": "string",
  • "locationId": "string",
  • "title": "string",
  • "targetType": "ORDER",
  • "targetRootId": "string",
  • "targetId": "string",
  • "targetRevision": 1,
  • "targetRootRevision": 1,
  • "taskKind": "PICK",
  • "taskType": "string",
  • "assignment": { },
  • "workSource": {
    },
  • "requirements": {
    },
  • "authorityJobId": "string",
  • "assigneePrincipal": {
    },
  • "assigneeMembershipId": "string",
  • "assigneeUserId": "string",
  • "parentTaskId": "string",
  • "batchRevision": 1,
  • "childCount": 0,
  • "batchRank": "string",
  • "waveId": "string",
  • "memberKinds": [
    ],
  • "completedMemberCount": 0,
  • "cancelledMemberCount": 0,
  • "activeStepTaskId": "string",
  • "roundExecution": true,
  • "batchRelease": {
    },
  • "status": "OPEN"
}

Get a task

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

Responses

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "taskId": "string",
  • "locationId": "string",
  • "title": "string",
  • "targetType": "ORDER",
  • "targetRootId": "string",
  • "targetId": "string",
  • "targetRevision": 1,
  • "targetRootRevision": 1,
  • "taskKind": "PICK",
  • "taskType": "string",
  • "assignment": { },
  • "workSource": {
    },
  • "requirements": {
    },
  • "authorityJobId": "string",
  • "assigneePrincipal": {
    },
  • "assigneeMembershipId": "string",
  • "assigneeUserId": "string",
  • "parentTaskId": "string",
  • "batchRevision": 1,
  • "childCount": 0,
  • "batchRank": "string",
  • "waveId": "string",
  • "memberKinds": [
    ],
  • "completedMemberCount": 0,
  • "cancelledMemberCount": 0,
  • "activeStepTaskId": "string",
  • "roundExecution": true,
  • "batchRelease": {
    },
  • "status": "OPEN"
}

Update a task's status or assignment

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
object or null

Assignment changes as a JSON object. Use fields supported by the task's workflow.

Identifier (string) or null

Batch containing the task. Null requests removal from its batch, subject to the state restrictions described above.

status
required
string
Enum: "OPEN" "ASSIGNED" "IN_PROGRESS" "CANCELLED"
roundExecution
boolean

Whether this transition starts execution as a batch round. Use only when starting a batch workflow.

expectedBatchRevision
integer >= 1

Current batch revision when a change affects batch membership. This is distinct from the task revision sent in If-Match.

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "assignment": { },
  • "parentTaskId": "string",
  • "status": "OPEN",
  • "roundExecution": true,
  • "expectedBatchRevision": 1
}

Response samples

Content type
application/json
{
  • "revision": 1,
  • "createdAt": "2019-08-24T14:15:22Z",
  • "updatedAt": "2019-08-24T14:15:22Z",
  • "organizationId": "string",
  • "taskId": "string",
  • "locationId": "string",
  • "title": "string",
  • "targetType": "ORDER",
  • "targetRootId": "string",
  • "targetId": "string",
  • "targetRevision": 1,
  • "targetRootRevision": 1,
  • "taskKind": "PICK",
  • "taskType": "string",
  • "assignment": { },
  • "workSource": {
    },
  • "requirements": {
    },
  • "authorityJobId": "string",
  • "assigneePrincipal": {
    },
  • "assigneeMembershipId": "string",
  • "assigneeUserId": "string",
  • "parentTaskId": "string",
  • "batchRevision": 1,
  • "childCount": 0,
  • "batchRank": "string",
  • "waveId": "string",
  • "memberKinds": [
    ],
  • "completedMemberCount": 0,
  • "cancelledMemberCount": 0,
  • "activeStepTaskId": "string",
  • "roundExecution": true,
  • "batchRelease": {
    },
  • "status": "OPEN"
}

Cancel a task batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedBatchRevision
required
integer >= 1
memberDisposition
required
string
Enum: "RELEASE_MEMBERS" "CANCEL_MEMBERS"

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "expectedBatchRevision": 1,
  • "memberDisposition": "RELEASE_MEMBERS"
}

Response samples

Content type
application/json
{
  • "task": {
    },
  • "children": [
    ],
  • "childTotal": 0,
  • "childrenComplete": true
}

Get tasks for order lines

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

orderId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

pageSize
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

cursor
string <= 4096 characters

The cursor returned by the previous page. Omit for the first page. Keep other filters unchanged and do not interpret or modify the cursor.

Responses

Response samples

Content type
application/json
{
  • "orderId": "string",
  • "cursor": "string",
  • "items": [
    ]
}

Get task-batch limits

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

Responses

Response samples

Content type
application/json
{
  • "maximumMembers": 1,
  • "maximumEditMembers": 1,
  • "maximumCreatedMembers": 0,
  • "importedMemberKinds": [
    ]
}

Create a task batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

Request Body schema: application/json
required
object (TaskWorkSourcePlan)
object or null
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
title
required
string [ 1 .. 256 ] characters
waveId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
required
Array of objects (TaskBatchMemberPlan) [ 1 .. 1000 ] items

Responses

Request samples

Content type
application/json
{
  • "workSource": {
    },
  • "assignment": { },
  • "locationId": "string",
  • "title": "string",
  • "waveId": "string",
  • "members": [
    ]
}

Response samples

Content type
application/json
{
  • "task": {
    },
  • "members": [
    ],
  • "memberTotal": 0,
  • "membersComplete": true,
  • "targetTask": {
    },
  • "job": {
    }
}

Add tasks to a batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedBatchRevision
required
integer >= 1
required
Array of objects (TaskBatchMemberPlan) [ 1 .. 1000 ] items
afterTaskId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
beforeTaskId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "expectedBatchRevision": 1,
  • "members": [
    ],
  • "afterTaskId": "string",
  • "beforeTaskId": "string"
}

Response samples

Content type
application/json
{
  • "task": {
    },
  • "members": [
    ],
  • "memberTotal": 0,
  • "membersComplete": true,
  • "targetTask": {
    },
  • "job": {
    }
}

Remove tasks from a batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedBatchRevision
required
integer >= 1
required
Array of objects (TaskBatchMemberRef) [ 1 .. 1000 ] items
waveDisposition
string
Enum: "KEEP_WAVE" "LEAVE_WAVE"

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "expectedBatchRevision": 1,
  • "members": [
    ],
  • "waveDisposition": "KEEP_WAVE"
}

Response samples

Content type
application/json
{
  • "task": {
    },
  • "members": [
    ],
  • "memberTotal": 0,
  • "membersComplete": true,
  • "targetTask": {
    },
  • "job": {
    }
}

Move tasks to another batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedBatchRevision
required
integer >= 1
targetTaskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedTargetRevision
required
integer >= 1
expectedTargetBatchRevision
required
integer >= 1
required
Array of objects (TaskBatchMemberRef) [ 1 .. 1000 ] items
afterTaskId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
beforeTaskId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "expectedBatchRevision": 1,
  • "targetTaskId": "string",
  • "expectedTargetRevision": 1,
  • "expectedTargetBatchRevision": 1,
  • "members": [
    ],
  • "afterTaskId": "string",
  • "beforeTaskId": "string"
}

Response samples

Content type
application/json
{
  • "task": {
    },
  • "members": [
    ],
  • "memberTotal": 0,
  • "membersComplete": true,
  • "targetTask": {
    },
  • "job": {
    }
}

Reorder a task within a batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
header Parameters
Idempotency-Key
required
string <uuid>

A UUID identifying this write request. Generate a new UUID for a new request and reuse it only when retrying the same request.

If-Match
required
string^"revision-[1-9][0-9]*"$

The latest ETag of the record, including quotes, for example "revision-3". If using a list result, format its revision as "revision-<revision>".

Request Body schema: application/json
required
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedBatchRevision
required
integer >= 1
memberTaskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
expectedMemberRevision
integer >= 1
afterTaskId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
beforeTaskId
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Responses

Request samples

Content type
application/json
{
  • "locationId": "string",
  • "expectedBatchRevision": 1,
  • "memberTaskId": "string",
  • "expectedMemberRevision": 1,
  • "afterTaskId": "string",
  • "beforeTaskId": "string"
}

Response samples

Content type
application/json
{
  • "task": {
    },
  • "members": [
    ],
  • "memberTotal": 0,
  • "membersComplete": true,
  • "targetTask": {
    },
  • "job": {
    }
}

List remaining tasks in a batch

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.

Authorizations:
beamApiKey
path Parameters
organizationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

Your Beam Organization ID, shown in the Organization path when you create an API key.

taskId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$
query Parameters
locationId
required
string (Identifier) ^[A-Za-z0-9][A-Za-z0-9_-]{2,127}$

The location containing the records. Required even when an individual order or task ID is supplied.

cursor
string <= 4096 characters

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
integer [ 1 .. 50 ]
Default: 25

Maximum number of records to request per page, from 1 to 50. Defaults to 25.

Responses

Response samples

Content type
application/json
{
  • "items": [
    ],
  • "cursor": "string",
  • "batchRevision": 1
}