Share a Private App

A private app isn’t listed in the App Store. You share it with selected merchants using activation codes. This suits an app that isn’t ready for general release, or one built for a few specific customers.

Before You Start

Your app needs to be registered, provisioned, and tested, and you need to Become a Seller to list it. Deploy your app to a public URL with HTTPS and update its URLs to production in the app manifest before you submit.

Activation Codes

Merchants install a private app with an activation code you generate in JTL Hub. Each code is single-use: one code activates the app for one merchant. As a seller, you can generate as many codes as you need. Without a listing, you’re limited to three.

The Listing Manifest

You define your listing in a manifest. Set distributionType to PRIVATE to keep it out of the App Store.

{
  "version": "1.0.0",
  "defaultLocale": "de-DE",
  "distributionType": "PRIVATE",
  "name": {
    "de-DE": {
      "short": "My App",
      "full": "My JTL Cloud App"
    }
  },
  "description": {
    "de-DE": {
      "short": "A short teaser.",
      "full": "The full description of the app."
    }
  },
  "benefits": {
    "de-DE": [
      "Benefit 1",
      "Benefit 2",
      "Benefit 3"
    ]
  },
  "category": {
    "main": "articles-product-data",
    "sub": ["item-master-data-attributes"]
  },
  "media": {
    "icons": {
      "light": "https://example.com/icon-light.png",
      "dark": "https://example.com/icon-dark.png"
    },
    "screenshots": [
      {
        "id": "screenshot-1",
        "url": "https://example.com/screenshot-1.png",
        "alt": "The app's dashboard"
      }
    ]
  },
  "compatibility": {
    "products": {
      "de-DE": ["jtl-wawi"]
    },
    "productsNotes": "",
    "minVersions": {
      "jtl-wawi": "1.1.0"
    }
  },
  "support": {
    "url": {
      "de-DE": "https://example.com/support"
    },
    "documentation": {
      "de-DE": "https://example.com/docs"
    }
  },
  "legal": {
    "privacyPolicy": "https://example.com/privacy",
    "termsOfUse": "https://example.com/terms",
    "gdpr": {
      "request": "https://example.com/gdpr/request",
      "delete": "https://example.com/gdpr/delete"
    }
  }
}

Private listings don’t go through App Store review.

You can configure your pricing tiers now, but merchant billing through them is not yet available. Defining your tiers now ensures your listing is ready when billing becomes available.

Before you submit, replace any development placeholders with production content:

Icons and screenshots: Replace placeholder URLs with your production assets hosted at stable, publicly accessible URLs. Provide both light and dark icon variants.
Names and descriptions: Finalize the copy for every locale you support (name.{locale}.short, name.{locale}.full, description.{locale}.short, description.{locale}.full).
Benefits: Provide three to five localized benefits describing the value your app offers merchants.
Compatibility: List the supported JTL products and specify a valid minVersions entry for each.
Support URLs: Set support.url.{locale} and support.documentation.{locale} to publicly accessible support and documentation pages.
Legal URLs: Ensure legal.privacyPolicy, legal.termsOfUse, legal.gdpr.request, and legal.gdpr.delete all point to published pages. These are required for JTL compliance.

Names, descriptions, benefits, supported products, and support URLs are localized by locale, allowing a single manifest to support multiple markets. See the Listing Manifest Reference for more details.

Create the Listing

Create your listing as a draft. All three paths produce the same listing.

CLI
Listing Wizard

If you’re using one of the JTL Cloud App starter templates, update the listing.json file in your project root, then create the listing draft:

npm run listing

If you’re building your app from scratch:

Create a listing.json file in your project root
Generate the listing draft:

npx -y @jtl-software/create-cloud-app@latest listing

The CLI reads your listing.json and creates a listing in the DRAFT state in the Partner Portal.Once the listing is created, use the returned URL to open the listing in the Partner Portal to review and submit it.

Submit your Listing

Submit your listing when it’s complete. Because private apps skip App Store review, your listing is ready to share once submitted. Generate an activation code for your app in Partner Portal under Manage apps. Send the code to your customer directly, for example by email, along with instructions for redeeming it. A private app you build under your own tenant isn’t visible in another merchant’s tenant, so the code is what gives them access to install it.

Open the Partner Portal

Go to Partner Portal and open Manage apps. In the app list, click the three-dot menu for your app and select Activation codes.

Generate a code for your app

Generate an activation code by clicking on the Create activation code button.A dialog will show where you can manually input your custom activation code or auto-generate one by clicking the dice icon. The code is a plain-text string tied to your private app.

Activation code dialog for a private app

How a Merchant Redeems a Code

Include these steps when you send the code:

Open Manage apps menu in JTL Hub

In JTL Hub, open Manage apps.

Start activation

At the bottom of the page, click the Activate now button. A dialog opens.

Enter the code

Enter the activation code you received from your partner and follow the prompts to install the app.

Once the merchant redeems the code, the app installs in their tenant and runs through the same setup flow as any other app.

What’s Next?

Publish to the App Store

Ready for a wider audience? Publish your app for all merchants to find and install.

App Shell & UI

Add panel views, custom tabs, and deeper ERP integration to your app.

Get Started

Before You Start

Activation Codes

The Listing Manifest

Create the Listing

1. Generally

2. Media

3. Compatibility

4. Prices

5. Legal

Submit your Listing

How a Merchant Redeems a Code

What’s Next?

Publish to the App Store

App Shell & UI

​Before You Start

​Activation Codes

​The Listing Manifest

​Create the Listing

​1. Generally

​2. Media

​3. Compatibility

​4. Prices

​5. Legal

​Submit your Listing

​Generate and Share Activation Code

​How a Merchant Redeems a Code

​What’s Next?

Publish to the App Store

App Shell & UI

Before You Start

Activation Codes

The Listing Manifest

Create the Listing

1. Generally

2. Media

3. Compatibility

4. Prices

5. Legal

Submit your Listing

Generate and Share Activation Code

How a Merchant Redeems a Code

What’s Next?