Versioning and updates

Every registered version of an app is immutable. To change anything an org installs (components, settings, roles) you register a new version and orgs upgrade to it. Only listing details can change in place.

Version numbers

version is a semantic version: MAJOR.MINOR.PATCH, with an optional pre-release tag such as 1.5.0-beta.

Choose the bump

Major versions are never applied automatically, so admins always get to review them. For marketplace apps, a major version also gets a full review, including privacy. See Publish to the marketplace.

Changelog

changelog maps versions to the release notes Kustomer shows admins on your app's page. Each entry starts with the release month in double braces, followed by Markdown:

{
  "changelog": {
    "1.5.0": "{{October 2026}} Added the **Refund order** workflow action.",
    "1.4.3": "{{September 2026}} Fixed the order timeline in dark mode.",
    "1.4.0": "{{August 2026}} Orders now sync on every update, not just on create."
  }
}

Keys are versions, optionally with -alpha or -beta. Add an entry for each version you register, and say what changed for admins and agents, not how you built it. Marketplace apps must include release notes.

changelog is app-wide, so you can fix a typo in an old entry without a new version; see Edit without a new version.

Beta versions

Register a pre-release version such as 1.5.0-beta to try a change in a sandbox org before it's final. Beta versions are never installed automatically: admins install them on purpose. When you're done, register the final version (1.5.0), which sorts after its betas.

Marketplace listings can't contain betas. Test with a private app instead.

Upgrade an installed app

An org upgrades by installing the newer version. Admins do this from the app's page; with the API, call the install endpoint with the target version:

{ "app": "acme_orders", "version": "1.5.0" }

Omit version to install the latest. Kustomer compares the two versions and changes only what differs:

Klasses stay because deleting one would delete every record of that type. Their KObjects stay with them.

Installs run in the background. Check progress with:

attributes.status is installing, installed or install_failed, and attributes.previousVersion is the version you upgraded from. If an upgrade fails, the org keeps the previous version and you can retry.

Automatic updates

Admins can let an installed app update itself when you register a new version. The flag is per org, on the installed app:

{ "autoUpdate": true }

A new version is skipped, and left for the admin to install, when:

• It's a major version.
• It's a pre-release, such as 1.5.0-beta.
• The app is disabled in the org.
• An install is already in progress.
• An app it depends on isn't installed, or the installed version isn't one it supports.

Treat automatic updates as a convenience for orgs, not a delivery guarantee: always assume some orgs are on older versions, and keep your hooks and APIs compatible with every version you still support.

Edit without a new version

Listing details that don't install anything can change in place. Two endpoints cover them:

curl -X PATCH "https://acme.api.kustomerapp.com/v1/apps/available/acme_orders_${ORG_ID}-1.5.0" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"description": "Sync Acme orders and issue refunds from Kustomer."}'

curl -X PUT "https://acme.api.kustomerapp.com/v1/apps/available/acme_orders_${ORG_ID}-1.5.0" \
  -H "Authorization: Bearer $KUSTOMER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"changelog": {"1.5.0": "{{October 2026}} Added the **Refund order** workflow action."}}'

Use these to rotate a third-party OAuth client secret in auth, or to add a redirect URI, without making every org upgrade.

Version history at a glance

gitGraph
  commit id: "1.0.0"
  commit id: "1.1.0 new KView"
  branch beta
  commit id: "1.2.0-beta"
  checkout main
  merge beta id: "1.2.0"
  commit id: "1.2.1 fix"
  commit id: "2.0.0 new roles" type: HIGHLIGHT

Orgs on automatic updates move from 1.0.0 to 1.2.1 without anyone acting. They stop at 2.0.0 until an admin approves the new roles.