Warehouse tasks

Create 1 to 100 Warehouse tasks from one JSON array. Each task receives DRAFT status, is assigned to the API key locations, and starts without an assignee. Duplicate externalId values are rejected; each item is returned in the batch results.

POSThttp://localhost:3000/api/v1/warehouse/tasks
Method
POST
Content type
application/json
Authentication
Required · active locations · non-expired key
Maximum payload
1 MiB
Request frequency
30 requests per 60 seconds

Request headers

Send these headers with every POST request.

Content-Type: application/json
Authorization: Bearer y3m_ABCD2345_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

To get the authorization key, open Dashboard, use the three-dot menu on the company card, and select API integrations. Under Secret keys, select Create secret key, enable the Warehouse scope, and assign at least one active location. Copy the full key when it is created because it is shown only once, then send it after Bearer in the Authorization header.

Request fields

Required and optional fields accepted in the JSON request body. Unknown fields are rejected at every level.

FieldTypeRequirementDescription
externalIdstringRequiredCaller-controlled source-system task identifier. It must be unique within the company. Maximum 200 characters.
taskobjectOptionalOptional Warehouse task identity.
task.codestringOn createRequired when task is provided on create. External warehouse task code, stored unchanged. Maximum 100 characters.
task.typestringOptionalOptional external warehouse task type, stored unchanged. Maximum 100 characters.
task.namestring | nullOptionalOptional warehouse task display name. Maximum 200 characters.
datesobjectOn createWarehouse task schedule required on create. Both dates use the YYYY-MM-DD format.
dates.scheduleddateOn createFirst scheduled Warehouse task date required on create in YYYY-MM-DD format.
dates.enddateOptionalLast scheduled Warehouse task date in YYYY-MM-DD format. Must not be earlier than dates.scheduled and defaults to dates.scheduled when omitted.
operationType"RECEIVING" | "TRANSFER"On createWarehouse operation type required on create. Operations attached to this task must use the same operation type.
descriptionstring | nullOptionalOptional warehouse task description or note. Maximum 2,000 characters.
operationsarrayOn createBetween 1 and 1,000 confirmed Warehouse Operations required on create.
operations[].externalIdstringOn createExternal identifier required on create for an existing confirmed Warehouse Operation with the same operationType.
operations[].positionintegerOptionalOptional positive operation position. Supplied positions must be unique.

Error responses

Possible errors returned by this endpoint and how to resolve them.

StatusCodeMeaningResolution
400INVALID_JSONThe request body is not valid JSON.Send one correctly formatted JSON object.
400INVALID_PAYLOADThe JSON body is not an object.Send a JSON object instead of an array, string, number, or null.
401UNAUTHORIZEDThe Authorization header is missing, malformed, or contains an invalid API key.Send a valid API key using the Bearer authorization scheme.
401API_KEY_EXPIREDThe API key has reached its expiration date.Create a new API key and retry the request.
403FORBIDDENThe API key cannot access this module or is not assigned to an active company location.Assign an active location, enable the required module, or use another key.
409PRODUCT_DELETEDA product referenced by externalId is deleted.Restore the product in Y3M, then retry the request.
409WAREHOUSE_TASK_ALREADY_EXISTSA Warehouse task already uses this externalId, including a deleted task.Use another externalId.
409WAREHOUSE_OPERATION_ALREADY_EXISTSA non-deleted Warehouse Operation already uses this externalId.Use another externalId or delete the existing Warehouse Operation before creating a new one.
409WAREHOUSE_UNAVAILABLEWarehouse is inactive.Activate Warehouse, then retry the request.
413PAYLOAD_TOO_LARGEThe request body exceeds the 1 MiB limit.Reduce the JSON payload size to 1 MiB or less.
415UNSUPPORTED_MEDIA_TYPEThe Content-Type header is not application/json.Send Content-Type: application/json.
422VALIDATION_ERRORThe JSON is valid but one or more fields do not satisfy the endpoint contract.Use each { path, message } entry in error.details to correct the specified field.
429RATE_LIMIT_EXCEEDEDMore than 30 requests were sent within 60 seconds.Wait for the number of seconds specified by the Retry-After header.
500INTERNAL_ERRORRequest infrastructure, authentication, or rate-limit processing is temporarily unavailable.Retry later. Contact support if the error continues.
500STORAGE_ERRORThe validated payload could not be stored.Retry later. Contact support if the error continues.

Example request

Send this JSON object in the POST request body.

[
  {
    "externalId": "WAREHOUSE-001",
    "task": {
      "code": "RCV-001",
      "type": "supplier_delivery",
      "name": "Receive supplier shipment"
    },
    "dates": {
      "scheduled": "2026-10-20",
      "end": "2026-10-22"
    },
    "operationType": "RECEIVING",
    "description": "Receiving note",
    "operations": [
      {
        "externalId": "OPERATION-001",
        "position": 1
      }
    ]
  }
]