Versioning

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

JTL uses versioning across two 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.

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

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:

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

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

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.

Manifest Versioning

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

{
  "version": "2.3.1",
  ...
}

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.

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.

App Manifest Reference

Full app.json schema documentation.