Skip to main content
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 app.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

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 for the full list of removed paths.

​
JTL Cloud: URL-path Versioning

The JTL Cloud API embeds the version in the URL path:
The version segment determines which API version handles the request. Check the 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:
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.

​
SCX (Marketplace): URL-path Versioning

SCX APIs also use URL-path versioning:
The version prefix (/v1/) is part of the endpoint URL. Currently only v1 is available.

​
Manifest Versioning

Your app’s app.json contains a version field:

​
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
Follow semantic versioning conventions: increment major for breaking changes, minor for new features, and patch for bug fixes.

​
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:

​
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.x in the header. Start new projects on v2.x. Building on deprecated v1.x versions creates unnecessary migration work. Use v2.x for both Cloud and OnPremise, and set the latest version in your app manifest. Monitor the changelog. JTL publishes an API 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

API Reference

Explore available endpoints across API versions.

Error Handling

Handle version-related errors and deprecation responses.

Rate Limiting

Understand request limits that apply across all API versions.

App Manifest Reference

Full app.json schema documentation.