Inventory & Products | Shelves | Set Shelves

Set Shelves

This endpoint creates new shelves or updates existing shelves through https://easycms.fi/public_api/set_shelves/. A shelf always belongs to a stock location (warehouse).

Endpoint and Method

• Endpoint: https://easycms.fi/public_api/set_shelves/
• Method: POST
• Content-Type: application/json

Authentication

• Header: Authorization1: {API_TOKEN}
• Body parameters: username, password, account

Request Parameters

Creating a shelf (omit shelf_id)

Parameter	Type	Required	Description
username	string	Yes	API username
password	string	Yes	API password
account	string	Yes	Account domain
location_id	integer	Yes	Location ID the shelf belongs to (must exist)
shelf_name	string | object	No	Shelf name. A plain string is stored as en_GB; or pass a {lang: name} object for multiple languages. Defaults to "Shelf <N>"
shelf_number	integer	No	Sorting number within the location. Defaults to MAX(shelf_number) + 1 (the same rule the CMS itself uses)
parent_id	integer	No	Parent shelf ID (default 0)
visible	integer	No	1 = visible (default), 0 = hidden

Updating a shelf (include shelf_id)

Parameter	Type	Required	Description
username	string	Yes	API username
password	string	Yes	API password
account	string	Yes	Account domain
shelf_id	integer	Yes	Shelf ID to update
location_id	integer	No	Move the shelf to another (existing) location
shelf_name	string | object	No	New shelf name (string or {lang: name} object)
shelf_number	integer	No	New sorting number
parent_id	integer	No	Parent shelf ID
visible	integer	No	1 = visible, 0 = hidden

Only the fields you provide are updated. cr_shelf_id is reserved for the cash-register sync and is ignored.

Behavior

• Create: validates that location_id exists, resolves shelf_number (MAX+1 within the location when omitted), inserts the shelf, and returns the new shelf_id.
• Update: validates that shelf_id exists, applies only the provided fields, and returns the refreshed row plus a changes summary (old → new per field).
• Every shelf insert/update writes to the account's activity log automatically.

Response Format

{
    "status": "success",
    "message": "Shelf created successfully",
    "data": {
        "shelf_id": 123,
        "shelf": {
            "shelf_id": "123",
            "location_id": "7",
            "shelf_number": "3",
            "shelf_name": "a:1:{s:5:\"en_GB\";s:8:\"Shelf 3\";}",
            "parent_id": "0",
            "visible": "1",
            "cr_shelf_id": null
        }
    },
    "changes": {
        "shelf_created": {
            "shelf_id": 123,
            "location_id": 7,
            "shelf_number": 3
        }
    }
}

Update responses carry message: "Shelf updated successfully" and a changes.shelf object with old/new values per updated field.

Error Responses

HTTP Code	Error Code	Description
400	MISSING_REQUIRED_FIELDS	location_id missing on create
400	NOTHING_TO_UPDATE	No valid shelf fields provided on update
404	LOCATION_NOT_FOUND	location_id does not exist
404	SHELF_NOT_FOUND	shelf_id does not exist
500	CREATE_FAILED / UPDATE_FAILED	Database write failed

Call Examples

Create a shelf

curl -X POST "https://easycms.fi/public_api/set_shelves/" \
  -H "Content-Type: application/json" \
  -H "Authorization1: YOUR_API_TOKEN" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "account": "your_account",
    "location_id": 7,
    "shelf_name": {"en_GB": "Back room", "fi": "Takahuone"}
  }'

Rename and hide a shelf

curl -X POST "https://easycms.fi/public_api/set_shelves/" \
  -H "Content-Type: application/json" \
  -H "Authorization1: YOUR_API_TOKEN" \
  -d '{
    "username": "your_username",
    "password": "your_password",
    "account": "your_account",
    "shelf_id": 123,
    "shelf_name": "Storage B",
    "visible": 0
  }'