# Make a shop and a category

> Open a new shop through the API and start its first category with a report, in two calls.

Markdown twin of https://panlytics.net/developers/guides/make-a-shop-and-a-category (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.

## Who may do it

Opening a shop needs two things on the key's maker's role:

1. **Open, rename and archive shops, and connect their systems**, which is a Manager ability.
2. A scope that covers **every shop**. A role limited to chosen shops cannot open a new one, because the new shop would sit outside it.

The CEO has both. Anybody else needs a role the CEO or a Manager set up that way.

## 1. Open the shop

```bash title="curl"
curl -X POST https://panlytics.net/api/v1/shops \
  -H "Authorization: Bearer $PANLYTICS_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: open-harbour-2" \
  -d '{ "name": "Harbour 2", "city": "Helsinki" }'
```
```python title="Python"
import os
import requests

answer = requests.post(
    "https://panlytics.net/api/v1/shops",
    headers={
        "Authorization": f"Bearer {os.environ['PANLYTICS_KEY']}",
        "Idempotency-Key": "open-harbour-2",
    },
    json={"name": "Harbour 2", "city": "Helsinki"},
    timeout=30,
)
answer.raise_for_status()
shop = answer.json()
print(shop["id"])
```

`name` and `city` are required; `branch` and `country` are optional. The answer is `201` with the new shop:

```json title="201"
{
  "id": 31,
  "name": "Harbour 2",
  "branch": "",
  "city": "Helsinki",
  "country": "Finland",
  "createdAt": "2026-10-25T09:00:00.000Z"
}
```

The shop appears in the app at once, for everybody whose role covers every shop. A retry with the same `Idempotency-Key` answers with this same shop instead of opening a second one. [POST /v1/shops](https://panlytics.net/developers/api/shops-create) has every field and refusal.

## 2. Start its first category

A category starts with a report. Upload the shop's sales export with a `category` name and the days it covers, as [Upload a report](https://panlytics.net/developers/guides/upload-a-report) shows. Starting a category needs **Edit the sheet and upload a report** over the whole shop:

```bash title="curl"
curl -X POST https://panlytics.net/api/v1/shops/31/reports \
  -H "Authorization: Bearer $PANLYTICS_KEY" \
  -H "Idempotency-Key: harbour-2-soft-drinks" \
  -F "category=Soft drinks" \
  -F "periodDays=30" \
  -F "file=@soft-drinks.xlsx"
```

To rename the category later, or change the settings its figures use, send `PATCH /v1/categories/{id}`. See [Changing a category safely](https://panlytics.net/developers/api#changing-a-category-safely).

## Before you call

> [!WARNING]
> Opening a shop is seen by everybody in the company who covers every shop, and it is written to the audit log. An agent should ask its person before it opens one, and say the name it will use.

A shop cannot be deleted through the API. To remove one opened by mistake, a person archives it in the app. A shared demo account cannot open a shop (`403 refused.demo`).