Migration guide for v3

Version 3.0.0 of chargebee-dotnet contains some very sizable breaking changes. In v3.x, all integral currency fields have been upgraded from 32-bit to 64-bit.

Reason for the change

v2.x of the SDK supported a maximum value of 214,748,3647—the maximum value for the int type—for all integral currency fields. Consequently, when using v2.x, the following code—which creates an item price—would cause a compilation error:

ApiConfig.Configure("{site}","{site_api_key}");
EntityResult result = ItemPrice.Create()
      .Id("silver-USD-monthly")
      .ItemId("silver")
      .Name("silver USD monthly")
      .#Model(#ModelEnum.PerUnit)
      .Price(21474836478) // Error! Value greater than max possible for `int?`.
      .ExternalName("silver USD")
      .PeriodUnit(PeriodUnitEnum.Month)
      .Period(1)
      .Request();

ItemPrice itemPrice = result.ItemPrice;

This has been a grave limitation for many users.

What has changed

As part of v3.0.0, all integral currency field types have been changed from int to long, bumping up the maximum supported integral currency value in the API to 9,223,372,036,854,775,807.

Below is an example of the change introduced.

In version v2.x the property Price is defined as an int? type:

public int? Price 
{
    get { return GetValue<int?>("price", false); }
}

With v3.x, the type for the same property has been changed to long?:

public long? Price 
{
    get { return GetValue<long?>("price", false); }
}

Steps to migrate from v2.x to v3.x

1. Identify all the places in your codebase where Chargebee's integral currency fields are used. Integral currency fields can be identified by checking their data type in API docs. The data type for such fields is listed as in cents in the docs. See the screenshot below.

3. Change the data type for all those fields from int to long.