Stay current with API, SDK and CLI versions

This guide is for the developer or tech lead who owns an integration, a storefront or an App and does not want to find out about a change from a failing deploy. By the end you have a named owner for the Changelog, exact pins for the SDK and CLI (including in CI), a weekly check that tells you when your tenant's API surface changed, and an upgrade order that puts a change on dev and staging before production.

The pages that describe the promises are Versioning & stability (the API) and SDK versioning & stability (the packages). They say what you can rely on. This page turns them into a routine.

The short answer: one person reads the Changelog, the SDKs and the CLI you install are pinned exactly, a weekly job diffs your tenant's OpenAPI document, and every upgrade goes dev, then staging, then production.

1. Name an owner and subscribe

Deprecations and breaking changes are announced on the Changelog before they take effect, and with at least four weeks between the announcement and a removal of an API endpoint. That is the published policy, stated in Versioning & stability. For anything contractual, check your agreement. The packages and the CLI are announced there too, but with no stated window. Nothing on the response marks an endpoint as deprecated, so a notice only helps if someone reads it.

Write one name next to the Changelog in your team's runbook, with a backup. That person reads new entries at least once every two weeks, which keeps you well inside the four-week window.

There are two ways to follow it (as of 2026-10):

Point the feed at a channel the owner already reads, such as a team chat channel with an RSS integration.

2. Pin what you install, exactly

A lockfile alone is not a pin: npm update or composer update moves it, and so does a ^ range in the manifest that allows a newer version. Pin the exact version in the manifest, and install from the lockfile in CI.

The generated API clients are all at 0.x. Each release is compared with the previous one for changes that could stop your code compiling, and such a change ships as a minor version, never as a patch, so a minor can break you. The check reads shape, not behaviour (see SDK versioning & stability). That check does not cover the CLI, so a command, flag or output shape can move in a CLI patch. Treat both the same way:

# Saves the exact version, not a ^range. Do the same for @revenexx/node
npm install --save-exact @revenexx/sdk

# CI: install from the lockfile and fail if it disagrees with package.json
npm ci

# Writes the exact version into composer.json, then CI installs from composer.lock
composer require revenexx/sdk:<exact version>
composer install

Pin the CLI in the same way wherever it runs, including CI. Ask the machine you tested on for the version, then write that into the workflow:

revenexx --version

- name: Install the CLI
  run: npm install -g @revenexx/cli@<exact version>

Do not use @latest in a pipeline. revenexx --version prints the installed version and says whether a newer one exists, which is how you notice that the pin is old. Take a package's version from the Changelog entry for the release you tested, or from the package registry.

@revenexx/sdk is the client for JavaScript in the browser and @revenexx/node the one for server-side Node, so pin the one you import. The @revenexx/node client and the two platform SDKs (App SDK and Integration Node SDK) are numbered on their own. Pin each one separately the same way, using the package name on its page, and do not read one package being ahead of another as news about either.

3. Check your tenant's API surface every week

The endpoints you can call depend on the Apps installed in your tenant, so the document that is true for you is your tenant's own OpenAPI document. Keep a copy in the repository, and let a scheduled job tell you when the live one stops matching it. A weekly run fits well inside a four-week notice. Use an API key of that tenant and keep it as a CI secret. Which scope the key needs to read the document is unconfirmed (as of 2026-10), so start with the narrowest key you have and widen it only if the call is refused.

set -euo pipefail

curl -fsS https://api.revenexx.com/v1/openapi.json \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  | jq -S . > openapi.live.json

# jq -S sorts keys, so only real changes show up in the diff
diff -u openapi.snapshot.json openapi.live.json

curl -f makes an HTTP error (a 401, a 403 or a 5xx) fail the script before anything is written to the diff, and set -e stops it there. A failure with curl's own message is a network or key problem, not a change to the API. A diff printed by diff is the change.

Create the first snapshot once, before the first run. It is the same call, saved as the baseline:

curl -fsS https://api.revenexx.com/v1/openapi.json \
  -H "X-Revenexx-Tenant: $REVENEXX_TENANT" \
  -H "X-Revenexx-Api-Key: $REVENEXX_API_KEY" \
  | jq -S . > openapi.snapshot.json

Commit openapi.snapshot.json and check-openapi.sh at the repository root.

The script exits non-zero when the two differ. Run it from a scheduled job, for example every Monday, so that a failed run reaches the team the way any failed pipeline does, and treat a difference as a prompt to read, not as a failure to fix:

on:
  schedule:
    - cron: "0 7 * * 1"
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Diff the tenant's OpenAPI document
        env:
          REVENEXX_TENANT: acme
          REVENEXX_API_KEY: ${{ secrets.REVENEXX_API_KEY }}
        run: bash check-openapi.sh

• Something was added. This is the normal case under /v1, where changes are additive: new endpoints and optional fields. Copy openapi.live.json over openapi.snapshot.json and commit it.
• Something was removed, renamed or retyped. That is a breaking change. Look it up in the Changelog. If it was announced, you are inside the notice period. If it was not announced and you cannot find it, send the diff to support.
• An App was installed or removed in your tenant. That also changes the document, and it is yours to confirm.

Read the first snapshot once against what you build on. From then on the check reports change since that point, not before it. Run it against staging as well as production if their installed Apps differ.

If you want typed calls, feed the same document to an OpenAPI generator of your choice and regenerate the types when the snapshot changes, at least once a month. The CLI's types and generate commands work from a local project file and do not read your tenant's document, see Type generation.

4. Upgrade on dev, then staging, then production

Upgrade one thing at a time, so that a failure has one cause:

1. Read the release notes for the package you are about to move, from the Changelog entry. For the CLI, this is the only place that says a flag moved.
2. Bump on dev with your compiler on. A typed client turns a removed field into a build error instead of a runtime one. Run your tests and the scripts that use the CLI.
3. Promote to staging and run the flows a test cannot cover: a checkout, an order handover, a deploy of an App.
4. Promote to production only after staging has run the new version through a normal working day.
5. Commit the new pin and, if the API document changed, the new snapshot in the same pull request, so a revert takes both back. A snapshot update that belongs to no upgrade gets its own pull request.

Move the API client, the CLI and the App SDK in separate pull requests, each with its own pin. A combined bump is quicker to write and slower to debug.

5. If you publish an App, diff your own contract before you bump

The same discipline applies to the contract you publish. An App's version only moves forward and is bumped on every successful build, and a breaking change means a new major version, a new capability key and a new route, never a change in place. Before you bump, compare the routes, request fields and events your App exposes now with the ones in the version you are about to ship, using the same snapshot-and-diff approach as above on your own document. Anything another App or a merchant could notice is a break. The rules, and what merchants see, are in App versioning.

Checklist

• A named owner, and a backup, for the Changelog, with the feed or digest wired to somewhere they read.
• Every revenexx package and the CLI pinned to an exact version, in the manifest and in CI.
• openapi.snapshot.json committed, and a weekly job that diffs it against the live document.
• An upgrade order written down: dev, staging, then production, one package per pull request, with the snapshot in the pull request it belongs to.
• For an App you publish: a diff of your own contract before every bump.

Where to go next

• Versioning & stability — what counts as a break and how long you get.
• SDK versioning & stability — what a package version promises.
• Go live with a project — the one-time list this routine continues after launch.