# PATCH /v1/categories/{id}

> Rename a category, change the settings its figures use, or both.

Markdown twin of https://panlytics.net/developers/api/categories-update (last updated 2026-10-25). Every page of the Panlytics developer docs is listed at https://panlytics.net/developers/llms.txt, and all of them are in one file at https://panlytics.net/developers/llms-full.txt. The site guide is https://panlytics.net/llms.txt.

## What it does

A new name needs the shops ability; settings need the sheet ability. Send the `updatedAt` you read, or the same time in an If-Unmodified-Since header, and the change is refused with 409 when somebody changed the category after it. After a change the figures are worked out again at once, as they are in the app.

## Who may call it

A key whose maker's role holds `sheet` (edit the sheet and upload a report), after the fence, for the shop or category it names. Some uses also need `shops` (open, rename and archive shops, and connect their systems): the description above says which.

## Request

```http
PATCH https://panlytics.net/api/v1/categories/{id}
```

### Parameters

| Name | In | Type | Required | What it is |
| --- | --- | --- | --- | --- |
| `id` | path | integer | Yes | The category's id. |
| `Authorization` | header | string | Yes | Bearer, a space, then the key. |
| `If-Unmodified-Since` | header | string | No | The category's `updatedAt` as you read it, instead of sending it in the body. |

### Body

Sent as `application/json`.

| Field | Type | Required | What it is |
| --- | --- | --- | --- |
| `name` | string | No | A new name, as people in the company say it. |
| `settings` | object | No | Only the settings to change. Every value is a number of zero or more; periodDays is at least 1. |
| `settings.periodDays` | number | No | How many days the newest report covers. |
| `settings.delTimeDs` | number | No | Days until the next delivery, as the report's file says it. |
| `settings.targetSto` | number | No | How many times a year the stock should sell through, used to class products by sales. |
| `settings.targetRoce` | number | No | The return wanted on the money tied up in stock, used to class products by margin. |
| `settings.co2PerWastePc` | number | No | The CO2e of one wasted item, in kg. |
| `settings.carbonTaxPerKgCo2` | number | No | What one kg of CO2e costs, in euros. |
| `settings.labourCostPerHour` | number | No | What an hour of staff time costs, in euros. |
| `settings.wasteHandlingMinPerPc` | number | No | Minutes of staff time to handle one wasted item. |
| `settings.orderEveryDs` | number | No | Days between orders. 0 keeps what the report's file says. |
| `settings.leadTimeDs` | number | No | The days a delivery takes, for every product of the category. 0 keeps what the report's file says. |
| `settings.shelfLifeDs` | number | No | How many days a product keeps, for every product of the category. 0 keeps what the report's file says. |
| `settings.demandNoisePhi` | number | No | How much daily sales jump around: their variance divided by their mean. 1 is an even pace; groceries run near 3.3, which is used when this is 0. |
| `settings.shelvingEurPerPc` | number | No | What it costs to put one piece on the shelf, in euros. A wasted piece costs it twice. |
| `updatedAt` | string (ISO 8601) | No | The `updatedAt` you read. The change is refused with 409 when the category changed after it. The If-Unmodified-Since header does the same. |

### Example request

```bash title="curl"
curl -X PATCH https://panlytics.net/api/v1/categories/40 \
  -H "Authorization: Bearer $PANLYTICS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "settings": {
    "orderEveryDs": 7,
    "leadTimeDs": 3
  },
  "updatedAt": "2026-10-20T07:12:00.000Z"
}'
```
```python title="Python"
import os

import requests

response = requests.patch(
    "https://panlytics.net/api/v1/categories/40",
    headers={"Authorization": f"Bearer {os.environ['PANLYTICS_KEY']}"},
    json={
      "settings": {
        "orderEveryDs": 7,
        "leadTimeDs": 3
      },
      "updatedAt": "2026-10-20T07:12:00.000Z"
    },
    timeout=60,
)
response.raise_for_status()
print(response.json())
```
```typescript title="TypeScript"
const response = await fetch("https://panlytics.net/api/v1/categories/40", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.PANLYTICS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "settings": {
      "orderEveryDs": 7,
      "leadTimeDs": 3
    },
    "updatedAt": "2026-10-20T07:12:00.000Z"
  }),
});
if (!response.ok) throw new Error(`Panlytics answered ${response.status}`);
console.log(await response.json());
```

## Response

`200`: The answer, as JSON.

| Field | Type | Always there | What it is |
| --- | --- | --- | --- |
| `id` | integer | Yes | The category's id. |
| `shopId` | integer | Yes | The shop the category belongs to. |
| `name` | string | Yes | The category's name, as people in the company say it. |
| `reportId` | integer | Yes | The newest report of this category. Its figures are the ones every endpoint answers with. |
| `products` | integer | Yes | How many products the newest report holds. |
| `uploadedAt` | string (ISO 8601) | Yes | When the newest report was uploaded, in UTC. |
| `updatedAt` | string (ISO 8601) | Yes | When the newest report or its settings last changed. Send it back as `updatedAt` on PATCH. |
| `settings` | object | Yes | The settings the category's figures are worked out with. |
| `settings.periodDays` | number | Yes | How many days the newest report covers. |
| `settings.delTimeDs` | number | Yes | Days until the next delivery, as the report's file says it. |
| `settings.targetSto` | number | Yes | How many times a year the stock should sell through, used to class products by sales. |
| `settings.targetRoce` | number | Yes | The return wanted on the money tied up in stock, used to class products by margin. |
| `settings.co2PerWastePc` | number | Yes | The CO2e of one wasted item, in kg. |
| `settings.carbonTaxPerKgCo2` | number | Yes | What one kg of CO2e costs, in euros. |
| `settings.labourCostPerHour` | number | Yes | What an hour of staff time costs, in euros. |
| `settings.wasteHandlingMinPerPc` | number | Yes | Minutes of staff time to handle one wasted item. |
| `settings.orderEveryDs` | number | Yes | Days between orders. 0 keeps what the report's file says. |
| `settings.leadTimeDs` | number | Yes | The days a delivery takes, for every product of the category. 0 keeps what the report's file says. |
| `settings.shelfLifeDs` | number | Yes | How many days a product keeps, for every product of the category. 0 keeps what the report's file says. |
| `settings.demandNoisePhi` | number | Yes | How much daily sales jump around: their variance divided by their mean. 1 is an even pace; groceries run near 3.3, which is used when this is 0. |
| `settings.shelvingEurPerPc` | number | Yes | What it costs to put one piece on the shelf, in euros. A wasted piece costs it twice. |

### Example response

```json title="200"
{
  "id": 40,
  "shopId": 12,
  "name": "Beverages",
  "reportId": 311,
  "products": 412,
  "uploadedAt": "2026-10-20T07:12:00.000Z",
  "updatedAt": "2026-10-25T09:30:00.000Z",
  "settings": {
    "periodDays": 30,
    "delTimeDs": 2,
    "targetSto": 12,
    "targetRoce": 0.3,
    "co2PerWastePc": 0.5,
    "carbonTaxPerKgCo2": 0,
    "labourCostPerHour": 25,
    "wasteHandlingMinPerPc": 1,
    "orderEveryDs": 7,
    "leadTimeDs": 3,
    "shelfLifeDs": 0,
    "demandNoisePhi": 1,
    "shelvingEurPerPc": 0
  }
}
```

## Errors

A refusal is JSON with a `code`, a sentence in `error`, and a `requestId` when the fault is ours. Read the code, not the sentence. Every code is listed on [Errors](https://panlytics.net/developers/security/errors).

| Status | Code | When | What to do |
| --- | --- | --- | --- |
| 400 | `api.invalid` | A path id, a query parameter, a header or a body field is missing or not valid. `detail` names the field. | Read that endpoint in the API reference, correct the field and call again. |
| 401 | `api.key_missing` | The call had no Authorization header. | Send the key in the Authorization header as Bearer, then call again. |
| 401 | `api.key_refused` | The key is wrong, revoked, past its end, or its maker or company no longer allows it (developer mode off, the maker removed or switched off, or the maker's role lost the developer ability). | Ask the person who gave you the key to make a new one. |
| 401 | `api.wrong_key_kind` | This key does not open these endpoints. | Use the key these endpoints were made for, or ask the person who gave you the key. |
| 403 | `refused` | The key's maker may not do this here: their role lacks the ability, or the shop or category is outside their reach. | Ask the CEO for a role that allows it, or call it for a shop or category the role reaches. |
| 403 | `auth.not_fresh` | This step needs you to prove it is you. | Confirm your password or passkey, then try again. |
| 403 | `refused.demo` | The key belongs to a shared demo account, which may not change anything. | Use a key made in a real company account. |
| 404 | `not_found.said` | Nothing with that id in the key's company. An id of another company answers the same. | Check the id. List the shop or category it belongs to and take the id from there. |
| 409 | `report.none` | There is no report yet to work from. | Upload a report first, with POST /v1/shops/{id}/reports. |
| 409 | `api.stale` | The category changed after the `updatedAt` you sent. | Read it again, then send your change with the new updatedAt. |
| 429 | `api.rate_limited` | The key made more than 120 calls in this minute. Wait the seconds in Retry-After. | Wait the seconds in Retry-After, then call again. |
| 500 | `server` | Something failed on our side. The answer carries a requestId to quote. | Try again in a minute; if it keeps happening, report it. |
| 503 | `developer.unavailable` | API keys are not set up on this deployment yet. | Report it, and we will switch them on. |