Skip to content

Migration guide for v27

Jump to bottom
Olivier Bellone edited this page Jun 7, 2019 · 1 revision

Version 27 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 v27.

Table of Contents

Breaking changes

Changes to StripeConfiguration

  • The HttpMessageHandler and Timeout properties on StripeConfiguration are gone. In order to use custom message handlers or set other properties, you can now provide your own System.Net.HttpClient client instance (cf. Advanced client usage).

  • Similarly, the SetApiBase, SetConnectBase and SetFilesBase method on StripeConfiguration are gone. You can change the base URLs by creating a custom StripeClient instance (cf. Advanced client usage).

Polymorphic parameters

Previously, polymorphic parameters (i.e. request parameters that can be two or more different types) were represented in the library by different properties. For instance, the options class for most list requests had a Created property typed as DateTime and a CreatedRange property typed as DateRangeOptions, even though both properties are sent as created in the API request and only one of them should be set.

In v27, all polymorphic parameters are now represented by a single property that can transparently accept either type (e.g. Created on a list options class can now be either a DateTime or a DateRangeOptions). In addition, some properties that were set using a separate boolean property are now represented by enums.

Here is the list of properties that you'll need to rename in your code:

Class name Old property name New property name
*ListOptions CreatedRange Created
AccountCreateOptions ExternalAccountId ExternalAccount
AccountCreateOptions ExternalBankAccount ExternalAccount
AccountCreateOptions ExternalCardAccount ExternalAccount
AccountUpdateOptions ExternalAccountId ExternalAccount
AccountUpdateOptions ExternalBankAccount ExternalAccount
AccountUpdateOptions ExternalCardAccount ExternalAccount
BalanceTransactionListOptions AvailableOnRange AvailableOn
BankAccountCreateOptions SourceBankAccount Source
BankAccountCreateOptions SourceToken Source
CardCreateOptions SourceCard Source
CardCreateOptions SourceToken Source
ChargeCreateOptions SourceCard Source
ChargeCreateOptions SourceId Source
CustomerCreateOptions SourceCard Source
CustomerCreateOptions SourceToken Source
CustomerUpdateOptions SourceCard Source
CustomerUpdateOptions SourceToken Source
ExternalAccountCreateOptions ExternalAccountBankAccount ExternalAccount
ExternalAccountCreateOptions ExternalAccountTokenId ExternalAccount
InvoiceListOptions DueDateRange DueDate
OrderStatusTransitionsOptions CanceledRange Canceled
OrderStatusTransitionsOptions FulfilledRange Fulfilled
OrderStatusTransitionsOptions PaidRange Paid
OrderStatusTransitionsOptions ReturnedRange Returned
PayoutListOptions ArrivalDateRange ArrivalDate
PlanCreateOptions ProductId Product
SourceCreateOptions CardId Card
SubscriptionListOptions CurrentPeriodEndRange CurrentPeriodEnd
SubscriptionListOptions CurrentPeriodStartRange CurrentPeriodStart
SubscriptionScheduleListOptions CanceledAtRange CanceledAt
SubscriptionScheduleListOptions CompletedAtRange CompletedAt
SubscriptionScheduleListOptions ReleasedAtRange ReleasedAt
TaxRateListOptions PercentageRange Percentage
TokenCreateOptions BankAccountId BankAccount
TokenCreateOptions CardId Card

Here is the list of special property values that you'll need to update in your code:

Class name Old property name and value New property name and value
CustomerCreateOptions EndTrialNow = true TrialEnd = SubscriptionTrialEnd.Now
PlanTierOptions UpTo = new PlanTierOptions.UpToBound(123) UpTo = 123
PlanTierOptions UpTo = new PlanTierOptions.UpToInf() UpTo = PlanTierUpTo.Inf
SubscriptionCreateOptions EndTrialNow = true TrialEnd = SubscriptionTrialEnd.Now
SubscriptionUpdateOptions EndTrialNow = true TrialEnd = SubscriptionTrialEnd.Now
SubscriptionUpdateOptions BillingCycleAnchorNow = true BillingCycleAnchor = SubscriptionBillingCycleAnchor.Now
SubscriptionUpdateOptions BillingCycleAnchorUnchanged = true BillingCycleAnchor = SubscriptionBillingCycleAnchor.Unchanged
UpcomingInvoiceListLineItemsOptions SubscriptionBillingCycleAnchorNow = true SubscriptionBillingCycleAnchor = SubscriptionBillingCycleAnchor.Now
UpcomingInvoiceListLineItemsOptions SubscriptionBillingCycleAnchorUnchanged = true SubscriptionBillingCycleAnchor = SubscriptionBillingCycleAnchor.Unchanged
UpcomingInvoiceOptions SubscriptionBillingCycleAnchorNow = true SubscriptionBillingCycleAnchor = SubscriptionBillingCycleAnchor.Now
UpcomingInvoiceOptions SubscriptionBillingCycleAnchorUnchanged = true SubscriptionBillingCycleAnchor = SubscriptionBillingCycleAnchor.Unchanged

Removals

  • The Mapper class is gone. In order to deserialize resources, you can use either Entity.FromJson() or Newtonsoft.Json.JsonConvert.DeserializeObject<Entity>() (where Entity is any Stripe entity class, e.g. Charge or PaymentIntent).

  • The properties for the string and expanded versions of expandable fields (e.g. CustomerId and Customer on Charge) no longer have setters.

  • The Invoice and InvoiceChargeReason properties on PaymentIntentConfirmOptions are removed.

  • The PaymentIntentLastPaymentError class is removed.

Type changes

  • parent on order_item is now expandable. OrderItem.Parent is now a Sku. The ID is accessible via OrderItem.ParentId.

  • The Deauthorize and DeauthorizeAsync methods on OAuthService now accept a OAuthTokenDeauthorizeOptions instance instead of raw strings for the client ID and account ID.

  • PaymentIntent.LastPaymentError is now a StripeError.

  • Constant values are now once again declared as const instead of static. This makes them usable in switch statements.

Method signature changes

  • OAuthTokenService.Deauthorize and OAuthTokenService.DeauthorizeAsync now accept a OAuthTokenDeauthorizeOptions instance instead of passing the client ID and Stripe user ID as strings directly.

Name changes

  • The DuplicateChargeDocumentation property on DisputeEvidenceOptions is renamed to DuplicateChargeDocumentationFileId.

Upcoming deprecations

  • The SetApiKey method on StripeConfiguration is deprecated and has been replaced by the ApiKey property setter. Please update your code to use the property instead, as the method will be removed in a future major version.

  • RequestOptions.StripeConnectAccountId is deprecated in favor of RequestOptions.StripeAccount.

  • The ExpandX properties on services are deprecated in favor of BaseOptions.AddExpand. For instance, instead of doing this:

var invoiceService = new InvoiceService();
invoiceService.ExpandSubscription = true;
var invoice = invoiceService.Get("in_123");
// use expanded invoice.Subscription

you should now do this instead:

var invoiceService = new InvoiceService();
var options = new InvoiceGetOptions();
options.AddExpand("subscription");
var invoice = invoiceService.Get("in_123", options);
// use expanded invoice.Subscription

One advantage of this new method is that you can expand at more than one level, e.g. options.AddExpand("subscription.customer").

New features

Advanced client usage

The library now supports passing custom HTTP clients. This makes it easier to customize HTTP-related settings, or mock things out in tests. Please refer to the Advanced client usage wiki page for more information.

Automatic request retries

The library can now automatically retry certain failed requests (on timeouts, or if the API returns an unexpected error). This behavior is disabled by default. You can enable it by setting StripeConfiguration.MaxNetworkRetries to a non-zero value. We don't recommend setting this higher than 2 or 3.

See the Advanced client usage wiki page for an example of how to enable automatic request retries with a custom client.

Improved OAuth support

Support for OAuth has been improved. In particular, you can now use the OAuthTokenService.AuthorizeUrl() static method to form OAuth redirect URLs.

Clone this wiki locally