Migration guide for v22

Version 22 of Stripe.net contains a large number of changes. This guide will help you update your Stripe integration so that it keeps working as expected after you upgrade to v22.

Breaking changes

Event deserialization with EventUtility.ConstructEvent / EventUtility.ParseEvent

One of the most important changes in this version is that deserializing an event using the EventUtility.ConstructEvent or EventUtility.ParseEvent methods will now throw a StripeException if the library detects a mismatch between the event's API version and the API version the library is pinned to (which is 2018-11-08 for Stripe.net 22.0.0).

This is a safety feature to ensure that the events you receive via your webhook handler are formatted as the library expects. Otherwise this could lead to missing information (e.g. if an attribute was renamed) or even crashes (e.g. if the library expects a non-nullable value type that is missing in the event's JSON).

You can disable this behavior by passing throwOnApiVersionMismatch: false to either method, but we don't recommend you do this.

Type changes

• InvoiceService.ListUpcomingLineItems now accepts a UpcomingInvoiceListLineItemsOptions instead of a UpcomingInvoiceOptions. The new UpcomingInvoiceListLineItemsOptions class has all the same attributes as UpcomingInvoiceOptions, but also accepts pagination parameters.

• Recipient.ActiveAccount is now a BankAccount instead of a RecipientActiveAccount. The RecipientActiveAccount class has been removed entirely.

• Deleted is now a bool? instead of a bool on all classes.

• All arrays have been replaced by lists:

Property	Old type	New type
AccountVerification.FieldsNeeded	string[]	List<string>
Card.AvailablePayoutMethods	string[]	List<string>
Requirements.CurrentlyDue	string[]	List<string>
Requirements.EventuallyDue	string[]	List<string>
Requirements.PastDue	string[]	List<string>
Product.Attributes	string[]	List<string>
Product.DeactivateOn	string[]	List<string>
Product.Images	string[]	List<string>
WebhookEndpoint.EnabledEvents	string[]	List<string>
BankAccountVerifyOptions.Amounts	long[]	List<long>
OrderListOptions.Ids	string[]	List<string>
OrderListOptions.UpstreamIds	string[]	List<string>
ProductCreateOptions.Attributes	string[]	List<string>
ProductCreateOptions.DeactivateOn	string[]	List<string>
ProductCreateOptions.Images	string[]	List<string>
ProductListOptions.Ids	string[]	List<string>
ProductUpdateOptions.Attributes	string[]	List<string>
ProductUpdateOptions.DeactivateOn	string[]	List<string>
ProductUpdateOptions.Images	string[]	List<string>
SkuListOptions.Ids	string[]	List<string>
WebhookEndpointCreateOptions.EnabledEvents	string[]	List<string>
WebhookEndpointUpdateOptions.EnabledEvents	string[]	List<string>

Name changes

The following properties have been renamed:

Old name	New name
Account.BusinessLogoFileId	Account.BusinessLogoId
LegalEntityVerification.DocumentIdBack	LegalEntityVerification.DocumentBackId
Evidence.CancellationPolicyFileId	Evidence.CancellationPolicyId
Evidence.CancellationPolicyFile	Evidence.CancellationPolicy
Evidence.CustomerCommunicationFileId	Evidence.CustomerCommunicationId
Evidence.CustomerCommunicationFile	Evidence.CustomerCommunication
Evidence.CustomerSignatureFileId	Evidence.CustomerSignatureId
Evidence.CustomerSignatureFile	Evidence.CustomerSignature
Evidence.CustomerSignatureFileId	Evidence.CustomerSignatureId
Evidence.CustomerSignatureFile	Evidence.CustomerSignature
Evidence.DuplicateChargeDocumentationFileId	Evidence.DuplicateChargeDocumentationId
Evidence.DuplicateChargeDocumentationFile	Evidence.DuplicateChargeDocumentation
Evidence.ReceiptFileId	Evidence.ReceiptId
Evidence.ReceiptFile	Evidence.Receipt
Evidence.RefundPolicyFileId	Evidence.RefundPolicyId
Evidence.RefundPolicyFile	Evidence.RefundPolicy
Evidence.ServiceDocumentationFileId	Evidence.ServiceDocumentationId
Evidence.ServiceDocumentationFile	Evidence.ServiceDocumentation
Evidence.ShippingDocumentationFileId	Evidence.ShippingDocumentationId
Evidence.ShippingDocumentationFile	Evidence.ShippingDocumentation
Recipient.StripeDefaultCardId	Recipient.DefaultCardId
Recipient.StripeDefaultCard	Recipient.DefaultCard

Removals

• StripeList.TotalCount has been removed. This property was deprecated and is no longer returned by the API in nearly all cases.

• ValueList.Updated and ValueList.UpdatedBy have been removed. The API no longer returns these properties.

Constants are now static read-only properties

String constants (e.g. Event.ChargeCreated) are now declared as static read-only properties. For the most part, this requires no change on your part, save for switch statements. C# only accepts constant values in switch statements, so you will have to replace the various switch / case with if / else if to achieve the same effect.

New features

Auto-pagination

Stripe.net now supports auto-pagination.

Example usage:

var service = new BalanceTransactionService();
var listOptions = new BalanceTransactionListOptions
{
  Created = new DateRangeOptions
  {
    GreatherThanOrEqual = DateTime.Parse("2018-11-01T00:00:00Z"),
    LessThan = DateTime.Parse("2018-12-01T00:00:00Z"),
  },
  Limit = 100,
};

foreach (var balanceTransaction in service.ListAutoPaging(listOptions))
{
  // Do something with balanceTransaction
}

You can also use LINQ's ToList() method to convert the iterator to a list in memory (be careful when doing this though as this could take a long time depending on the number of items to fetch):

var service = new InvoiceService();
var lineItems = service.ListLineItemsAutoPaging("in_123").ToList();

ToJson() and ToString()

You can now call ToJson() on any instance of a StripeEntity to get a JSON representation of the object.

ToString() has also been overridden to be more useful and include more information, including the class name, a unique ID, and the JSON represensation.

SourceLink support

The library now supports SourceLink, which should improve your debugging experience.