PHPackages chargebee/chargebee-php - PHPackages - PHPackages [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register) 1. [Directory](/) 2. / 3. [Payment Processing](/categories/payments) 4. / 5. chargebee/chargebee-php ActiveLibrary[Payment Processing](/categories/payments) chargebee/chargebee-php ======================= ChargeBee API client implementation for PHP v4.23.0(2d ago)758.5M↓32.8%67[9 issues](https://github.com/chargebee/chargebee-php/issues)[1 PRs](https://github.com/chargebee/chargebee-php/pulls)9MITPHPPHP >=8.1.0CI passing Since Jul 10Pushed 2d ago37 watchersCompare [ Source](https://github.com/chargebee/chargebee-php)[ Packagist](https://packagist.org/packages/chargebee/chargebee-php)[ Docs](https://github.com/chargebee/chargebee-php)[ RSS](/packages/chargebee-chargebee-php/feed)WikiDiscussions master Synced 2d ago READMEChangelog (10)Dependencies (28)Versions (242)Used By (9) Chargebee PHP Client Library - API V2 ===================================== [](#chargebee-php-client-library---api-v2) [![Packagist](https://camo.githubusercontent.com/f77f15584c4a0b4ad0f649d6777e5b582b5fa08cd16a94461e5bd793d5fd34c5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6368617267656265652f6368617267656265652d7068702e7376673f6d61784167653d33)](https://packagist.org/packages/chargebee/chargebee-php)[![Packagist](https://camo.githubusercontent.com/bcbd8e7fb7d917eb69a14947693843a96c5b73564d6af628d794219d97f65f6a/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6368617267656265652f6368617267656265652d7068702e7376673f6d61784167653d33)](https://packagist.org/packages/chargebee/chargebee-php/stats)[![Packagist](https://camo.githubusercontent.com/cebdd156ba11589a3db792aad01ecba421fc91d76cc9a4fec552ef8b91e44f39/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646d2f6368617267656265652f6368617267656265652d7068702e7376673f6d61784167653d33)](https://packagist.org/packages/chargebee/chargebee-php/stats)[![Packagist](https://camo.githubusercontent.com/d0b7c18fbab2c4334cf090e176e31ab5f8b18ace0d05d4f4c18379a5371c052f/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6368617267656265652f6368617267656265652d7068702e7376673f6d61784167653d33)](https://packagist.org/packages/chargebee/chargebee-php) Note [![Join Discord](https://camo.githubusercontent.com/ed15441a7673cc5a79d517647e7f3250b96c0f1ca6abf2763742436c134169da/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f446973636f72642d4561726c792532304163636573732d626c75653f6c6f676f3d646973636f7264266c6f676f436f6c6f723d7768697465)](https://discord.gg/S3SXDzXHAg) 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/gpsNqnhDm2) if interested. This is the official PHP library for integrating with Chargebee. - πŸ“˜ For a complete reference of available APIs, check out our [API Documentation](https://apidocs.chargebee.com/docs/api/?lang=php). - πŸ§ͺ To explore and test API capabilities interactively, head over to our [API Explorer](https://api-explorer.chargebee.com). > Note: Chargebee now supports two API versions - [V1](https://apidocs.chargebee.com/docs/api/v1) and [V2](https://apidocs.chargebee.com/docs/api), of which V2 is the latest release and all future developments will happen in V2. This library is for **API version V2**. If you’re looking for V1, head to [chargebee-v1 branch](https://github.com/chargebee/chargebee-php/tree/chargebee-v1). Requirements ------------ [](#requirements) PHP 8.1 or later Installation ------------ [](#installation) ### Composer [](#composer) `Chargebee` is available on [Packagist](https://packagist.org/packages/chargebee/chargebee-php) and can be installed using [Composer](https://getcomposer.org/) ``` composer require chargebee/chargebee-php ``` To use the bindings, ``` require_once('vendor/autoload.php'); ``` Usage ----- [](#usage) ### To create a new subscription: [](#to-create-a-new-subscription) ``` use Chargebee\ChargebeeClient; $chargebee = new ChargebeeClient(options: [ "site" => "{your_site}", "apiKey" => "{your_apiKey}", ]); $result = $chargebee->subscription()->createWithItems("customer_id", [ "subscription_items" => [ [ "item_price_id" => "Montly-Item", "quantity" => "3", ] ] ]); $subscription = $result->subscription; $customer = $result->customer; ``` ### Create an idempotent request [](#create-an-idempotent-request) [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. ``` use Chargebee\ChargebeeClient; $chargebee = new ChargebeeClient(options: [ "site" => "{your_site}", "apiKey" => "{your_apiKey}", ]); $responseCustomer = $chargebee->customer()->create([ "first_name" => "John", "last_name" => "Doe", "email" => "john@test.com", "card" => [ "first_name" => "Joe", "last_name" => "Doe", "number" => "4012888888881881", "expiry_month" => "10", "expiry_year" => "29", "cvv" => "231" ] ], [ "chargebee-idempotency-key" => "" // Replace with a unique string ] ); $responseHeaders = $responseCustomer->getResponseHeaders(); // Retrieves response headers print_r($responseHeaders); $idempotencyReplayedValue = $responseCustomer->isIdempotencyReplayed(); // Retrieves Idempotency replayed header value print_r($idempotencyReplayedValue); ``` `isIdempotencyReplayed()` method can be accessed to differentiate between original and replayed requests. ### Retry Handling [](#retry-handling) Chargebee'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**. #### Key features include: [](#key-features-include) - **Automatic retries for specific HTTP status codes**: Retries are automatically triggered for status codes `500`, `502`, `503`, and `504`. - **Exponential backoff**: Retry delays increase exponentially to prevent overwhelming the server. - **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. > *Note: Exponential backoff and max retries do not apply in this case.* - **Customizable retry behavior**: Retry logic can be configured using the `retryConfig` parameter in the environment configuration. #### Example: Customizing Retry Logic [](#example-customizing-retry-logic) You can enable and configure the retry logic by passing a `retryConfig` object when initializing the Chargebee environment: ``` use Chargebee\ChargebeeClient; // Retry Configurations $retryConfig = new RetryConfig(); $retryConfig->setEnabled(true); // Enable retry mechanism $retryConfig->setMaxRetries(5); // Maximum number of retries $retryConfig->setDelayMs(1000); // Delay in milliseconds before retrying $retryConfig->setRetryOn([500, 502, 503, 504]); // Retry on these HTTP status codes $chargebee = new ChargebeeClient(options: [ "site" => "{your_site}", "apiKey" => "{your_apiKey}", "retryConfig" => $retryConfig, ]); // ... your Chargebee API operations below ... ``` #### Example: Rate Limit retry logic [](#example-rate-limit-retry-logic) You can enable and configure the retry logic for rate-limit by passing a `retryConfig` object when initializing the Chargebee environment: ``` use Chargebee\ChargebeeClient; // Retry Configurations $retryConfig = new RetryConfig(); $retryConfig->setEnabled(true); // Enable retry mechanism $retryConfig->setMaxRetries(5); // Maximum number of retries $retryConfig->setDelayMs(1000); // Delay in milliseconds before retrying $retryConfig->setRetryOn([429]); // Retry on 429 HTTP status codes $chargebee = new ChargebeeClient(options: [ "site" => "{your_site}", "apiKey" => "{your_apiKey}", "retryConfig" => $retryConfig, ]); // ... your Chargebee API operations below ... ``` ### Telemetry (OpenTelemetry) [](#telemetry-opentelemetry) Optional. Pass a `telemetryAdapter` when you want Chargebee API calls traced in your observability stack (Datadog, Splunk, Honeycomb, Jaeger, etc.). OpenTelemetry is not bundled with `chargebee/chargebee-php` β€” install and configure it in your app, implement `TelemetryAdapter`, and wire it on the client. The SDK builds standardized span attributes (`startAttributes`, `endAttributes`) following the stable [OpenTelemetry HTTP semantic conventions](https://opentelemetry.io/docs/specs/semconv/http/http-spans/) (`url.full`, `http.request.method`, `http.response.status_code`, `server.address`, `error.type`) plus Chargebee-specific `chargebee.*` attributes β€” use them as-is so spans render correctly in your APM and stay consistent across SDKs. > **Note:** `url.full` intentionally omits the query string (it carries only scheme, host, and path) to avoid leaking potentially sensitive query parameters into traces. This is a deliberate, cross-SDK PII-safety choice. Spans are named `chargebee.{resource}.{operation}` (e.g. `chargebee.subscription.create`). When no adapter is configured, the SDK skips all telemetry work β€” zero overhead for existing integrations. #### Trace shape [](#trace-shape) The SDK emits **one `CLIENT` span per API call**, covering the full lifecycle. Retries reuse the same span β€” `onRequestStart` runs once before the retry loop and `onRequestEnd` runs once after the final outcome. ``` inbound request span └── chargebee.subscription.create ← parented to caller, propagates to Chargebee └── (Chargebee-side spans) ``` > If you separately enable HTTP auto-instrumentation (e.g. an OpenTelemetry PHP agent on Guzzle), it will create an **additional transport-level HTTP span as a sibling** of the Chargebee span. For the cleanest trace where `chargebee.{resource}.{operation}` is the single propagating span, leave HTTP auto-instrumentation off for Chargebee calls. #### OpenTelemetry setup [](#opentelemetry-setup) OpenTelemetry is not bundled β€” install it in your app: ``` composer require open-telemetry/sdk open-telemetry/exporter-otlp ``` Configure OpenTelemetry at app startup (tracer provider, exporter, propagator), then pass your adapter: ``` use Chargebee\ChargebeeClient; use Chargebee\Telemetry\RequestTelemetryContext; use Chargebee\Telemetry\RequestTelemetryResult; use Chargebee\Telemetry\TelemetryAdapter; use OpenTelemetry\API\Trace\Propagation\TraceContextPropagator; use OpenTelemetry\API\Trace\SpanInterface; use OpenTelemetry\API\Trace\SpanKind; use OpenTelemetry\API\Trace\StatusCode; use OpenTelemetry\API\Trace\TracerInterface; class OtelTelemetryAdapter implements TelemetryAdapter { public function __construct(private readonly TracerInterface $tracer) {} public function onRequestStart(RequestTelemetryContext $context, array &$requestHeaders): mixed { $span = $this->tracer ->spanBuilder($context->spanName) ->setSpanKind(SpanKind::KIND_CLIENT) ->setAttributes($context->startAttributes) ->startSpan(); $scope = $span->activate(); TraceContextPropagator::getInstance()->inject($requestHeaders); $scope->detach(); return $span; } public function onRequestEnd(mixed $handle, RequestTelemetryResult $result): void { if (!$handle instanceof SpanInterface) { return; } $span = $handle; $span->setAttributes($result->endAttributes); if ($result->error !== null) { $span->setStatus(StatusCode::STATUS_ERROR, $result->error->message); } else { $span->setStatus(StatusCode::STATUS_OK); } $span->end(); } } $tracer = \OpenTelemetry\API\Globals::tracerProvider()->getTracer('your-app'); $chargebee = new ChargebeeClient([ 'site' => '{your_site}', 'apiKey' => '{your_apiKey}', 'telemetryAdapter' => new OtelTelemetryAdapter($tracer), ]); ``` `RequestTelemetryResult` also exposes `durationMs` if you want to record request duration on the span (e.g. `$span->setAttribute('chargebee.request.duration_ms', $result->durationMs)`). To add custom span attributes (tenant ID, correlation ID, etc.), set them in your adapter's `onRequestStart` / `onRequestEnd` β€” use your own namespace (e.g. `app.tenant_id`), not `chargebee.*`. Spans are exported by your own OpenTelemetry setup, so they flow to whatever backend you've configured. The Chargebee config above stays the same regardless of backend. License ------- [](#license) See the LICENSE file. ### Health Score 76 β€” ExcellentBetter than 100% of packages Maintenance97 Actively maintained with recent releases Popularity62 Solid adoption and visibility Community39 Small or concentrated contributor base Maturity91 Battle-tested with a long release history Bus Factor2 2 contributors hold 50%+ of commits How is this calculated?**Maintenance (25%)** β€” Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window. **Popularity (30%)** β€” Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores. **Community (15%)** β€” Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement. **Maturity (30%)** β€” Project age, version count, PHP version support, and release stability. ### Release Activity Cadence Every ~20 days Recently: every ~14 days Total 234 Last Release 2d ago Major Versions v3.47.0 β†’ v4.9.02025-09-03 v3.48.0 β†’ 4.10.02025-09-23 v3.49.0 β†’ v4.11.02025-10-28 v3.50.0 β†’ v4.12.02025-11-26 v3.51.0 β†’ v4.14.02026-01-12 PHP version history (2 changes)v3.0.0PHP >=5.6.0 v4.0.0-beta.1PHP >=8.1.0 ### Community Maintainers ![](https://www.gravatar.com/avatar/c1d3bf9c89377cf8045bf8bebed3245072851037f809301361fe2c7d83c0af32?d=identicon)[chargebee](/maintainers/chargebee) --- Top Contributors [![rraman](https://avatars.githubusercontent.com/u/535773?v=4)](https://github.com/rraman "rraman (92 commits)")[![SangeethaBaskaran](https://avatars.githubusercontent.com/u/10059229?v=4)](https://github.com/SangeethaBaskaran "SangeethaBaskaran (87 commits)")[![cb-alish](https://avatars.githubusercontent.com/u/162097444?v=4)](https://github.com/cb-alish "cb-alish (49 commits)")[![cb-vaibhav](https://avatars.githubusercontent.com/u/1768604?v=4)](https://github.com/cb-vaibhav "cb-vaibhav (26 commits)")[![cb-khushbubibay](https://avatars.githubusercontent.com/u/90763103?v=4)](https://github.com/cb-khushbubibay "cb-khushbubibay (14 commits)")[![cb-goutham](https://avatars.githubusercontent.com/u/35914593?v=4)](https://github.com/cb-goutham "cb-goutham (12 commits)")[![cb-yateshmathuria](https://avatars.githubusercontent.com/u/85875129?v=4)](https://github.com/cb-yateshmathuria "cb-yateshmathuria (11 commits)")[![hellokps](https://avatars.githubusercontent.com/u/872557?v=4)](https://github.com/hellokps "hellokps (10 commits)")[![saravana-cb](https://avatars.githubusercontent.com/u/3005472?v=4)](https://github.com/saravana-cb "saravana-cb (9 commits)")[![cb-navaneedhan](https://avatars.githubusercontent.com/u/64066477?v=4)](https://github.com/cb-navaneedhan "cb-navaneedhan (7 commits)")[![cb-thushitamariaselvan](https://avatars.githubusercontent.com/u/126495463?v=4)](https://github.com/cb-thushitamariaselvan "cb-thushitamariaselvan (6 commits)")[![cb-nithins](https://avatars.githubusercontent.com/u/126080858?v=4)](https://github.com/cb-nithins "cb-nithins (5 commits)")[![cb-gaurav](https://avatars.githubusercontent.com/u/55385089?v=4)](https://github.com/cb-gaurav "cb-gaurav (4 commits)")[![cb-sriramthiagarajan](https://avatars.githubusercontent.com/u/78782731?v=4)](https://github.com/cb-sriramthiagarajan "cb-sriramthiagarajan (3 commits)")[![cb-karthikp](https://avatars.githubusercontent.com/u/78947874?v=4)](https://github.com/cb-karthikp "cb-karthikp (3 commits)")[![geoffreytran](https://avatars.githubusercontent.com/u/544500?v=4)](https://github.com/geoffreytran "geoffreytran (3 commits)")[![bjdelange](https://avatars.githubusercontent.com/u/2757512?v=4)](https://github.com/bjdelange "bjdelange (2 commits)")[![cb-bharathvaj](https://avatars.githubusercontent.com/u/44696641?v=4)](https://github.com/cb-bharathvaj "cb-bharathvaj (2 commits)")[![Wojciechem](https://avatars.githubusercontent.com/u/4303141?v=4)](https://github.com/Wojciechem "Wojciechem (1 commits)")[![bharathvaj-ganesan](https://avatars.githubusercontent.com/u/16360498?v=4)](https://github.com/bharathvaj-ganesan "bharathvaj-ganesan (1 commits)") --- Tags chargebeephppaymentschargebeesubscription billingrecurring billing ### Code Quality TestsPHPUnit Static AnalysisPHPStan Type Coverage Yes ### Embed Badge ![Health badge](/badges/chargebee-chargebee-php/health.svg) ``` [![Health](https://phpackages.com/badges/chargebee-chargebee-php/health.svg)](https://phpackages.com/packages/chargebee-chargebee-php) ``` ### Alternatives [tempest/framework The PHP framework that gets out of your way. 2.2k34.4k15](/packages/tempest-framework)[flow-php/flow PHP ETL - Extract Transform Load - Data processing framework 85036.3k](/packages/flow-php-flow)[sylius/sylius E-Commerce platform for PHP, based on Symfony framework. 8.5k5.9M737](/packages/sylius-sylius)[telnyx/telnyx-php Official Telnyx PHP SDK β€” APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network. 35789.4k2](/packages/telnyx-telnyx-php)[drupal/core-recommended Locked core dependencies; require this project INSTEAD OF drupal/core. 6942.5M421](/packages/drupal-core-recommended)[typo3/cms TYPO3 CMS is a free open source Content Management Framework initially created by Kasper Skaarhoj and licensed under GNU/GPL. 1.2k1.9M122](/packages/typo3-cms) PHPackages Β© 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)