https://github.com/chargebee/chargebee-dotnet
.NET library for the Chargebee API.
https://github.com/chargebee/chargebee-dotnet
chargebee dotnet
Last synced: 12 days ago
JSON representation
.NET library for the Chargebee API.
- Host: GitHub
- URL: https://github.com/chargebee/chargebee-dotnet
- Owner: chargebee
- License: mit
- Created: 2013-03-23T14:49:54.000Z (about 13 years ago)
- Default Branch: master
- Last Pushed: 2026-03-27T05:59:56.000Z (3 months ago)
- Last Synced: 2026-03-27T17:48:23.152Z (3 months ago)
- Topics: chargebee, dotnet
- Language: C#
- Homepage: https://apidocs.chargebee.com/docs/api?lang=dotnet
- Size: 8.75 MB
- Stars: 26
- Watchers: 40
- Forks: 25
- Open Issues: 12
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Security: SECURITY.md
Awesome Lists containing this project
README
# .NET Client Library for Chargebee API
> [!NOTE]
> [](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.
***
[](https://www.nuget.org/packages/ChargeBee/)
and
[](https://www.nuget.org/packages/ChargeBee/)
This is the official .NET library for integrating with Chargebee.
- 📘 For a complete reference of available APIs, check out our [API Documentation](https://apidocs.chargebee.com/docs/api/?lang=dotnet).
- 🧪 To explore and test API capabilities interactively, head over to our [API Explorer](https://api-explorer.chargebee.com).
The latest version (v3) of the library supports the following:
- .NET Standard 1.2+
- .NET Core 1.0+
- .NET Framework 4.5+
## Library versions
***
The versioning scheme of this library is inspired by [SemVer](https://semver.org/) and the format is `v{MAJOR}.{MINOR}.{PATCH}`. For example, `v3.0.0` and `v2.5.1` are valid library versions.
The following table provides some details for each major version:
| Library major version | Status | Compatible API versions | **Branch** |
|----------------------------|----------|-----------------------------------------------------------------------------------------------------------------|---------------|
| v3 | Active | [v2](https://apidocs.chargebee.com/docs/api/v2?lang=dotnet) and [v1](https://apidocs.chargebee.com/docs/api/v1?lang=dotnet) | `master` |
| v2 | Inactive | [v2](https://apidocs.chargebee.com/docs/api/v2?lang=dotnet) and [v1](https://apidocs.chargebee.com/docs/api/v1?lang=dotnet) | `chargebee-v2`|
| v1 | Inactive | [v1](https://apidocs.chargebee.com/docs/api/v1?lang=dotnet) | `chargebee-v1`|
A couple of terms used in the above table are explained below:
- **Status**: The current development status for the library version. An **Active** major version is currently being maintained and continues to get backward-compatible changes. **Inactive** versions no longer receive any updates.
- **Branch**: The branch in this repository containing the source code for the latest release of the library version. Every version of the library has been [tagged](https://github.com/chargebee/chargebee-dotnet/tags). You can check out the source code for any version using its tag.
🔴 **Attention**: The support for v2 will eventually be discontinued on **December 31st 2023** and will no longer receive any further updates. We strongly recommend [upgrading to v3](https://github.com/chargebee/chargebee-dotnet/wiki/Migration-guide-for-v3) as soon as possible.
**Note:** See the [changelog](CHANGELOG.md) for a history of changes.
## Install the library
***
You can install any release of an **active** library version using [NuGet](https://nuget.org)—a package manager for Visual Studio—by running the following command in the NuGet Package Manager Console:
```shell
$ Install-Package ChargeBee -Version {MAJOR}.{MINOR}.{PATCH}
```
For example, the following commands are valid:
- Install the latest version:
```shell
$ Install-Package ChargeBee -Version 3.0.0
```
- Install an earlier version, say v2.5.1:
```shell
$ Install-Package ChargeBee -Version 2.5.1
```
## Use the library
***
Some examples for using the library are listed below.
### [Create a new subscription](https://apidocs.chargebee.com/docs/api/subscriptions?prod_cat_ver=2&lang=dotnet#create_subscription_for_items)
```cs
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("site","api_key");
EntityResult result = Subscription.Create()
.PlanId("basic")
.Request();
Subscription subscription = result.Subscription;
Customer customer = result.Customer;
```
### 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.
```cs
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("site","api_key");
EntityResult result = Customer.Create()
.FirstName("John")
.LastName("Doe")
.Email("john@test.com")
.SetIdempotencyKey("<>") // Replace <> with a unique string
.Request();
Customer customer = result.Customer;
Console.WriteLine(ApiConfig.SerializeObject(customer));
HttpResponseHeaders httpResponseHeaders = result.ResponseHeaders; // Retrieves response headers
Console.WriteLine(httpResponseHeaders);
string idempotencyReplayedValue = result.IsIdempotencyReplayed(); // Retrieves idempotency replayed header value
Console.WriteLine(idempotencyReplayedValue);
```
`isIdempotencyReplayed()` method can be accessed to differentiate between original and replayed requests.
### Serialize an object
```cs
ApiConfig.SerializeObject(obj);
```
### Deserialize an object
```cs
ApiConfig.DeserializeObject(jsonString);
```
### 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:
- **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
You can enable and configure the retry logic by passing a `retryConfig` object when initializing the Chargebee environment:
```cs
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("site","api_key");
ChargeBee.Api.RetryConfig retryConfig = new ChargeBee.Api.RetryConfig
{
Enabled = true, // Enable retry logic
MaxRetries = 5, // Maximum number of retries
DelayMs = 300, // Initial delay between retries in milliseconds
RetryOnStatus = [500] // HTTP status codes to retry on
};
ApiConfig.UpdateRetryConfig(retryConfig);
EntityResult result = Customer.Create()
.FirstName("John")
.LastName("Doe")
.Email("john@test.com")
.Reqeust();
```
#### 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:
```cs
using ChargeBee.Api;
using ChargeBee.Models;
ApiConfig.Configure("site","api_key");
ChargeBee.Api.RetryConfig retryConfig = new ChargeBee.Api.RetryConfig
{
Enabled = true, // Enable retry logic
MaxRetries = 5, // Maximum number of retries
DelayMs = 300, // Initial delay between retries in milliseconds
RetryOnStatus = [429] // HTTP status codes to retry on
};
ApiConfig.UpdateRetryConfig(retryConfig);
EntityResult result = Customer.Create()
.FirstName("John")
.LastName("Doe")
.Email("john@test.com")
.Reqeust();
```
## Contribution
***
You may contribute patches to any of the **Active** versions of this library. To do so, raise a PR against the [respective branch](#library-versions).
If you find something amiss, you are welcome to create an [issue](https://github.com/chargebee/chargebee-dotnet/issues).
## API documentation
***
The API documentation for the .NET library can be found in our [API reference](https://apidocs.chargebee.com/docs/api?lang=dotnet).
## License
***
See the [LICENSE](LICENSE).
***