Uploads the store data that notifications are built from: whether language mutations are on, the list of languages, the list of stores (multistore), order statuses and return statuses. Send only the items you want to change — the others stay as they are. The response always returns the current values of all items.

## API URL

The URL used to send the HTTP requests:

```url
https://portal.bulkgate.com/api/1.0/eshop/setup
```

> [!NOTE]
> If the request does not reach its destination, repeat it on the [backup server](https://www.bulkgate.com/en/docs/api-administration-tokens/api-backup-server/) `backup1.bulkgate.com`.

## Supported HTTP methods

- `POST` - `application/json`

```http
POST /api/1.0/eshop/setup HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json
```

## Parameters table

| PARAMETER NAME      | VALUE                                                        | MANDATORY | DEFAULT VALUE |
|:--------------------|:-------------------------------------------------------------|:----------|:--------------|
| application_id      | [Application ID](https://www.bulkgate.com/en/docs/api-administration-tokens/api-administration/)                | **Yes**   | -             |
| application_token   | [Application authentication token](https://www.bulkgate.com/en/docs/api-administration-tokens/api-tokens/)      | **Yes**   | -             |
| language_mutation   | Language mutations on — `true` or `false`                    | No        | Unchanged     |
| languages           | Store languages — a `code: name` object                      | No        | Unchanged     |
| stores              | Stores (multistore) — an `id: name` object                   | No        | Unchanged     |
| order_status_list   | Order statuses — an `id: name` object                        | No        | Unchanged     |
| return_status_list  | Return statuses — an `id: name` object                       | No        | Unchanged     |

Each list you send **replaces the whole list** — items you leave out disappear from the portal.

## How the portal uses the items

### Language mutations

With `language_mutation` on, customer notifications have their own text for each language in the `languages` list. The portal then picks the text by the `language` parameter you send with each [event](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-overview/). With mutations off, each customer notification has a single text and the language is ignored. Admin notifications always have a single text.

The language code is what you send in the `language` parameter — 1 to 16 letters, digits or underscores, e.g. `cs` or `en_us`. A hyphen is not allowed.

### Stores

The store id is what you send in the `shop_id` parameter. Notifications are set up for each store separately. The id has 1 to 20 letters, digits or underscores. A store without multistore sends a single store with id `0` — events without `shop_id` belong to it.

The portal fills the name of the store matching the event's `shop_id` into the `<shop_name>` variable, unless you send it yourself. When the list has no store with that id, the first store in the list is used.

### Order and return statuses

For each status in the list, the portal offers a status change notification in the **Customer SMS** and **Admin SMS** sections. The status id is the value you send in the `order_status_id` variable ([order status change](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-orders/)), or `return_status_id` ([return status change](https://www.bulkgate.com/en/docs/eshop-api/eshop-api-returns/)). The id has 1 to 29 letters, digits, underscores or hyphens, e.g. `ready-for-pickup`.

The status lists may be empty, the language and store lists may not. The name of each item is a non-empty text of at most 255 characters.

## Request example

```http-json
POST /api/1.0/eshop/setup HTTP/1.1
Host: portal.bulkgate.com
Content-Type: application/json

{
  "application_id": 451,
  "application_token": "NKN02TWE6NfBkfl-your-secret-token-Wf05GaqLIWLW4aBj",
  "language_mutation": true,
  "languages": {
    "cs": "Čeština",
    "en": "English"
  },
  "stores": {
    "0": "BulkGate Shop CZ",
    "1": "BulkGate Shop SK"
  },
  "order_status_list": {
    "processing": "Processing",
    "completed": "Completed",
    "cancelled": "Cancelled"
  }
}
```

The request above leaves the return statuses unchanged.

## Response

**On success** it returns the current values of all items. The lists are always an object, even when empty:

```json
{
    "data": {
        "language_mutation": true,
        "languages": {
            "cs": "Čeština",
            "en": "English"
        },
        "stores": {
            "0": "BulkGate Shop CZ",
            "1": "BulkGate Shop SK"
        },
        "order_status_list": {
            "processing": "Processing",
            "completed": "Completed",
            "cancelled": "Cancelled"
        },
        "return_status_list": {}
    }
}
```

A request without items changes nothing and just returns the current settings.

**On error:**

```json
{
    "type": "invalid_languages",
    "code": 400,
    "error": "Invalid languages",
    "detail": "Invalid identifier 'cs-CZ'."
}
```

Where:

- **type** and **error** (error description) are listed in the [error types table](https://www.bulkgate.com/en/docs/api-administration-tokens/api-error-types/)
- **code** is the HTTP error code
- **detail** is additional information about the error

### Error types

When any item fails validation, the portal saves nothing.

| TYPE                         | WHEN IT OCCURS                                                                      |
|:-----------------------------|:------------------------------------------------------------------------------------|
| `invalid_languages`          | The language list is empty or contains an invalid code or name.                     |
| `invalid_stores`             | The store list is empty or contains an invalid id or name.                          |
| `invalid_order_status_list`  | The order status list contains an invalid id or name.                               |
| `invalid_return_status_list` | The return status list contains an invalid id or name.                              |
| `invalid_input_parameters`   | An unknown parameter, a list given other than as an object (e.g. as text), or `language_mutation` that is not a boolean. |
| `unknown_identity`           | `application_id` or `application_token` is missing or invalid.                      |
