Rename a product category or change its place in the order

inventory.category.update

POST/api/v1/households/{household_id}/commands/inventory.category.update

Command
Rigel runs it
Applies offline

Sets only the fields given. before_category_id puts it just before that category (null for last), which is the order lists that go by category use. To combine two categories, move their products with inventory.product.update and remove the empty one.

Parameters#

Rename a product category or change its place in the order: parameters
Field	Description
`household_id`pathstringrequired	The household's ID.
`Idempotency-Key`headerstringoptional	The command's ID. Reuse it when retrying the same command.

Request body#

JSON, as application/json.

Rename a product category or change its place in the order: request body fields
Field	Description
`category_id`stringrequired	A product category ID, such as pcg_01JC0000000000000000000000.
`name`stringoptional	A grouping for lists and for shopping in a store with no aisles, such as "Produce", "Dairy", "Canned", "Cleaning" or "Baby". Keep to the categories already in use. 1 to 60 characters
`before_category_id`string or nulloptional	Put it just before this category, or null for last.

Response#

200 The command was applied.

Rename a product category or change its place in the order: response fields
Field	Description
`result`objectrequired	What the command returned, such as the IDs it created.
`version`integerrequired	The household version after the command.

Errors#

Every error has the same envelope: error.code, error.message, error.details, error.recovery and error.request_id.

Rename a product category or change its place in the order: errors
Status	Code	When
`400`	`validation_failed`	A field is missing, misspelled or out of range. details.fields lists each problem.
`401`	`unauthenticated`	The request has no valid session.
`404`	`category_not_found`	Before itself. Before a category that isn't there. A category that isn't there.
`404`	`not_found`	The household doesn't exist, or you aren't a member of it.
`409`	`name_taken`	Rename to another category's name ignoring case.
`409`	`idempotency_key_reused`	The Idempotency-Key was already used for a different command.

Examples#

These are real. Each scenario is one of the command's test cases, run on a household when this site was built, and the response is what the API returned.

Rename

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000A",
  "name": "Dairy and eggs"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000A",
    name: "Dairy and eggs",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000A",
  "name": "Dairy and eggs"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R05YAYETEHZ08351R2

{
  "result": {},
  "version": 1
}

Rename to its own name in a different case

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000A",
  "name": "DAIRY"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000A",
    name: "DAIRY",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000A",
  "name": "DAIRY"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R01R0GEF7K8K3DES76

{
  "result": {},
  "version": 1
}

Move before another category renumbers only what moved

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000D",
  "before_category_id": "pcg_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000D",
    before_category_id: "pcg_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000D",
  "before_category_id": "pcg_01JC000000000000000000000B"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0C4KMPF1C6VE46EJD

{
  "result": {},
  "version": 1
}

Null moves it to the end

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000C",
  "before_category_id": null
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000C",
    before_category_id: null,
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000C",
  "before_category_id": null
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0NF0BTDZZ9ZY6ECR9

{
  "result": {},
  "version": 1
}

Moving to where it already is changes nothing

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000B",
  "before_category_id": "pcg_01JC000000000000000000000C"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000B",
    before_category_id: "pcg_01JC000000000000000000000C",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000B",
  "before_category_id": "pcg_01JC000000000000000000000C"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0NAG29BZCQHRARV15

{
  "result": {},
  "version": 1
}

Rename and move together

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000C",
  "name": "Tins",
  "before_category_id": "pcg_01JC000000000000000000000A"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000C",
    name: "Tins",
    before_category_id: "pcg_01JC000000000000000000000A",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000C",
  "name": "Tins",
  "before_category_id": "pcg_01JC000000000000000000000A"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0MWTHWBQT3C2RZ6TP

{
  "result": {},
  "version": 1
}

Rename to another category's name ignoring case

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000A",
  "name": "produce"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000A",
    name: "produce",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000A",
  "name": "produce"
}

Response, 409

HTTP/1.1 409 Conflict
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0TSYS9G1Q6G02WB07

{
  "error": {
    "code": "name_taken",
    "message": "There's already a category called Produce. No changes were applied.",
    "details": {
      "category_id": "pcg_01JC000000000000000000000B"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0TSYS9G1Q6G02WB07"
  }
}

Before itself

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000B",
  "before_category_id": "pcg_01JC000000000000000000000B"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000B",
    before_category_id: "pcg_01JC000000000000000000000B",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000B",
  "before_category_id": "pcg_01JC000000000000000000000B"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0805A1VJ10RDB50WE

{
  "error": {
    "code": "category_not_found",
    "message": "A category can't go before itself. No changes were applied.",
    "details": {
      "category_id": "pcg_01JC000000000000000000000B"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0805A1VJ10RDB50WE"
  }
}

Before a category that isn't there

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000B",
  "before_category_id": "pcg_01JC000000000000000000000E"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000B",
    before_category_id: "pcg_01JC000000000000000000000E",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000B",
  "before_category_id": "pcg_01JC000000000000000000000E"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0GS4YYDTZWXRDEMVZ

{
  "error": {
    "code": "category_not_found",
    "message": "That category isn't there any more. No changes were applied.",
    "details": {
      "category_id": "pcg_01JC000000000000000000000E"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0GS4YYDTZWXRDEMVZ"
  }
}

A category that isn't there

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA' \
  -d '{
  "category_id": "pcg_01JC000000000000000000000E",
  "name": "Snacks"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01JC4N0000AAAAAAAAAAAAAAAA",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01JC000000000000000000000E",
    name: "Snacks",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01K9BKKP003AHRZ6DMV29GQY5C/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01JC4N0000AAAAAAAAAAAAAAAA

{
  "category_id": "pcg_01JC000000000000000000000E",
  "name": "Snacks"
}

Response, 404

HTTP/1.1 404 Not Found
Content-Type: application/json
X-Request-Id: req_01K9D9S2R0YFZ2RV9Y62V1JDCC

{
  "error": {
    "code": "category_not_found",
    "message": "That category isn't there any more. No changes were applied.",
    "details": {
      "category_id": "pcg_01JC000000000000000000000E"
    },
    "recovery": "Read the current state, then send a command that fits it.",
    "request_id": "req_01K9D9S2R0YFZ2RV9Y62V1JDCC"
  }
}

Rename a category

Request, curl

curl -X POST 'https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.category.update' \
  -H "Cookie: rigel_session=$RIGEL_SESSION" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: cmd_01M6V9CSD1WFAGW269R9EHZB9D' \
  -d '{
  "category_id": "pcg_01M6V9CSAG0KYYACRJ15QGGWXF",
  "name": "Baking supplies"
}'

Request, TypeScript

const response = await fetch("https://rigel.house/api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.category.update", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Idempotency-Key": "cmd_01M6V9CSD1WFAGW269R9EHZB9D",
    Cookie: `rigel_session=${process.env.RIGEL_SESSION}`,
  },
  body: JSON.stringify({
    category_id: "pcg_01M6V9CSAG0KYYACRJ15QGGWXF",
    name: "Baking supplies",
  }),
});
const data = await response.json();

Request, HTTP

POST /api/v1/households/hh_01M6V9CS6GGVFCY7NAS8ZTQV95/commands/inventory.category.update HTTP/1.1
Host: rigel.house
Cookie: rigel_session=<your session>
Content-Type: application/json
Idempotency-Key: cmd_01M6V9CSD1WFAGW269R9EHZB9D

{
  "category_id": "pcg_01M6V9CSAG0KYYACRJ15QGGWXF",
  "name": "Baking supplies"
}

Response, 200

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_01M6V9CSD199GZQYWDAJHP41RD

{
  "result": {},
  "version": 50
}

For Rigel#

Rigel's tool for this command is inventory_category_update. Rigel runs this on its own, then says what it did. The agent guide has the rest.