> ## 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.

# Storefront API Test mode

> Query test mode via the Storefront API, activate it with a password, deactivate it and change the switches for debugging, simulated payment failures and the WEBSALE Search test API.

With the test mode endpoints of the Storefront API, you can control the shop's [test mode](/en/frontend/referenz/module/wstestmode) from your own storefront. You can query the current state, activate test mode with the test mode password and toggle the switches for debugging, simulated payment failures and the WEBSALE Search test API. You can also deactivate test mode again.

Test mode applies to the session passed in the `x-session` header. All endpoints therefore require a valid session.

***

## Supported methods

List of all supported methods.

| **Command** | **Endpoints** | **GET** | **POST** | **PUT** | **DELETE** |
| - | - | - | - | - | - |
| Query the test mode state | `testMode/status` | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |
| Activate test mode | `testMode/activate` | <Icon icon="ban" color="#DC2626" /> | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |
| Deactivate test mode | `testMode/deactivate` | <Icon icon="ban" color="#DC2626" /> | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |
| Change test mode switches | `testMode/update` | <Icon icon="ban" color="#DC2626" /> | <Icon icon="check" /> | <Icon icon="ban" color="#DC2626" /> | <Icon icon="ban" color="#DC2626" /> |

***

## Basic concept

### Mapping to shop actions

Internally, the writing endpoints execute the same shop actions as the forms in the template. The error codes therefore come from these actions. You maintain their error texts in the configuration under [actions - Test mode](/en/konfiguration/actions-fehlertexte-e-mails/actions-testmodus).

| **Endpoint** | **Shop action** | **Error text configuration** |
| - | - | - |
| `testMode/activate` | [TestModeOn](/en/frontend/referenz/aktionen/testmode#testmodeon) | `actions.testModeOn` |
| `testMode/deactivate` | [TestModeOff](/en/frontend/referenz/aktionen/testmode#testmodeoff) | `actions.testModeOff` |
| `testMode/update` | [TestModeChange](/en/frontend/referenz/aktionen/testmode#testmodechange) | `actions.testModeChange` |

### Response on success

On success, all four endpoints respond with status 200 and the current state of test mode. The structure corresponds to the [\$wsTestMode](/en/frontend/referenz/module/wstestmode) module.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "debug": true,
  "makePaymentFail": false,
  "searchTestApi": true
}
```

| **Field** | **Type** | **Description** |
| - | - | - |
| `active` | bool | `true` if test mode is active for the session. |
| `debug` | bool | `true` if extended debugging is switched on. |
| `makePaymentFail` | bool | `true` if payments in test mode are deliberately simulated as failed. |
| `searchTestApi` | bool | `true` if the storefront should use the WEBSALE Search test API instead of the production API. |

### `searchTestApi` switch

The `searchTestApi` switch does not change the shop itself. It is merely a signal to your storefront. Based on its value, the storefront decides whether to address the test API or the production API of [WEBSALE Search](/en/schnittstellen/search-api).

<Note>
  The shop does not call WEBSALE Search itself. Instead, it only stores the switch in the session and passes it on in the response so that your storefront can react to it. You implement the switch to the test API in your storefront.
</Note>

### General responses

| **Status / code** | **Description** |
| - | - |
| Status 400 | No valid session was passed. For `testMode/activate` and `testMode/update`, also if the request contains no body or only an empty object `{}`. |
| Status 404 | The endpoint was called with an unsupported HTTP method. |
| `invalidParameters` | The request contains an unknown field or a field with the wrong data type. |

***

## Methods for test mode

### GET testMode/status

The following call returns the current state of test mode for the session.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
GET https://<ihr-shop>.de/api/v1/testMode/status
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description** |
| - | - |
| `x-session` | **Required field**<br />ID of the current session.<br />More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": false,
  "debug": false,
  "makePaymentFail": false,
  "searchTestApi": false
}
```

### POST testMode/activate

With the following call, you activate test mode for the session. Optionally, you can switch on extended debugging, the simulation of failed payments and the signal for the WEBSALE Search test API.

The call defines the initial state of test mode. Switches that you do not send are then off. If test mode is already active for the session, switches that are not sent keep their previous value.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<ihr-shop>.de/api/v1/testMode/activate
```

#### Example request

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "password": "test",
  "debug": true,
  "makePaymentFail": false,
  "searchTestApi": true
}
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description** |
| - | - |
| `x-session` | **Required field**<br />ID of the current session.<br />More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |

#### Body parameters

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `password` | string | **Required field**<br />Test mode password. It corresponds to the value of the `password` parameter under [general.testMode](/en/konfiguration/general-allgemeine-shopeinstellungen#general-testmode-test-mode). |
| `debug` | bool | Switches on extended debugging.<br />Default: `false` |
| `makePaymentFail` | bool | Simulates payments in test mode as failed.<br />Default: `false` |
| `searchTestApi` | bool | Signals to the storefront that it should use the WEBSALE Search test API instead of the production API. For more information, see [searchTestApi switch](#searchtestapi-switch).<br />Default: `false` |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "debug": true,
  "makePaymentFail": false,
  "searchTestApi": true
}
```

#### Error codes

| **Code** | **Description** |
| - | - |
| `noPassword` | No password was submitted. |
| `invalidPassword` | The submitted password is incorrect. |
| `tooManyAttempts` | Access to test mode is temporarily blocked for the caller's IP address due to too many failed password attempts. You define the limits and lockout duration under [general.testMode](/en/konfiguration/general-allgemeine-shopeinstellungen#general-testmode-test-mode). |

<Note>
  The lockout applies to the IP address, not to the session. A new session therefore does not lift it. During the lockout, the shop also rejects a correct password with `tooManyAttempts`.
</Note>

### POST testMode/deactivate

The following call deactivates test mode for the session. The shop resets the values `active`, `debug`, `makePaymentFail` and `searchTestApi` to `false`. A request body is not required.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<ihr-shop>.de/api/v1/testMode/deactivate
```

#### Parameter overview

#### Header parameters

| **Parameter** | **Description** |
| - | - |
| `x-session` | **Required field**<br />ID of the current session.<br />More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |

#### Example response

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": false,
  "debug": false,
  "makePaymentFail": false,
  "searchTestApi": false
}
```

### POST testMode/update

The following call changes the `debug`, `makePaymentFail` and `searchTestApi` switches without leaving test mode. The prerequisite is that test mode was previously activated with the password for the respective session.

The call only changes the switches that you send in the request. Switches that are not specified keep their previous value. All switches are therefore optional.

```text theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
POST https://<ihr-shop>.de/api/v1/testMode/update
```

#### Example request

This request switches `debug` off and leaves `makePaymentFail` and `searchTestApi` unchanged.

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

#### Parameter overview

#### Header parameters

| **Parameter** | **Description** |
| - | - |
| `x-session` | **Required field**<br />ID of the current session.<br />More information: [Storefront API Basics](/en/schnittstellen/storefront-api/storefront-api-basics) |

#### Body parameters

| **Parameter** | **Type** | **Description** |
| - | - | - |
| `debug` | bool | Switches extended debugging on (`true`) or off (`false`). Optional. |
| `makePaymentFail` | bool | Switches the simulation of failed payments on (`true`) or off (`false`). Optional. |
| `searchTestApi` | bool | Signals to the storefront that it should use the WEBSALE Search test API (`true`) or the production API (`false`). Optional. |

<Note>
  With `testMode/update`, only the switches you send are changed. To switch a switch off, explicitly send it with the value `false`. Omitting it means "do not change". This way, existing integrations continue to work unchanged even if further switches are added later.
</Note>

<Note>
  This does not apply to the form on the shop's test mode page. The [TestModeChange](/en/frontend/referenz/aktionen/testmode#testmodechange) action used there always sets all switches when saving. The reason is that the browser does not send an unchecked checkbox at all. A switch that is not checked in the form is therefore off after saving.
</Note>

#### Example response

The response shows the state after the example request. Only `debug` has changed.

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "active": true,
  "debug": false,
  "makePaymentFail": false,
  "searchTestApi": true
}
```

#### Error codes

| **Code** | **Description** |
| - | - |
| `notAllowed` | Test mode is not active for the session. Activate it first via [testMode/activate](#post-testmodeactivate). |

***

## Transition to the checkout

If you redirect from the storefront to a checkout of the template theme via [session/prepareRedirect](/en/schnittstellen/storefront-api/storefront-api-session-handling#post-sessionprepareredirect), test mode is retained because the shop takes over the session. The following applies to the rest of the process:

* Orders receive the verification status "Test". You can recognize them in the order overview in the admin interface and filter by the `verificationStatus` field via the [Admin Interface API](/en/schnittstellen/admin-interface-api/api-referenz-bestellungen#get-orders).
* If `makePaymentFail` is switched on, payments also fail in the checkout.

<Warning>
  The link from `session/prepareRedirect` is valid for **30 seconds**. If it is called later, the shop creates a new, empty session. Test mode is no longer active in this session, and orders are executed as regular orders.
</Warning>

***

## Related links

* [\$wsTestMode](/en/frontend/referenz/module/wstestmode): query the test mode state in the template.
* [TestMode actions](/en/frontend/referenz/aktionen/testmode): control test mode via forms in the template.
* [actions - Test mode](/en/konfiguration/actions-fehlertexte-e-mails/actions-testmodus): error texts of the test mode actions.
* [general.testMode](/en/konfiguration/general-allgemeine-shopeinstellungen#general-testmode-test-mode): password, template and lockout after failed password attempts.
* [Storefront API Session handling](/en/schnittstellen/storefront-api/storefront-api-session-handling): create a session and pass it to the template theme.
* [Search API](/en/schnittstellen/search-api): WEBSALE Search interface.


## Related topics

- [$wsTestMode - Test mode](/en/frontend/referenz/module/wstestmode.md)
- [Changelog](/en/changelog.md)
- [TestMode](/en/frontend/referenz/aktionen/testmode.md)
- [Storefront API Customer Account](/en/schnittstellen/storefront-api/storefront-api-kundenkonto.md)
- [actions - Test mode](/en/konfiguration/actions-fehlertexte-e-mails/actions-testmodus.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.