> ## Documentation Index
> Fetch the complete documentation index at: https://developer.jtl-software.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Versioning

> Understand how JTL versions its APIs, manifests, and platform components, and how to keep your integration stable across updates.

JTL uses versioning across three layers of the platform:

1. **API versioning**: Controls which version of the JTL Cloud and JTL-Wawi API your requests target.
2. **Manifest versioning**: Declares the schema version and app version in your `manifest.json`.
3. **Client compatibility**: Lets SCX marketplace channels enforce minimum JTL-Wawi versions for new seller connections.

Understanding each layer helps you ship stable integrations, adopt new features safely, and avoid breaking changes when JTL updates the platform.

## API Versioning

JTL uses different versioning strategies depending on the API surface. Both the JTL Cloud and JTL-Wawi APIs share the same version catalogue, but they pass the version differently.

### Available Versions

| Version | Notes                                                       |
| ------- | ----------------------------------------------------------- |
| `1.0`   | Original release                                            |
| `1.1`   | Incremental additions                                       |
| `1.2`   | Extended endpoints for items, customers, and orders         |
| `1.3`   | Last minor release before v2.0                              |
| `2.0`   | Major revision, many v1.x endpoints removed or restructured |

<Warning>
  **v1.x → v2.0 is a breaking change.** Dozens of endpoints from v1.x were removed in v2.0. If you're building a new integration, **always use v2.0**. If you're migrating from v1.x, review the [API Changelog](/help/changelog) for the full list of removed paths.
</Warning>

### JTL Cloud: URL-path Versioning

The JTL Cloud API embeds the version in the URL path:

```bash theme={null}
# JTL Cloud: version is in the path (/erp/v2/)
curl -X GET "https://api.jtl-cloud.com/erp/v2/info" \
  -H "Authorization: Bearer <JWT>" \
  -H "X-Tenant-ID: <tenantId>"
```

The version segment determines which API version handles the request. Check the [API Reference](/api-reference) to see available versions and choose the appropriate one for your integration.

### JTL-Wawi (OnPremise): Header-based Versioning

The JTL-Wawi API uses the `api-version` request header instead:

```bash theme={null}
# JTL-Wawi: version is in the header
curl -i -X GET "http://127.0.0.1:<port>/api/eazybusiness/info" \
  -H "Authorization: Wawi <API-Key>" \
  -H "api-version: 2.0" \
  -H "x-appid: MyApp/1.0.0" \
  -H "x-appversion: 1.0.0" \
  -H "x-challengecode: MyChallengeCode"
```

<Note>
  The `api-version` header is required on every OnPremise request. If omitted, the API may default to the earliest supported version. Always set it to `2.0` explicitly.
</Note>

### SCX (Marketplace): URL-path Versioning

SCX APIs also use URL-path versioning:

```
GET https://scx-sbx.api.jtl-software.com/v1/channel/order
```

The version prefix (`/v1/`) is part of the endpoint URL. Currently only `v1` is available.

## Manifest Versioning

Your app's `manifest.json` contains two version fields:

```json theme={null}
{
  "manifestVersion": "1.0.0",
  "version": "2.3.1",
  ...
}
```

### `manifestVersion`

Declares which version of the manifest **schema** your file conforms to. JTL uses this to parse and validate your manifest correctly.

* Format: `major.minor.patch` (semantic versioning)
* Set this to the latest supported schema version when creating your manifest
* Changing `manifestVersion` may be required when JTL introduces new manifest capabilities (new fields, changed validation rules)

### `version`

Your **app's own version** to track releases of your application.

* Format: `major.minor.patch` (semantic versioning)
* Update this when you ship changes to your app
* Displayed to merchants in the Extension Store

<Tip>
  Follow [semantic versioning](https://semver.org) conventions: increment `major` for breaking changes, `minor` for new features, and `patch` for bug fixes.
</Tip>

## Client Compatibility (SCX Channels)

If you're building an SCX marketplace channel, the `minClientsVersionRequired` property lets you enforce a minimum JTL-Wawi version for new seller signups.

### How it Works

When a seller connects to your channel, SCX compares the seller's Wawi version (from their `User-Agent` header) against your defined minimum. If their version is too low, onboarding fails with error code `SLR202`. Existing connected sellers are **not** affected and their connection continues even if their Wawi version is below the minimum.

### Configuration

Set the minimum version via `PATCH /v1/channel`:

```json theme={null}
{
  "minClientsVersionRequired": [
    {
      "type": "Wawi",
      "version": "1.11.0.0"
    }
  ]
}
```

| Field     | Type   | Description                                                             |
| --------- | ------ | ----------------------------------------------------------------------- |
| `type`    | string | Client type. Currently only `Wawi` is supported.                        |
| `version` | string | Minimum version in `major.minor.patch.build` format (e.g., `1.11.0.0`). |

### When to Use This

* **Gradual rollouts**: Require a minimum client version for new signups when your channel depends on features from a specific Wawi release.
* **Controlled upgrades**: Encourage merchants to update Wawi before connecting to your channel.
* **Legacy protection**: Prevent issues from outdated clients without disrupting merchants already connected.

## Best Practices

**Pin your API version explicitly.** For JTL Cloud, always use the `/erp/v2/` path prefix. For JTL-Wawi, always send `api-version: 2.0` in the header.

**Start new projects on v2.0.** Building on deprecated v1.x versions creates unnecessary migration work. Use v2.0 for both Cloud and OnPremise, and set the latest `manifestVersion` in your manifest.

**Monitor the changelog.** JTL publishes an [API Changelog](/help/changelog) documenting removed, added, and changed endpoints between versions. Subscribe to updates or check before each release cycle.

**Version your own app meaningfully.** Use the `version` field in your manifest to communicate changes to merchants. Consistent version bumps build trust in the App Store.

***

## What's next

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore available endpoints across API versions.
  </Card>

  <Card title="Error Handling" icon="triangle-alert" href="/guides/essentials/common-patterns/error-handling">
    Handle version-related errors and deprecation responses.
  </Card>

  <Card title="Rate Limiting" icon="gauge" href="/guides/essentials/common-patterns/rate-limiting">
    Understand request limits that apply across all API versions.
  </Card>

  <Card title="App Manifest Reference" icon="file-code-2" href="/guides/cloud-apps/app-shell-ui-integration#app-manifest">
    Full manifest.json schema documentation.
  </Card>
</CardGroup>