{"id":28254968,"url":"https://github.com/chargebee/chargebee-node","last_synced_at":"2026-05-04T09:02:09.656Z","repository":{"id":13581536,"uuid":"16274159","full_name":"chargebee/chargebee-node","owner":"chargebee","description":"Node.js library for the Chargebee API.","archived":false,"fork":false,"pushed_at":"2026-05-04T03:20:55.000Z","size":1761,"stargazers_count":60,"open_issues_count":7,"forks_count":30,"subscribers_count":33,"default_branch":"master","last_synced_at":"2026-05-04T05:15:42.886Z","etag":null,"topics":["chargebee","javascript","nodejs"],"latest_commit_sha":null,"homepage":"https://apidocs.chargebee.com/docs/api?lang=node","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"deadlyvipers/dojo_rules","license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/chargebee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2014-01-27T09:06:09.000Z","updated_at":"2026-04-26T11:13:29.000Z","dependencies_parsed_at":"2024-05-02T12:26:13.847Z","dependency_job_id":"12d9db60-bbc9-4a13-82b3-74fedeeaeb3a","html_url":"https://github.com/chargebee/chargebee-node","commit_stats":{"total_commits":125,"total_committers":13,"mean_commits":9.615384615384615,"dds":0.656,"last_synced_commit":"b4e5e3fc3296aea09f2196ffbcf16416d332ee41"},"previous_names":[],"tags_count":209,"template":false,"template_full_name":null,"purl":"pkg:github/chargebee/chargebee-node","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargebee%2Fchargebee-node","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargebee%2Fchargebee-node/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargebee%2Fchargebee-node/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargebee%2Fchargebee-node/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/chargebee","download_url":"https://codeload.github.com/chargebee/chargebee-node/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/chargebee%2Fchargebee-node/sbom","scorecard":{"id":274117,"data":{"date":"2025-08-11","repo":{"name":"github.com/chargebee/chargebee-node","commit":"aab60ab0c1c440cb5b1b1c8aa7be29e344d96ca2"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":5.9,"checks":[{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":4,"reason":"4 commit(s) and 1 issue activity found in the last 90 days -- score normalized to 4","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Security-Policy","score":10,"reason":"security policy file detected","details":["Info: security policy file detected: SECURITY.md:1","Info: Found linked content: SECURITY.md:1","Info: Found disclosure, vulnerability, and/or timelines in security policy: SECURITY.md:1","Info: Found text in security policy: SECURITY.md:1"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Code-Review","score":2,"reason":"Found 5/20 approved changesets -- score normalized to 2","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":-1,"reason":"internal error: error during branchesHandler.setup: internal error: githubv4.Query: Resource not accessible by integration","details":null,"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"SAST","score":5,"reason":"SAST tool is not run on all commits -- score normalized to 5","details":["Warn: 10 commits out of 20 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}}]},"last_synced_at":"2025-08-17T14:03:02.950Z","repository_id":13581536,"created_at":"2025-08-17T14:03:02.950Z","updated_at":"2025-08-17T14:03:02.950Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32600968,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T22:12:39.696Z","status":"online","status_checked_at":"2026-05-04T02:00:06.625Z","response_time":58,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chargebee","javascript","nodejs"],"created_at":"2025-05-19T20:16:35.314Z","updated_at":"2026-05-04T09:02:09.632Z","avatar_url":"https://github.com/chargebee.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Chargebee Node.js / TypeScript Client Library\n\n\u003e [!NOTE]\n\u003e [![Join Discord](https://img.shields.io/badge/Discord-Early%20Access-blue?logo=discord\u0026logoColor=white)](https://discord.gg/gpsNqnhDm2)\n\u003e\n\u003e We are trialing a Discord server for developers building with Chargebee. Limited spots are open on a first-come basis. Join [here](https://discord.gg/S3SXDzXHAg) if interested.\n\n\n\u003e [!TIP]\n\u003e If you are using [Next.js](https://nextjs.org/) or [Express](https://expressjs.com/), check out [chargebee-init](https://www.npmjs.com/package/chargebee-init) to get started quickly with the adapters for these frameworks. Learn more about it in this [tutorial](https://www.chargebee.com/tutorials/chargebee-init-nextjs-integration/).\n\n\n- 📘 For a complete reference of available APIs, check out our [API Documentation](https://apidocs.chargebee.com/docs/api/?lang=node).  \n- 🧪 To explore and test API capabilities interactively, head over to our [API Explorer](https://api-explorer.chargebee.com).\n\nIf you're upgrading from an older version of [`chargebee-typescript`](https://www.npmjs.com/package/chargebee-typescript) or [`chargebee`](https://www.npmjs.com/package/chargebee/v/2.40.0), please refer to the [Migration Guide](https://github.com/chargebee/chargebee-node/wiki/Migration-guide-for-v3).\n\n\n## Requirements\n\nNode.js 18 or higher.\n\n## Runtime Support\n\nThis SDK supports multiple JavaScript runtimes:\n\n- **Node.js** 18+\n- **Deno**\n- **Bun**\n- **Cloudflare Workers**\n- **Edge Runtimes** (e.g., Vercel Edge, Netlify Edge Functions)\n\n## Installation\n\nInstall the library with npm:\n\n```sh\nnpm install chargebee\n```\nWith pnpm:\n```sh\npnpm add chargebee\n```\n\nWith yarn:\n```sh\nyarn add chargebee\n```\n\nWith bun:\n```sh\nbun add chargebee\n```\n\nWith deno:\n```sh\ndeno add npm:chargebee\n```\n\n## Usage\n\nThe package needs to be configured with your site's API key, which is available under Configure Chargebee Section. Refer [here](https://www.chargebee.com/docs/2.0/api_keys.html) for more details.\n\nIf you're using ESM / TypeScript:\n\n```typescript\nimport Chargebee from 'chargebee';\n\nconst chargebee = new Chargebee({\n  site: \"{{site}}\",\n  apiKey: \"{{api-key}}\",\n});\n```\n\nOr using Common JS module system:\n\n```javascript\nconst Chargebee = require('chargebee');\n\nconst chargebee = new Chargebee({\n  site: \"{{site}}\",\n  apiKey: \"{{api-key}}\",\n});\n```\n\n### Using Deno:\n\n```typescript\nimport Chargebee from \"npm:chargebee\";\n\nconst chargebee = new Chargebee({\n  site: \"{{site}}\",\n  apiKey: \"{{api-key}}\",\n});\n\nconst response = await chargebee.customer.list();\nconsole.log(response);\n```\n\n### Using Bun:\n\n```typescript\nimport Chargebee from \"chargebee\";\n\nconst chargebee = new Chargebee({\n  site: \"{{site}}\",\n  apiKey: \"{{api-key}}\",\n});\n\nconst response = await chargebee.customer.list();\nconsole.log(response);\n```\n\n### Using Async / Await\n\n```typescript\ntry {\n  const { customer } = await chargebee.customer.create({\n    email: \"john@test.com\"\n    // other params\n  });\n} catch (err) {\n  // handle error\n}\n```\n\n### Using filters in the List API\n\nFor pagination, `offset` is the parameter that is being used. The value used for this parameter must be the value returned for `next_offset` parameter in the previous API call.\n\n```typescript\nasync function getAllCustomers() {\n  const allCustomers: Customer[] = [];\n  let offset: string | undefined = undefined;\n\n  do {\n    const listCustomersReponse = await chargebee.customer.list({\n      limit: 2,\n      offset,\n      first_name: {\n        is: \"John\"\n      }\n    });\n\n    const customers = listCustomersReponse.list.map(\n      (object) =\u003e object.customer\n    );\n    \n    allCustomers.push(...customers);\n    offset = listCustomersReponse.next_offset;\n  } while (offset);\n\n  console.log(allCustomers);\n}\n```\n\n### Using custom headers and custom fields\n\n```typescript\nconst { customer } = await chargebee.customer.create(\n  {\n    email: \"john@test.com\",\n    cf_host_url: \"http://xyz.com\" // `cf_host_url` is a custom field in Customer object\n  },\n  {\n    \"chargebee-event-email\": \"all-disabled\" // To disable webhooks\n  }\n);\n```\n\n### Creating an idempotent request\n\n[Idempotency keys](https://apidocs.chargebee.com/docs/api/idempotency?prod_cat_ver=2) are passed along with request headers to allow a safe retry of POST requests.\n\n```typescript\nconst { customer, isIdempotencyReplayed } = await chargebee.customer.create(\n  { email: \"john@test.com\" },\n  {\n    \"chargebee-idempotency-key\": \"eBs7iOFQuR7asUKHfddyxDDerOuF1JtFrLmDI\" // Add idempotency key\n  }\n);\nconsole.log(\"isIdempotencyReplayed: \", isIdempotencyReplayed);\n```\n\n### Creating multiple instances of Chargebee for different sites\n\n```typescript\nconst chargebeeSiteUS = new Chargebee({\n  apiKey: \"{api-key}\",\n  site: \"my-site-us\"\n});\n\nconst chargebeeSiteEU = new Chargebee({\n  apiKey: \"{api-key}\",\n  site: \"my-site-eu\"\n});\n```\n\n### Handle webhooks\n\nUse the webhook handlers to parse and route webhook payloads from Chargebee with full TypeScript support.\n\n#### Quick Start: Using the instance `webhooks` handler\n\nThe simplest way to handle webhooks is using the `webhooks` property on your initialized Chargebee client:\n\n```typescript\nimport express from 'express';\nimport Chargebee, {\n  WebhookEventType,\n  AuthenticationError,\n  PayloadValidationError,\n  PayloadParseError,\n} from 'chargebee';\n\nconst chargebee = new Chargebee({\n  site: '{{site}}',\n  apiKey: '{{api-key}}',\n});\n\nconst app = express();\napp.use(express.json());\n\n// ⚠️ Register listeners once at startup, not inside request handlers\nchargebee.webhooks.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) =\u003e {\n  console.log(`Subscription created: ${event.id}`);\n  const subscription = event.content.subscription;\n  console.log(`Customer: ${subscription.customer_id}`);\n  response?.status(200).send('OK');\n});\n\nchargebee.webhooks.on('error', (error, { response }) =\u003e {\n  if (error instanceof AuthenticationError) {\n    response?.status(401).send('Unauthorized');\n  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {\n    response?.status(400).send('Bad Request');\n  } else {\n    console.error('Webhook error:', error.message);\n    response?.status(500).send('Internal Server Error');\n  }\n});\n\napp.post('/chargebee/webhooks', async (req, res) =\u003e {\n  await chargebee.webhooks.handle({\n    body: req.body,\n    headers: req.headers,\n    request: req,\n    response: res,\n  });\n});\n\napp.listen(8080);\n```\n\n**Auto-configured Basic Auth:** The `webhooks` handler automatically configures Basic Auth validation if the following environment variables are set:\n\n- `CHARGEBEE_WEBHOOK_USERNAME` - The expected username\n- `CHARGEBEE_WEBHOOK_PASSWORD` - The expected password\n\nWhen both are present, incoming webhook requests will be validated against these credentials.\n\n#### Creating typed webhook handlers\n\nFor more control or multiple webhook endpoints, use `chargebee.webhooks.createHandler()`:\n\n```typescript\nimport express, { Request, Response } from 'express';\nimport Chargebee, {\n  WebhookEventType,\n  basicAuthValidator,\n  AuthenticationError,\n  PayloadValidationError,\n  PayloadParseError,\n} from 'chargebee';\n\nconst chargebee = new Chargebee({\n  site: '{{site}}',\n  apiKey: '{{api-key}}',\n});\n\nconst app = express();\napp.use(express.json());\n\n// Create a typed handler for Express\nconst handler = chargebee.webhooks.createHandler\u003cRequest, Response\u003e();\n\n// Optional: Add request validator (e.g., Basic Auth)\nhandler.requestValidator = basicAuthValidator((username, password) =\u003e {\n  return username === 'admin' \u0026\u0026 password === 'secret';\n});\n\n// ⚠️ Register event listeners once at startup, not inside request handlers\nhandler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) =\u003e {\n  console.log(`Subscription created: ${event.id}`);\n  const subscription = event.content.subscription;\n  console.log(`Customer: ${subscription.customer_id}`);\n  console.log(`Plan: ${subscription.plan_id}`);\n  response?.status(200).send('OK');\n});\n\nhandler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) =\u003e {\n  console.log(`Payment succeeded: ${event.id}`);\n  const transaction = event.content.transaction;\n  const customer = event.content.customer;\n  console.log(`Amount: ${transaction.amount}, Customer: ${customer.email}`);\n  response?.status(200).send('OK');\n});\n\nhandler.on('error', (error, { response }) =\u003e {\n  if (error instanceof AuthenticationError) {\n    response?.status(401).send('Unauthorized');\n  } else if (error instanceof PayloadValidationError || error instanceof PayloadParseError) {\n    response?.status(400).send('Bad Request');\n  } else {\n    console.error('Webhook error:', error.message);\n    response?.status(500).send('Internal Server Error');\n  }\n});\n\napp.post('/chargebee/webhooks', async (req, res) =\u003e {\n  await handler.handle({\n    body: req.body,\n    headers: req.headers,\n    request: req,\n    response: res,\n  });\n});\n\napp.listen(8080);\n```\n\n#### Low-level: Parse and handle events manually\n\nFor more control, you can parse webhook events manually:\n\n```typescript\nimport express from 'express';\nimport Chargebee, { type WebhookEvent, WebhookEventType } from 'chargebee';\n\nconst app = express();\napp.use(express.json());\n\napp.post('/chargebee/webhooks', async (req, res) =\u003e {\n  try {\n    const event = req.body as WebhookEvent;\n\n    switch (event.event_type) {\n      case WebhookEventType.SubscriptionCreated: {\n        // Cast to specific event type for proper content typing\n        const typedEvent = event as WebhookEvent\u003cWebhookEventType.SubscriptionCreated\u003e;\n        const subscription = typedEvent.content.subscription;\n        console.log('Subscription created:', subscription.id);\n        break;\n      }\n\n      case WebhookEventType.PaymentSucceeded: {\n        const typedEvent = event as WebhookEvent\u003cWebhookEventType.PaymentSucceeded\u003e;\n        const transaction = typedEvent.content.transaction;\n        console.log('Payment succeeded:', transaction.amount);\n        break;\n      }\n\n      default:\n        console.log('Unhandled event type:', event.event_type);\n    }\n\n    res.status(200).send('OK');\n  } catch (err) {\n    console.error('Error processing webhook:', err);\n    res.status(500).send('Error processing webhook');\n  }\n});\n\napp.listen(8080);\n```\n\n#### Responding to Webhooks\n\n\u003e ⚠️ **Important:** Always send an HTTP response from your webhook handlers. If you don't respond with a 2xx status, Chargebee will retry the webhook, potentially causing duplicate processing.\n\n**Respond with 200** to acknowledge receipt:\n\n```typescript\nhandler.on(WebhookEventType.SubscriptionCreated, async ({ event, response }) =\u003e {\n  await provisionAccess(event.content.subscription);\n  response?.status(200).json({ received: true });\n});\n```\n\n**Respond with 5xx** so Chargebee retries on failure:\n\n```typescript\nhandler.on(WebhookEventType.PaymentSucceeded, async ({ event, response }) =\u003e {\n  try {\n    await recordPayment(event.content.transaction);\n    response?.status(200).send('OK');\n  } catch (err) {\n    response?.status(500).json({ error: 'Processing failed' });\n  }\n});\n```\n\n**Access request context** (headers, middleware data):\n\n```typescript\nhandler.on(WebhookEventType.CustomerCreated, async ({ event, request, response }) =\u003e {\n  const tenantId = (request as any)?.tenant?.id;\n  await createCustomerForTenant(tenantId, event.content.customer);\n  response?.status(200).send('OK');\n});\n```\n\n#### Handling Unhandled Events and Errors\n\nThe webhook handler provides specific error classes for different failure scenarios:\n\n- **`AuthenticationError`** - Authentication failed (missing/invalid credentials)\n- **`PayloadValidationError`** - Invalid webhook payload structure (missing required fields)\n- **`PayloadParseError`** - Failed to parse JSON body\n\n```typescript\nimport {\n  AuthenticationError,\n  PayloadValidationError,\n  PayloadParseError,\n} from 'chargebee';\n\n// Handle events without registered listeners\nhandler.on('unhandled_event', async ({ event, response }) =\u003e {\n  console.log(`Unhandled: ${event.event_type}`);\n  response?.status(200).send('OK');\n});\n\n// Handle errors with appropriate HTTP status codes\nhandler.on('error', (error, { response }) =\u003e {\n  if (error instanceof AuthenticationError) {\n    console.error('Authentication failed:', error.message);\n    response?.status(401).send('Unauthorized');\n  } else if (error instanceof PayloadValidationError) {\n    console.error('Invalid payload:', error.message);\n    response?.status(400).send('Bad Request');\n  } else if (error instanceof PayloadParseError) {\n    console.error('Failed to parse JSON:', error.message);\n    response?.status(400).send('Bad Request');\n  } else {\n    console.error('Unknown error:', error.message);\n    response?.status(500).send('Internal Server Error');\n  }\n});\n```\n\n### Processing Webhooks - API Version Check\n\nAn attribute `api_version` is added to the [Event](https://apidocs.chargebee.com/docs/api/events) resource, which indicates the API version based on which the event content is structured. In your webhook servers, ensure this `api_version` is the same as the [API version](https://apidocs.chargebee.com/docs/api#versions) used by your webhook server's client library.\n\n### Retry Handling\n\nChargebee's SDK includes built-in retry logic to handle temporary network issues and server-side errors. This feature is **disabled by default** but can be **enabled when needed**.\n\n#### Key features include:\n\n- **Automatic retries for specific HTTP status codes**: Retries are automatically triggered for status codes `500`, `502`, `503`, and `504`.\n- **Exponential backoff**: Retry delays increase exponentially to prevent overwhelming the server.\n- **Rate limit management**: If a `429 Too Many Requests` response is received with a `Retry-After` header, the SDK waits for the specified duration before retrying.  \n  \u003e *Note: Exponential backoff and max retries do not apply in this case.*\n- **Customizable retry behavior**: Retry logic can be configured using the `retryConfig` parameter in the environment configuration.\n\n#### Example: Customizing Retry Logic\n\nYou can enable and configure the retry logic by passing a `retryConfig` object when initializing the Chargebee environment:\n\n```typescript\nimport Chargebee from 'chargebee';\n\nconst chargebee = new Chargebee({\n  site: \"{{site}}\",\n  apiKey: \"{{api-key}}\",\n  retryConfig: {\n    enabled: true, // Enable retry logic\n    maxRetries: 5, // Maximum number of retries\n    delayMs: 300, // Initial delay between retries in milliseconds\n    retryOn: [500, 502, 503, 504], // HTTP status codes to retry on\n  },\n});\n\ntry {\n  const { customer } = await chargebee.customer.create({\n    email: \"john@test.com\",\n  });\n  console.log(\"Customer created:\", customer);\n} catch (err) {\n  console.error(\"Request failed after retries:\", err);\n}\n```\n\n#### Example: Rate Limit retry logic\n\nYou can enable and configure the retry logic for rate-limit by passing a `retryConfig` object when initializing the Chargebee environment:\n\n```typescript\nimport Chargebee from 'chargebee';\n\nconst chargebee = new Chargebee({\n  site: \"{{site}}\",\n  apiKey: \"{{api-key}}\",\n  retryConfig: {\n    enabled: true,\n    retryOn: [429], \n  },\n});\n\ntry {\n  const { customer } = await chargebee.customer.create({\n    email: \"john@test.com\",\n  });\n  console.log(\"Customer created:\", customer);\n} catch (err) {\n  console.error(\"Request failed after retries:\", err);\n}\n```\n\n### Webhook Type Mapping\nTo improve type safety and gain better autocompletion when working with webhooks, you can leverage the `WebhookEvent` resource. This allows you to strongly type the event content for a particular webhook event.\n\n#### Example\n\n```ts\nimport Chargebee, { WebhookEventType, WebhookEvent } from \"chargebee\";\n\nconst result = await chargebeeInstance.event.retrieve(\"{event-id}\");\nconst subscriptionActivatedEvent: WebhookEvent\u003cWebhookEventType.SubscriptionActivated\u003e = result.event;\nconst subscription = subscriptionActivatedEvent.content.subscription;\n```\n\n#### Notes\n\n* `WebhookEvent\u003cT\u003e` provides type hinting for the event payload, making it easier to work with specific event structures.\n* Use the `WebhookEventType` to specify the exact event type (e.g., `SubscriptionCreated`, `InvoiceGenerated`, etc.).\n* This approach ensures you get proper IntelliSense and compile-time checks when accessing event fields.\n\n### Custom HTTP Client\n\nThe SDK supports injecting a **custom HTTP client**, giving you full flexibility to control how API requests are made and handled. This feature is useful if you want to integrate your own networking stack, add custom logging, implement telemetry, or handle retries in a specific way.\n\nWith this enhancement, you can replace the default HTTP client with your own implementation by passing a custom client that adheres to the `HttpClientInterface` contract when initializing the Chargebee instance.\n\n```js\nconst chargebee = new Chargebee({\n    site: \"{site}\",\n    apiKey: \"{key}\",\n    httpClient: new CustomHttpClient(),\n});\n```\n\n#### Notes\n* Your custom client must implement the `HttpClientInterface` provided by the SDK.\n* This feature is especially useful in environments with strict networking policies or where advanced observability is required.\n* Example implementations are available under:\n\n  * [`/examples/customHttpClient/axiosHttpClient.ts`](./examples/customHttpClient/axiosHttpClient.ts)\n  * [`/examples/customHttpClient/kyHttpClient.ts`](./examples/customHttpClient/kyHttpClient.ts)\n* You may need to implement custom conversion logic when integrating third-party HTTP libraries, as their request and response formats might not directly align with the `HttpClientInterface` expected by the SDK.\n\nThese examples demonstrate how to implement and inject custom clients using `axios` and `ky`, respectively.\n\n## Feedback\n\nIf you find any bugs or have any questions / feedback, open an issue in this repository or reach out to us on dx@chargebee.com\n\n\n## v2\n\nChargebee Node SDK v2 is deprecated. If you using v2, follow [this guide](https://github.com/chargebee/chargebee-node/wiki/Migration-guide-for-v3) to migrate to v3.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchargebee%2Fchargebee-node","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fchargebee%2Fchargebee-node","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fchargebee%2Fchargebee-node/lists"}