Add tills in bulk

Time	Status	User Agent
Retrieving recent requests…

Create up to 50 tills in a single request. Each till is validated and persisted independently; a failure in one item doesn't block the others. The response reflects the outcome of each item individually, and the HTTP status reflects the overall result: 201 If all items succeeded, 207 If some failed, or 400 If all failed.

Example request

curl -X POST "https://{host}/v2/locations/tills" \
  -H "Authorization: Basic {base64-encoded-credentials}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "code": "till-north-01",
      "name": "North Till 01",
      "storeParentCode": "store-north-01",
      "description": "Primary till for the north store",
      "isActive": true,
      "isAdmin": false,
      "isDefault": false,
      "customFields": {
        "tillcf1": "value1"
      }
    }
  ]'

Prerequisites

Authenticate using Basic authentication (Base64-encoded username:password).
The parent store (storeParentCode) must exist and be active in the org.
The parent store must have language, currency, and timezone configured. Tills inherit locale from their parent store automatically; there are no locale fields in the till request.

Body parameters

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

Field	Type	Required	Description
`code`	string	Required	Unique code for the till in the org. Accepts lowercase letters, digits, periods (`.`), underscores (`_`), and hyphens (`-`). Must start with a lowercase letter or digit. Max 50 characters.
`name`	string	Required	Display name for the till. Accepts letters, digits, underscores, and spaces. Cannot equal `root` (any case). Max 100 characters.
`storeParentCode`	string	Required	Code of the parent store this till belongs to. Must be an existing active store. The till inherits `language`, `currency`, and `timezone` from this store; the parent store must have all three configured.
`description`	string	Optional	Free-text description of the till.
`isActive`	boolean	Optional	Whether the till is active. Defaults to `true` when omitted.
`isAdmin`	boolean	Optional	Whether this till has admin privileges. Defaults to `false`.
`isDefault`	boolean	Optional	Whether this is the default till for the parent store. Defaults to `false`.
`externalIds`	object	Optional	Object containing key-value pairs of external identifiers for the till. Maximum five entries. Keys and values must be non-blank and no longer than 200 characters each. Values must be unique within the request and not already assigned to another entity in the org.
`customFields`	object	Optional	Object containing custom field key-value pairs for the till. Keys must match custom fields configured for the org (matched case-insensitively).

Example response

{
  "response": [
    {
      "entityId": 75251044,
      "result": {
        "code": "till-north-01",
        "name": "North Till 01",
        "description": "Primary till for the north store",
        "isActive": true,
        "isAdmin": false,
        "storeParentCode": "store-north-01",
        "customFields": {
          "tillcf1": "test-value"
        },
        "isDefault": false
      },
      "errors": [],
      "warnings": []
    }
  ],
  "totalCount": 1,
  "failureCount": 0
}

Partial failure example (HTTP 207):

{
  "response": [
    {
      "entityId": 75251036,
      "result": {
        "code": "till-north-01",
        "name": "North Till 01",
        "isActive": true,
        "isAdmin": false,
        "storeParentCode": "store-north-01"
      },
      "errors": [],
      "warnings": []
    },
    {
      "result": {
        "code": "till-north-01",
        "name": "North Till 01 Duplicate",
        "isActive": true,
        "isAdmin": false,
        "storeParentCode": "store-north-01"
      },
      "errors": [
        {
          "status": false,
          "message": "Code already Exists Orgs",
          "code": 1220
        }
      ],
      "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 created till. Absent when the item failed.
`.result`	object	Object containing the submitted till fields, 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.
`..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 create.

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.
`CODE_NOT_SET`	1247	Error	`code` is missing or blank. HTTP 400.
`NAME_NOT_SET`	1200	Error	`name` is missing or blank. HTTP 400.
`REGEX_MATCH_FAILED`	1219	Error	`code` or `name` failed format validation. HTTP 400.
`NAME_LENGHT_NOT_VALID`	1218	Error	`code` exceeds 50 characters. HTTP 400.
`NAME_LENGTH_EXCEEDS_LIMIT`	1264	Error	`name` exceeds 100 characters. HTTP 400.
`NAME_ROOT_NOT_ALLOWED`	1210	Error	`name` cannot equal `root` (any case). HTTP 400.
`GLOBAL_ERR_MISSING_MANDATORY_FIELD`	403	Error	A required field is missing. Applies to `storeParentCode`, locale fields missing on the parent store, and blank `externalIds` keys or values. HTTP 400.
`PARAM_TYPE_IS_NOT_VALID`	1217	Error	A field value is invalid. Applies to a `storeParentCode` that doesn't match an active store, more than five `externalIds` entries, and invalid `customFields` key names. HTTP 400.
`CODE_ALREADY_EXISTS_ORG`	1220	Error	A till with this code already exists in the org, or a duplicate `code` appears in the same request. HTTP 400.
`NAME_ALREADY_EXISTS_ORG`	1206	Error	A till with this name already exists in the org. HTTP 400.
`NAME_ALREADY_EXISTS_ZION`	1207	Error	The till code already exists in the authentication system. HTTP 400.
`ZION_CAll_FAILED`	1212	Error	The check against the authentication system failed. Retry the 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.
`DUPLICATE_EXTERNAL_ID_IN_REQUEST`	1248	Error	Duplicate `externalIds` values in the same request. 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.
`ORG_ENTITY_TYPE_LIMIT_EXCEEDED`	1225	Error	The parent store has reached its configured limit for tills. HTTP 400.
`SERVICE_CALL_FAILED`	1213	Error	The till couldn't be created because the ID generation service or authentication service returned an error. Retry the request. HTTP 400.
`PARAM_TYPE_SET_TO_DEFAULT`	1215	Warning	`isActive` was not provided and defaulted to `true`.

Example request

Prerequisites

Body parameters

Example response

Response parameters

Error & warning codes

201All tills created successfully.

207Partial success — some tills created, some failed.

400All items failed, batch contains more than 50 items, or empty request body.