> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# API reference stores

> Manage physical outlets through the Admin Interface API stores endpoint: retrieve, create, and update store data including address and zip code prefixes.

The `stores/` endpoint provides an interface for managing stores (outlets) in our shop system. With this interface you can retrieve store data, create new stores and update existing stores.

## Supported methods

List of all supported methods.

| **Command/Info**     | **Endpoints** | **GET**               | **POST**              | **PUT**               | **DELETE**            |
| -------------------- | ------------- | --------------------- | --------------------- | --------------------- | --------------------- |
| **Store management** | stores/       | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> | <Icon icon="check" /> |

## Data fields of a store

| **Name**                         | **Type** | **Meaning**                                                                                                                                       |
| -------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                             | number   | Unique ID of the store (read-only).                                                                                                               |
| `info`                           | object   | Object with general information about the store.                                                                                                  |
| `info.name`                      | string   | Name of the store.                                                                                                                                |
| `info.street`                    | string   | Street and house number of the store.                                                                                                             |
| `info.zipCode`                   | string   | Postal code of the store.                                                                                                                         |
| `info.city`                      | string   | City of the store.                                                                                                                                |
| `info.country`                   | string   | Country code of the store (e.g. `DE`).                                                                                                            |
| `info.zipcodes`                  | array    | List of postal code prefixes assigned to the store.                                                                                               |
| `info.zipcodes[].prefix`         | string   | Postal code prefix.                                                                                                                               |
| `info.zipcodes[].country`        | string   | Country code of the postal code prefix.                                                                                                           |
| `info.timeZone`                  | string   | Time zone of the store (e.g. `Europe/Berlin`).                                                                                                    |
| `info.metadata`                  | object   | Arbitrary additional information about the store.                                                                                                 |
| `storageId`                      | string   | Storage ID of the store (used for the "Pickup at store" feature).                                                                                 |
| `subshops`                       | array    | List of subshops for which this store is enabled.                                                                                                 |
| `location`                       | object   | Geographic coordinates of the store.                                                                                                              |
| `location.longitude`             | number   | Longitude of the store.                                                                                                                           |
| `location.latitude`              | number   | Latitude of the store.                                                                                                                            |
| `openingHours`                   | object   | Opening hours of the store.                                                                                                                       |
| `openingHours.{0-6}`             | array    | Regular opening hours per day of the week (0=Sunday, 6=Saturday). Each entry is an array of time slots. An empty array means "closed".            |
| `openingHours.{0-6}[].startTime` | number   | Opening time in seconds since the start of the day (e.g. 08:00 = `28800`).                                                                        |
| `openingHours.{0-6}[].endTime`   | number   | Closing time in seconds since the start of the day (e.g. 18:00 = `64800`). Must be greater than `startTime`.                                      |
| `openingHours.specialDays`       | object   | Special opening hours. The key has the format `<month>-<day>` (e.g. `12-24`). Each value is an array of time slots (as for the days of the week). |
| `clickAndCollect`                | boolean  | Indicates whether the store is enabled for click & collect.                                                                                       |
| `createdAt`                      | string   | Time of creation (ISO 8601 format, UTC, read-only).                                                                                               |
| `updatedAt`                      | string   | Time of the last update (ISO 8601 format, UTC, read-only).                                                                                        |

#### Example of the record

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 42,
    "info": {
        "name": "Markt Musterstadt",
        "street": "Musterstra\u00dfe 1",
        "zipCode": "12345",
        "city": "Musterstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "123", "country": "DE" },
            { "prefix": "124", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-99",
    "subshops": ["deutsch", "english"],
    "location": {
        "longitude": 13.405,
        "latitude": 52.52
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 72000 }],
        "6": [{ "startTime": 36000, "endTime": 57600 }],
        "specialDays": {
            "12-24": [{ "startTime": 28800, "endTime": 43200 }],
            "12-25": []
        }
    },
    "clickAndCollect": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-20T14:45:00.000Z"
}
```

## Using the methods

### GET stores

This method returns a list of all stores from the shop's admin interface.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/stores/
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "endReached": true,
    "items": [
        {
            "id": 42,
            "info": {
                "name": "Markt Musterstadt",
                "street": "Musterstra\u00dfe 1",
                "zipCode": "12345",
                "city": "Musterstadt",
                "country": "DE",
                "zipcodes": [
                    { "prefix": "123", "country": "DE" }
                ],
                "timeZone": "Europe/Berlin",
                "metadata": {}
            },
            "storageId": "storage-99",
            "subshops": ["deutsch"],
            "location": {
                "longitude": 13.405,
                "latitude": 52.52
            },
            "openingHours": {
                "0": [],
                "1": [{ "startTime": 28800, "endTime": 64800 }],
                "2": [{ "startTime": 28800, "endTime": 64800 }],
                "3": [{ "startTime": 28800, "endTime": 64800 }],
                "4": [{ "startTime": 28800, "endTime": 64800 }],
                "5": [{ "startTime": 28800, "endTime": 72000 }],
                "6": [{ "startTime": 36000, "endTime": 57600 }],
                "specialDays": {}
            },
            "clickAndCollect": true,
            "createdAt": "2025-01-15T10:30:00.000Z",
            "updatedAt": "2025-06-20T14:45:00.000Z"
        }
    ],
    "nextPageToken": "Mw",
    "totalCount": 1
}
```

#### Filter fields

`id`, `subshops`, `clickAndCollect`, `storageId`, `createdAt`, `updatedAt`

#### Sort fields

`id`, `clickAndCollect`, `storageId`, `createdAt`, `updatedAt`

#### Error codes

| **Error**        | **Type**            | **Reason**                                                              |
| ---------------- | ------------------- | ----------------------------------------------------------------------- |
| 401 Unauthorized |                     | Not authorized: you are not logged in.                                  |
| 403 Forbidden    |                     | You do not have the required permissions to read store data.            |
| 400 Bad Request  | "invalidValue"      | `size` ∉ \[1;300] <br /> `pageToken` is not a number or is less than 0. |
| 400 Bad Request  | "unknownDataField"  | A filter or sort field is invalid.                                      |
| 400 Bad Request  | "unknownOperation"  | A filter type is invalid.                                               |
| 400 Bad Request  | "invalidCharacters" | `size` is not an integer. <br /> A filter value is invalid.             |
| 400 Bad Request  | "syntaxError"       | `sort` contains more than one or no ":".                                |

### GET stores/\{id}

This method retrieves the details of a single store by its unique store ID.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/stores/42
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 42,
    "info": {
        "name": "Markt Musterstadt",
        "street": "Musterstra\u00dfe 1",
        "zipCode": "12345",
        "city": "Musterstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "123", "country": "DE" },
            { "prefix": "124", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-99",
    "subshops": ["deutsch"],
    "location": {
        "longitude": 13.405,
        "latitude": 52.52
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 72000 }],
        "6": [{ "startTime": 36000, "endTime": 57600 }],
        "specialDays": {
            "12-24": [{ "startTime": 28800, "endTime": 43200 }]
        }
    },
    "clickAndCollect": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-20T14:45:00.000Z"
}
```

#### Error codes

| **Error**        | **Type**       | **Reason**                                                   |
| ---------------- | -------------- | ------------------------------------------------------------ |
| 401 Unauthorized |                | Not authorized: you are not logged in.                       |
| 403 Forbidden    |                | You do not have the required permissions to read store data. |
| 400 Bad Request  | "invalidValue" | The store ID is invalid (not a valid number).                |
| 404 Not Found    |                | The store with the given ID was not found.                   |

### POST stores

This method creates a new store. All fields except `id`, `createdAt` and `updatedAt` are required on creation.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/stores
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "info": {
        "name": "Neuer Markt",
        "street": "Beispielstra\u00dfe 5",
        "zipCode": "54321",
        "city": "Beispielstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "543", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-10",
    "subshops": ["deutsch"],
    "location": {
        "longitude": 9.993,
        "latitude": 53.551
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 64800 }],
        "6": [{ "startTime": 36000, "endTime": 43200 }],
        "specialDays": {}
    },
    "clickAndCollect": false
}
```

#### Response

The response contains the full store object including the assigned `id` and the `createdAt` and `updatedAt` fields.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 43,
    "info": {
        "name": "Neuer Markt",
        "street": "Beispielstra\u00dfe 5",
        "zipCode": "54321",
        "city": "Beispielstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "543", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-10",
    "subshops": ["deutsch"],
    "location": {
        "longitude": 9.993,
        "latitude": 53.551
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 64800 }],
        "6": [{ "startTime": 36000, "endTime": 43200 }],
        "specialDays": {}
    },
    "clickAndCollect": false,
    "createdAt": "2025-06-20T14:45:00.000Z",
    "updatedAt": "2025-06-20T14:45:00.000Z"
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                                                                        |
| ---------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                    | Not authorized: you are not logged in.                                                                            |
| 403 Forbidden    |                    | You do not have the required permissions to create store data.                                                    |
| 400 Bad Request  | "badRequest"       | The request body is not a valid JSON object.                                                                      |
| 400 Bad Request  | "missing"          | A required field is missing in the request body. The affected field is specified in `errorContext`.               |
| 400 Bad Request  | "invalidFormat"    | A field has an incorrect data type. The expected type is specified in `errorContext` under `expectedType`.        |
| 400 Bad Request  | "invalidValue"     | A field value is invalid (e.g. invalid time zone, `startTime` ≥ `endTime`, invalid date format in `specialDays`). |
| 400 Bad Request  | "unknownDataField" | An unknown field was sent in the request body.                                                                    |

### PUT stores/\{id}

This method updates an existing store by its unique store ID. One or multiple fields can be provided — only the sent fields are updated.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/stores/42
```

#### Request body

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "clickAndCollect": true,
    "storageId": "storage-77",
    "openingHours": {
        "6": [{ "startTime": 36000, "endTime": 50400 }],
        "specialDays": {
            "12-31": [{ "startTime": 28800, "endTime": 36000 }]
        }
    }
}
```

#### Response

The response contains the complete updated store object.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "id": 42,
    "info": {
        "name": "Markt Musterstadt",
        "street": "Musterstra\u00dfe 1",
        "zipCode": "12345",
        "city": "Musterstadt",
        "country": "DE",
        "zipcodes": [
            { "prefix": "123", "country": "DE" },
            { "prefix": "124", "country": "DE" }
        ],
        "timeZone": "Europe/Berlin",
        "metadata": {}
    },
    "storageId": "storage-77",
    "subshops": ["deutsch", "english"],
    "location": {
        "longitude": 13.405,
        "latitude": 52.52
    },
    "openingHours": {
        "0": [],
        "1": [{ "startTime": 28800, "endTime": 64800 }],
        "2": [{ "startTime": 28800, "endTime": 64800 }],
        "3": [{ "startTime": 28800, "endTime": 64800 }],
        "4": [{ "startTime": 28800, "endTime": 64800 }],
        "5": [{ "startTime": 28800, "endTime": 72000 }],
        "6": [{ "startTime": 36000, "endTime": 50400 }],
        "specialDays": {
            "12-24": [{ "startTime": 28800, "endTime": 43200 }],
            "12-31": [{ "startTime": 28800, "endTime": 36000 }]
        }
    },
    "clickAndCollect": true,
    "createdAt": "2025-01-15T10:30:00.000Z",
    "updatedAt": "2025-06-20T15:00:00.000Z"
}
```

#### Error codes

| **Error**        | **Type**           | **Reason**                                                                                                                                          |
| ---------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 401 Unauthorized |                    | Not authorized: you are not logged in.                                                                                                              |
| 403 Forbidden    |                    | You do not have the required permissions to update store data.                                                                                      |
| 400 Bad Request  | "invalidValue"     | The store ID is invalid (not a valid number).                                                                                                       |
| 404 Not Found    |                    | The store with the given ID was not found.                                                                                                          |
| 400 Bad Request  | "badRequest"       | The request body is not a valid JSON object.                                                                                                        |
| 400 Bad Request  | "missing"          | A required subfield is missing in an array element. Affected: `startTime` or `endTime` in time slots, `prefix` or `country` in postal code entries. |
| 400 Bad Request  | "invalidFormat"    | A field has an incorrect data type. The expected type is specified in `errorContext` under `expectedType`.                                          |
| 400 Bad Request  | "invalidValue"     | A field value is invalid (e.g. invalid time zone, `startTime` ≥ `endTime`, invalid date format in `specialDays`).                                   |
| 400 Bad Request  | "unknownDataField" | An unknown field was sent in the request body.                                                                                                      |

### DELETE stores/\{id}

This method deletes an existing store by its unique store ID.

#### Example

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
https://www.<your-shop>.de/admin/api/v1/stores/42
```

#### Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
    "success": true
}
```

#### Error codes

| **Error**        | **Type**       | **Reason**                                                 |
| ---------------- | -------------- | ---------------------------------------------------------- |
| 401 Unauthorized |                | Not authorized: you are not logged in.                     |
| 403 Forbidden    |                | You do not have the required permissions to delete stores. |
| 400 Bad Request  | "invalidValue" | `id` is invalid.                                           |
| 404 Not Found    |                | Store with `id`=`{id}` was not found.                      |

## Support

Bei technischen Fragen und Hilfestellungen ist unser Support-Team für Sie erreichbar: [Zum Kundenportal](https://websale.atlassian.net/servicedesk/customer/portal/6)

Bitte senden Sie uns eine möglichst detaillierte Beschreibung sowie Screenshots, Requests/Antworten, damit wir Ihre Anfrage zeitnah und zielführend beantworten können.