Time	Status	User Agent
Retrieving recent requests…

Update tills in bulk

Update up to 50 tills in a single request. Each row is validated and persisted independently — a failure in one item does not block the others. The response reflects the outcome of each item individually, and the HTTP status reflects the overall result: 200 if all items succeeded, 207 if some failed, or 400 if all failed.

Each row identifies the till to update using identifierName and identifierValue. All other fields are optional and use patch semantics: fields absent from the request JSON are left unchanged. Null and patch semantics vary per field — see the body parameters table for the exact behavior of each field.

Example request

curl -X PUT "https://{host}/v2/locations/tills" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "X-CAP-API-AUTH-ORG-ID: {orgId}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "identifierName": "CODE",
      "identifierValue": "till-north-01",
      "name": "North Till Primary",
      "externalIds": {
        "erpId": "ERP-TILL-001"
      },
      "customFields": {
        "till_cf1": "value1"
      }
    }
  ]'

Prerequisites

Authenticate using Basic authentication (Base64-encoded username:password).

Body parameters

Pass a JSON array of till update objects. Maximum 50 items per request.

Note: The Updatable column indicates whether the field can be changed after creation. identifierName and identifierValue identify the target till and are never updated themselves.

Field	Type	Required	Description	Updatable
`identifierName`	string	Required	How the target till is identified. Must be one of: `ID` (internal system ID), `CODE` (till code), `EXTERNAL_ID` (external identifier value). Case-insensitive.	No
`identifierValue`	string	Required	The identifier value matching `identifierName`.	No
`name`	string	Optional	Display name for the till. Cannot be set to `null` or empty. Max 100 characters. Accepts letters, digits, underscores, and spaces.	Yes
`description`	string	Optional	Free-text description. Set to `null` to clear the stored value.	Yes
`isAdmin`	boolean	Optional	Whether the till has admin access.	Yes
`isActive`	boolean	Optional	Whether the till is active. Activation fails if the parent store is inactive. Deactivation fails if the till has active child entities.	Yes
`storeParentCode`	string	Optional	Code of the parent store. Cannot be set to `null`. Provide a valid store code to change the parent store.	Yes
`externalIds`	object	Optional	Key-value map of external identifiers (`{"typeName": "value"}`). Omit to preserve existing values. Pass `null` to clear all external identifiers. Pass `{}` to make no change. Set a key's value to `null` to remove that specific key. Maximum five entries. Keys and values must not exceed 200 characters each.	Yes
`customFields`	object	Optional	Key-value map of custom field values. Omit to preserve existing values. Pass `null` to clear all custom field values. Pass `{}` to make no change. Set a key's value to `null` to remove that specific key. Keys must match custom fields configured for the org.	Yes

Example response

{
  "response": [
    {
      "entityId": 76500001,
      "result": {
        "identifierName": "CODE",
        "identifierValue": "till-north-01",
        "name": "North Till Primary",
        "externalIds": {
          "erpId": "ERP-TILL-001"
        },
        "customFields": {
          "till_cf1": "value1"
        }
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 76500001,
      "result": {
        "identifierName": "CODE",
        "identifierValue": "till-north-01",
        "name": "North Till Primary"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "identifierName": "CODE",
        "identifierValue": "till-does-not-exist"
      },
      "errors": [
        {
          "status": false,
          "code": 1260,
          "message": "till not found for passed identifiers"
        }
      ],
      "warnings": []
    }
  ],
  "totalCount": 2,
  "failureCount": 1
}

Response parameters

Field	Type	Description
`response`	array	One entry per input item, in the same order as the request.
`.entityId`	integer	System-assigned ID of the updated till. Present when the till was identified, regardless of whether the update succeeded. Absent when the till could not be identified, or when an unexpected error occurs.
`.result`	object	Object containing the fields submitted for this till, echoed from the request. Present for all items regardless of success or failure.
`.errors`	array	Errors for this item. Empty when the item succeeded.
`..code`	integer	Numeric error code.
`..message`	string	Error message.
`..status`	boolean	Status flag for the error entry.
`.warnings`	array	Non-fatal warnings for this item. The till update may still succeed even when warnings are present.
`..code`	integer	Numeric warning code.
`..message`	string	Warning message.
`..status`	boolean	Status flag for the warning entry.
`totalCount`	integer	Total number of items in the request.
`failureCount`	integer	Number of items that failed to update.

Error & warning codes

Code	Error number	Type	Description
`BULK_REQUEST_LIMIT_EXCEEDED`	1246	Error	The request contains more than 50 items. Maximum allowed is 50. HTTP 400.
`IDENTIFIER_REQUIRED`	1249	Error	`identifierName` or `identifierValue` is missing or blank. HTTP 400.
`INVALID_IDENTIFIER_TYPE`	1250	Error	`identifierName` must be `ID`, `CODE`, or `EXTERNAL_ID`. HTTP 400.
`IDENTIFIER_VALUE_INVALID`	1251	Error	`identifierValue` is not a valid integer when `identifierName` is `ID`. HTTP 400.
`TILL_NAME_NOT_FOUND`	1260	Error	Till not found for the given `ID`, `CODE`, or `EXTERNAL_ID`. HTTP 400.
`DUPLICATE_ENTITY_IN_REQUEST`	1253	Error	Two or more rows in the request resolve to the same till. HTTP 207 (first wins — the first occurrence in the batch is updated; later duplicates are rejected).
`NAME_ALREADY_EXISTS_ORG`	1206	Error	A name in the request matches another till in the org, or two rows in the batch share the same name. HTTP 207 (first wins).
`NAME_CANNOT_BE_NULL`	1252	Error	`name` is set to `null` or an empty string. HTTP 400.
`REGEX_MATCH_FAILED`	1219	Error	`name` contains characters that are not letters, digits, underscores, or spaces. HTTP 400.
`NAME_LENGTH_EXCEEDS_LIMIT`	1264	Error	`name` exceeds 100 characters. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	`storeParentCode` does not match an active store in the org; or a `customFields` key does not match a configured custom field for the org; or adding external identifiers would exceed the five-entry limit. HTTP 400.
`GLOBAL_ERR_MISSING_MANDATORY_FIELD`	403	Error	The parent store referenced by `storeParentCode` is missing a required locale (timezone, language, or currency); or an `externalIds` key or value is blank. HTTP 400.
`PARENT_NOT_ACTIVE`	1258	Error	`isActive` is set to `true` but the parent store is inactive. HTTP 400.
`CHILDREN_STILL_ACTIVE`	1259	Error	`isActive` is set to `false` but the till has active child entities. HTTP 400.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate values in `externalIds` within the same request. HTTP 400.
`EXTERNAL_ID_ALREADY_EXISTS_ORG`	1245	Error	One or more `externalIds` values are already assigned to another entity in the org. HTTP 400.
`EXTERNAL_ID_KEY_TOO_LONG`	1261	Error	An `externalIds` key exceeds 200 characters. HTTP 400.
`EXTERNAL_ID_VALUE_TOO_LONG`	1262	Error	An `externalIds` value exceeds 200 characters. HTTP 400.