JavaScript / TypeScript SDK

Official TypeScript SDK for the GrowPanel REST API. Works in Node.js, Bun, Deno, Cloudflare Workers, and modern browsers. Published as @growpanel/sdk on npm. Source: growpanel/growpanel-sdk-js.

Installation

npm install @growpanel/sdk

Requires Node.js 20+ (or any runtime with fetch and ES modules). TypeScript types ship with the package — no @types/... needed.

Authentication

Get an API key from app.growpanel.io → Account → API keys, then pass it when constructing the client. See Authentication for key scoping and rotation.

import { GrowPanel } from '@growpanel/sdk';

const gp = new GrowPanel({
    apiKey: process.env.GROWPANEL_API_KEY!
});

You can also override the base URL (useful for testing against api-dev.growpanel.io or a self-hosted proxy):

const gp = new GrowPanel({
    apiKey: process.env.GROWPANEL_API_KEY!,
    baseUrl: 'https://api-dev.growpanel.io'
});

Quick start

// Top-level KPIs
const summary = await gp.reports.getSummary();
console.log(summary.data.summary.mrr_current);

// MRR time series for a specific window
const mrr = await gp.reports.getMrr({
    query: { date: '20260101-20260531', interval: 'month' }
});
for (const period of mrr.data.result) {
    console.log(period.date, period.total_mrr);
}

// List customers
const customers = await gp.customers.list({ query: { limit: '50' } });
for (const c of customers.data.result.list) {
    console.log(c.name, c.current_mrr_base_currency);
}

Surfaces

Analytics:

gp.reports.getSummary()
gp.reports.getMrr({ query: { date, interval, breakdown } })
gp.reports.getCohort({ query: { date, interval } })
gp.reports.getRetention({ query: { date, interval } })
gp.reports.getCashflowFailedPayments({ query: { date } })
// ... 22 report endpoints in total

gp.customers.list({ query: { limit, search } })
gp.customers.detail({ path: { id } })
gp.plans.list()

Account & integrations:

gp.profile.get()
gp.profile.update({ body: { first_name, timezone } })
gp.notifications.get()
gp.notifications.update({ body: { daily_report: true } })
gp.webhooks.list()
gp.webhooks.create({ body: { url, event_type } })
gp.webhooks.delete({ path: { id } })

Ingestion (nested data.* namespace):

gp.data.customers.create({ body: { id, name, email, created_date, country, data_source } })
gp.data.customers.update({ path: { id }, body: { name } })
gp.data.customers.delete({ path: { id } })

gp.data.plans.create({ body: { id, name, billing_freq, currency, data_source } })
gp.data.invoices.create({ body: { id, customer_id, date, amount, currency, data_source } })

gp.data.planGroups.create({ body: { name, plans: ['price_a', 'price_b'] } })
gp.data.segments.create({ body: { name, filters: { region: 'eu' } } })

gp.data.sources.list()
gp.data.sources.fullImport({ path: { id } })
gp.data.sources.getProgress({ path: { id } })

Bulk-friendly endpoints (data.customers.create, data.invoices.create, data.plans.create) accept either a single object or an array — the response is always an array of per-row import results.

For anything not in a named namespace, gp.raw.<operationId>(...) exposes every generated operation by its OpenAPI ID.

Errors

Every method throws GrowPanelError on non-2xx responses. Inspect err.status, err.statusText, and err.body for context.

import { GrowPanel, GrowPanelError } from '@growpanel/sdk';

try {
    await gp.customers.detail({ path: { id: 'cus_doesnotexist' } });
} catch (err) {
    if (err instanceof GrowPanelError) {
        if (err.status === 404) {
            // customer doesn't exist
        } else if (err.status === 429) {
            // rate-limited — see Rate limiting docs
        }
    }
    throw err;
}

See error codes for the full list.

Custom fetch

The SDK uses the global fetch by default. Pass a custom implementation for retries, instrumentation, or Workers-specific bindings:

const gp = new GrowPanel({
    apiKey: process.env.GROWPANEL_API_KEY!,
    fetch: env.MY_INSTRUMENTED_FETCH
});

Updating

The SDK is regenerated on every API surface change — usually within minutes of a deploy. To pull the latest:

npm install @growpanel/sdk@latest

Changelog and breaking changes are on GitHub Releases.

Interactive API reference — every endpoint with try-it-out
Python SDK
Go SDK
CLI — same API surface, terminal-friendly
MCP server — same API surface, for AI assistants