@chargebee/chargebee-apps

Chargebee Apps CLI Developer Guide

The Chargebee Apps CLI is a command-line tool for building private serverless applications that extend Chargebee Billing. Use it to scaffold a new app, implement and test event handlers locally, and package the app into a ZIP file. When your app is ready, upload it to the Apps portal in Chargebee Billing to publish it privately to your site.

In Chargebee, a serverless application (also called an app) is a set of Node.js event handlers that run in Chargebee's hosted environment in response to Chargebee events. You write only the handler logic; Chargebee runs it automatically when a matching event occurs, so there is no server or infrastructure for you to provision, scale, or maintain.

With the Apps CLI, you can:

• Generate a ready-to-run app template.
• Implement and test event handlers locally.
• Trigger events interactively through a built-in web testing UI.
• Package your app into a deployable artifact.

Prerequisites

• Node.js 22 is required.

Install and verify the CLI

Install the CLI globally:

npm install -g @chargebee/chargebee-apps

Verify the installation by confirming that the version and help commands run successfully:

chargebee-apps --version
chargebee-apps --help

If both commands display the version and the list of chargebee-apps commands, your setup is complete.

Create a new application

Scaffold a new project with the create command. Choose the template that matches your app's requirements.

Standard template

Use the default template, serverless-node-starter-app, if your app performs pure event processing without user-configurable settings.

# Create in the current directory
chargebee-apps create <app_name>

# Create within a specific subdirectory path
chargebee-apps create <subdirectory_path>/<app_name>

iParams template

Use the iParams template if your app needs installation parameters (iParams) — user-configurable settings such as API keys, URLs, fee rules, or feature flags that users supply when they install the app.

chargebee-apps create <app_name> --template serverless-node-starter-app-with-iparams

Understand the app structure

The files in your project depend on the template you chose. Files marked as packaged are included in the deployable artifact; the rest are used only for local development.

File or folder	Standard template	iParams template	Packaged	Purpose
manifest.json	Yes	Yes	Yes	Maps Chargebee events to handler functions and declares npm dependencies.
handler/handler.js	Yes	Yes	Yes	Contains your core event-handling logic.
iparams.json	No	Yes	Yes	iParams template only. Defines the installation parameter schema.
iparams.local.json	No	Yes	No	iParams template only. Stores local test values, keyed by section name.
test_data/	Yes	Yes	No	Mock JSON event payloads used only for local testing.
.env	Yes	Yes	No	Local system environment variables.
logs/cb.log	Yes	Yes	No	Local development log file.

manifest.json — App configuration

The manifest.json file defines your app's metadata, maps event subscriptions to their handler functions, and declares required third-party package dependencies.

{
  "name": "your_app_name",
  "description": "A clear description of what your serverless app does",
  "events": {
    "customer_created": {
      "handler": "customerCreateHandler"
    },
    "invoice_generated": {
      "handler": "invoiceGeneratedHandler"
    }
  },
  "dependencies": {
    "chargebee": "3.14.0"
  }
}

• Event names: Each key under events must exactly match a valid Chargebee webhook event type.
• Handler names: Each handler value must match a function exported from handler/handler.js.
• Dependencies: Only chargebee and axios are currently supported. For any additional npm packages, contact the Chargebee support team.

handler/handler.js — Application logic

Write your event-handling logic in handler/handler.js. Each handler receives a single payload argument. Use payload.event to access the event data. If you use the iParams template, access installation parameters through payload.iparams.<section_name>.<param_name>.

module.exports = {
  customerCreateHandler: function (payload) {
    console.log("Processing customer_created event");
    console.log("Customer created for email:", payload.event.content.customer.email);

    // iParams template only: read configuration if present
    if (payload.iparams && payload.iparams.processing_fee_configuration) {
      const fees = payload.iparams.processing_fee_configuration;
      console.log("Processing fee (%):", fees.fee_percentage);
      console.log("Processing fee limit:", fees.fee_limit);
    }
  },

  invoiceGeneratedHandler: function (payload) {
    console.log("Processing invoice_generated event");
    console.log("Invoice status:", payload.event.content.invoice.status);

    // iParams template only: read configuration if present
    if (payload.iparams && payload.iparams.late_payment_fee_configuration) {
      const lateFees = payload.iparams.late_payment_fee_configuration;
      console.log("Late payment fee (%):", lateFees.fee_percentage);
    }
  }
};

.env — Environment variables

Define your Chargebee API keys and site domain in a .env file. The CLI supports only these three variables:

MKPLC_CB_READ_ONLY_API=your_read_only_api_key_here
MKPLC_CB_READ_WRITE_API=your_read_write_api_key_here
MKPLC_SITE_DOMAIN=your_site_domain_here

Access these values in your handler code through process.env, for example process.env.MKPLC_CB_READ_ONLY_API. The .env file is used for local development only and is not included when you package your app. In the hosted environment, Chargebee injects these variables automatically.

These environment variables are different from installation parameters (iParams). Environment variables are standard system values that Chargebee injects automatically and require no user action. iParams are user-defined settings that an installer provides when they install or update the app.

Define installation parameters (iParams)

This section applies only to apps built with the iParams template. Installation parameters let users configure your app when they install it — for example, API keys, endpoints, fee rules, or feature flags. An empty object ({}) in iparams.json means no installation parameters are defined.

Schema structure

Parameters are grouped into named sections in iparams.json. A maximum of 20 parameters is allowed in total across all sections.

Each section supports the following properties:

• name (required): Unique section identifier. Maximum 50 characters.
• display_name (required): Human-readable section title shown in the UI. Maximum 50 characters.
• description (required): Explains what the section configures. Maximum 250 characters.
• parameters (required): A non-empty array of parameter definitions.

Each parameter supports the following attributes:

• name (required): Unique parameter key within the section. Maximum 50 characters.
• display_name (required): Human-readable input label. Maximum 50 characters.
• description (required): Explains what the parameter is used for. Maximum 250 characters.
• type (required): One of the supported types listed below.
• required (optional): Defaults to false.
• default (optional): Default fallback value. Not allowed for the SECRET type.
• options (conditional): Required only for DROPDOWN and MULTISELECT_DROPDOWN.

Supported parameter types

Type	Input or use case
TEXT	String (maximum 250 characters) for names, labels, and non-sensitive keys.
SECRET	String (maximum 250 characters) for passwords and API tokens. Encrypted at rest. Never log these values.
URL	Enforces valid http:// or https:// webhook and API endpoints.
NUMBER	Integer or decimal values for percentages, limits, and counts.
BOOLEAN	true or false toggles for feature flags.
DROPDOWN	Single selection from the choices in the options array.
MULTISELECT_DROPDOWN	Multiple selections from the choices in the options array.
DATE	Enforces YYYY-MM-DD formatting for expiry or start dates.

Example: CRM schema with URL and SECRET

The following iparams.json defines a section with a URL endpoint and a secret token:

{
  "installation_parameters": {
    "sections": [
      {
        "name": "crm_integration",
        "display_name": "CRM Integration",
        "description": "HubSpot contacts API credentials and endpoint.",
        "parameters": [
          {
            "name": "crm_webhook_url",
            "display_name": "HubSpot contacts API URL",
            "description": "Example: https://api.hubapi.com/crm/v3/objects/contacts",
            "type": "URL",
            "required": true
          },
          {
            "name": "crm_auth_token",
            "display_name": "HubSpot private app token",
            "description": "Sent as Authorization: Bearer <token>.",
            "type": "SECRET",
            "required": true
          }
        ]
      }
    ]
  }
}

Provide local test inputs

To test your parametrized handlers locally, supply mock values in iparams.local.json, keyed by section name:

{
  "crm_integration": {
    "crm_webhook_url": "https://api.hubapi.com/crm/v3/objects/contacts",
    "crm_auth_token": "pat-your-test-token"
  }
}

`iparams.local.json` is never packaged. In production, users provide these values when they install or update the app.

Run and test locally

Start the local development server:

chargebee-apps run <app_directory>

To run the server on a custom port, add the --port option:

chargebee-apps run <app_directory> --port 16000

Then open the local development UI in your browser:

• Default URL: http://localhost:15000 (or your custom port).

If you use the iParams template, the CLI validates your iparams.json schema on startup. Fix any schema errors before you execute handlers.

Use the local web UI

• Event testing: Select an event type from the dropdown, for example customer_created. Review or edit the mock JSON payload loaded from test_data/, then click Execute Handler.
• iParams tab (iParams template only): Edit your parameter schema fields interactively. Saving writes directly to iparams.json.
• iParams inputs tab (iParams template only): Provide test values through a form or a raw JSON editor. Saving writes directly to iparams.local.json.
• Logs: Console output appears in the terminal running the server and is appended to logs/cb.log.

Package your application

After testing, bundle your application directory into a production-ready ZIP file:

chargebee-apps package <app_directory>

To set a custom version name, use the --name option:

chargebee-apps package <app_directory> --name my-app-v1.0.0

The package includes manifest.json, the handler/ folder, and iparams.json (iParams template only). It excludes test_data/, iparams.local.json, .env, logs/, and node_modules/.

The command compiles the deployable artifact into the dist/ folder:

my-first-app/
└── dist/
    └── app.zip

Publish your app

After you package your app, upload the ZIP file to the Apps portal in Chargebee Billing.

• In Chargebee Billing, go to Apps to open the Apps portal.
• Click Create App.
• On the Upload Package step, upload your app's .zip file. Click the upload area to browse, or drag and drop the file.
• On the Review Details step, review your app's details.
• Submit the app. Its status changes to Under Review.
• When the review is complete, the Result step shows the outcome.

After your app is published, it appears in the Apps portal list, where you can track each app's type (private or public) and status, and manage updates.