Chargebee Apps CLI Developer Guide

Chargebee Apps CLI is in early access. Request access for enabling it on your test site.

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, contact support 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.

Note

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

Note

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

Note

To publish your app privately to your Chargebee site, contact support with your packaged ZIP file.

Chargebee Apps CLI Developer Guide

Chargebee Apps CLI is in early access. Request access for enabling it on your test site.

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

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

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

Note

Define installation parameters (iParams)

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

Note

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

Note

To publish your app privately to your Chargebee site, contact support with your packaged ZIP file.

Product Updates

Getting Started

Implementing Chargebee

Agentic AI

Developer Resources

Chargebee Apps

Product Catalog

Subscriptions

Customers

Entitlements

Usage Based Billing

Invoices and Credit Notes

Taxes

Hosted Capabilities

Site Configuration

Multi Business Entity

Mobile Subscriptions

Reports and Analytics

Integrations

Data Privacy & Security

Data Operations

Chargebee Apps CLI Developer Guide

Prerequisites

Install and verify the CLI

Create a new application

Standard template

iParams template

Understand the app structure

manifest.json — App configuration

handler/handler.js — Application logic

.env — Environment variables

Define installation parameters (iParams)

Schema structure

Supported parameter types

Example: CRM schema with URL and SECRET

Provide local test inputs

Run and test locally

Use the local web UI

Package your application

Publish your app

Product Updates

Getting Started

Implementing Chargebee

Agentic AI

Developer Resources

Chargebee Apps

Product Catalog

Subscriptions

Customers

Entitlements

Usage Based Billing

Invoices and Credit Notes

Taxes

Hosted Capabilities

Site Configuration

Multi Business Entity

Mobile Subscriptions

Reports and Analytics

Integrations

Data Privacy & Security

Data Operations

Chargebee Apps CLI Developer Guide

Prerequisites

Install and verify the CLI

Create a new application

Standard template

iParams template

Understand the app structure

manifest.json — App configuration

handler/handler.js — Application logic

.env — Environment variables

Define installation parameters (iParams)

Schema structure

Supported parameter types

Example: CRM schema with URL and SECRET

Provide local test inputs

Run and test locally

Use the local web UI

Package your application

Publish your app