Migration guide for v46

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

Table of Contents

• Breaking changes
  • Removals
  • Reorganization
  • Behavior Changes

Breaking changes

Removals

Prior to v46, the SDK supported deriving a custom Service implementation to wrap preview or unsupported APIs. We've replaced this pattern with a standard interface to make custom requests to the Stripe API. To implement this change, you must create a StripeClient instance. Then you can change your code in the following way:

// before

class ThingService : Service<Thing> {
    ...
    public override string BasePath => "/v1/undocumented/things";

    public virtual Thing Create(ThingCreateOptions options, RequestOptions requestOptions = null)
    {
         return this.CreateEntity(options, requestOptions);
    }
    ...
}

// after


class ThingService { // no need to derive from Service<Thing>
    ...

    StripeClient stripeClient = new StripeClient("{{API_KEY}}");

    public virtual Thing Create(ThingCreateOptions options, RequestOptions requestOptions = null)
    {
        // represent options as a string: V1 APIs use form encoding, and V2 uses JSON
        var content = $"...";
        var response = stripeClient.RawRequest(HttpMethod.Post, "/v1/undocumented/things", content);
        return stripeClient.Deserialize<Thing>(response.Content);
    }
    ...
}

This change removes the following Service base class properties and methods. In all cases, you can replicate the functionality we used to provide with these properties and methods using the custom requests interface:

• The BasePath property and ClassUrl and InstanceUrl methods were removed.
• CreateEntity, DeleteEntity, GetEntity, ListEntities, ListEntitiesAutoPaging, UpdateEntity were removed.
• CreateEntityAsync, DeleteEntityAsync, GetEntityAsync, ListEntitiesAsync, ListEntitiesAutoPagingAsync, UpdateEntityAsync methods were removed.
• BaseUrl was removed.

Similar changes were made to the ServiceNested base class. If your integration relied on the following properties and methods, you can migrate your integration to use custom requests:

• ClassUrl and InstanceUrl were removed with no direct replacement.
• CreateNestedEntity, DeleteNestedEntity, GetNestedEntity, ListNestedEntities, ListNestedEntitiesAutoPaging, UpdateNestedEntity methods.
• CreateNestedEntityAsync, DeleteNestedEntityAsync, GetNestedEntityAsync, ListNestedEntitiesAsync, ListNestedEntitiesAutoPagingAsync, UpdateNestedEntityAsync method methods.

Reorganization

Renaming Stripe.Events to Stripe.EventTypes

The Stripe.Events class which exposes constants for event type strings has been renamed to Stripe.EventTypes to resolve a namespace collision with a new Stripe.Events namespace.

Renaming child services

Many child and nested services were reorganized so that they are more descriptive and discoverable.

The following services were renamed to be prefixed with the name of their parent service:

Old service name	New service name
CapabilityService	AccountCapabilityService
ExternalAccountService	AccountExternalAccountService
LoginLinkService	AccountLoginLinkService
PersonService	AccountPersonService
CashBalanceService	CustomerCashBalanceService
UsageRecordSummaryService	SubscriptionItemUsageRecordSummaryService
UsageRecordService	SubscriptionItemUsageRecordService

Renaming Options classes

Options classes used to pass API specific options into the above services have been prefixed with the parent service name, and some Options classes for child services have been changed so that the name of the service or resource (e.g. CustomerFundingInstructions) comes before the verb (e.g. Create, List). This affects the following classes:

Old name	New name
AccountListOwnersOptions	AccountOwnerListOptions
CalculationListLineItemsOptions	CalculationListLineItemsOptions
CapabilityGetOptions	AccountCapabilityGetOptions
CapabilityListOptions	AccountCapabilityListOptions
CapabilityUpdateOptions	AccountCapabilityUpdateOptions
CashBalanceGetOptions	CustomerCashBalanceGetOptions
CashBalanceUpdateOptions	CustomerCashBalanceUpdateOptions
CustomerBankTransferEuBankTransferOptions	CustomerFundingInstructionsBankTransferEuBankTransferOptions
CustomerBankTransferOptions	CustomerFundingInstructionsBankTransferOptions
CustomerCreateFundingInstructionsOptions	CustomerFundingInstructionsCreateOptions
CustomerListPaymentMethodsOptions	CustomerPaymentMethodListOptions
ExternalAccountCreateOptions	AccountExternalAccountCreateOptions
ExternalAccountDeleteOptions	AccountExternalAccountDeleteOptions
ExternalAccountDocumentsBankAccountOwnershipVerificationOptions	AccountExternalAccountDocumentsBankAccountOwnershipVerificationOptions
ExternalAccountDocumentsOptions	AccountExternalAccountDocumentsOptions
ExternalAccountGetOptions	AccountExternalAccountGetOptions
ExternalAccountListOptions	AccountExternalAccountListOptions
ExternalAccountUpdateOptions	AccountExternalAccountUpdateOptions
FinancialAccountRetrieveFeaturesOptions	FinancialAccountFeaturesGetOptions
FinancialAccountUpdateFeaturesOptions	FinancialAccountFeaturesUpdateOptions
LoginLinkCreateOptions	AccountLoginLinkCreateOptions
PersonAdditionalTosAcceptancesAccountOptions	AccountPersonAdditionalTosAcceptancesAccountOptions
PersonAdditionalTosAcceptancesOptions	AccountPersonAdditionalTosAcceptancesOptions
PersonCreateOptions	AccountPersonCreateOptions
PersonDeleteOptions	AccountPersonDeleteOptions
PersonDocumentsCompanyAuthorizationOptions	AccountPersonDocumentsCompanyAuthorizationOptions
PersonDocumentsOptions	AccountPersonDocumentsOptions
PersonDocumentsPassportOptions	AccountPersonDocumentsPassportOptions
PersonDocumentsVisaOptions	AccountPersonDocumentsVisaOptions
PersonGetOptions	AccountPersonGetOptions
PersonListOptions	AccountPersonListOptions
PersonRelationshipListOptions	AccountPersonRelationshipOptions
PersonRelationshipOptions	AccountPersonRelationshipOptions
PersonUpdateOptions	AccountPersonUpdateOptions
PersonVerificationAdditionalDocumentOptions	AccountPersonVerificationAdditionalDocumentOptions
PersonVerificationDocumentOptions	AccountPersonVerificationDocumentOptions
PersonVerificationOptions	AccountPersonVerificationOptions
QuoteListComputedUpfrontLineItemsOptions	QuoteComputedUpfrontLineItemsListOptions
QuoteListLineItemsOptions	QuoteLineItemListOptions
SessionListLineItemsOptions	SessionLineItemOptions
SourceTransactionsListOptions	SourceTransactionListOptions
TransactionListLineItemsOptions	TransactionLineItemListOptions
UpcomingInvoiceListLineItemsOptions	InvoiceUpcomingLinesListOptions
UsageRecordCreateOptions	SubscriptionItemUsageRecordCreateOptions

Separating child service methods into new services

Many nested child services were previously represented as special methods within a parent service. These methods have been moved into more descriptive, self-contained services. These services are called via new accessors on the parent service. Note that this release still contains the old methods (now marked obsolete) for backwards compatibility purposes, but we encourage users to migrate to the new service accessors if possible.

Old method	New accessor and method
CreditNoteService.ListPreviewLineItems	CreditNoteService.PreviewLines.List
CreditNoteService.ListPreviewLineItemsAsync	CreditNoteService.PreviewLines.ListAsync
CreditNoteService.ListPreviewLineItemsAutoPaging	CreditNoteService.PreviewLines.ListAutoPaging
CreditNoteService.ListPreviewLineItemsAutoPagingAsync	CreditNoteService.PreviewLines.ListAutoPagingAsync
CustomerService.CreateFundingInstructions	CustomerService.FundingInstructions.Create
CustomerService.CreateFundingInstructionsAsync	CustomerService.FundingInstructions.CreateAsync
CustomerService.ListPaymentMethods	CustomerService.PaymentMethods.List
CustomerService.ListPaymentMethodsAsync	CustomerService.PaymentMethods.ListAsync
CustomerService.ListPaymentMethodsAutoPaging	CustomerService.PaymentMethods.ListAutoPaging
CustomerService.ListPaymentMethodsAutoPagingAsync	CustomerService.PaymentMethods.ListAutoPagingAsync
CustomerService.RetrievePaymentMethod	CustomerService.PaymentMethods.Get
CustomerService.RetrievePaymentMethodAsync	CustomerService.PaymentMethods.GetAsync
FinancialConnections.AccountService.ListOwners	FinancialConnections.AccountService.Owners.List
FinancialConnections.AccountService.ListOwnersAsync	FinancialConnections.AccountService.Owners.ListAsync
FinancialConnections.AccountService.ListOwnersAutoPaging	FinancialConnections.AccountService.Owners.ListAutoPaging
FinancialConnections.AccountService.ListOwnersAutoPagingAsync	FinancialConnections.AccountService.Owners.ListAutoPagingAsync
InvoiceService.ListLineItems	InvoiceService.LineItems.List
InvoiceService.ListLineItemsAsync	InvoiceService.LineItems.ListAsync
InvoiceService.ListLineItemsAutoPaging	InvoiceService.LineItems.ListAutoPaging
InvoiceService.ListLineItemsAutoPagingAsync	InvoiceService.LineItems.ListAutoPagingAsync
InvoiceService.UpdateLines(string parentId, …)	InvoiceService.LineItems.Update
InvoiceService.UpdateLinesAsync(string parentId, …)	InvoiceService.LineItems.UpdateAsync
InvoiceService.ListUpcomingLineItems	InvoiceService.UpcomingLines.List
InvoiceService.ListUpcomingLineItemsAsync	InvoiceService.UpcomingLines.ListAsync
InvoiceService.ListUpcomingLineItemsAutoPaging	InvoiceService.UpcomingLines.ListAutoPaging
InvoiceService.ListUpcomingLineItemsAutoPagingAsync	InvoiceService.UpcomingLines.ListAutoPagingAsync
PaymentLinkService.ListLineItems	PaymentLinksService.LineItems.List
PaymentLinkService.ListLineItemsAsync	PaymentLinksService.LineItems.ListAsync
PaymentLinkService.ListLineItemsAutoPaging	PaymentLinksService.LineItems.ListAutoPaging
PaymentLinkService.ListLineItemsAutoPagingAsync	PaymentLinksService.LineItems.ListAutoPagingAsync
QuoteService.ListLineItems	QuoteService.LineItems.List
QuoteService.ListLineItemsAsync	QuoteService.LineItems.ListAsync
QuoteService.ListLineItemsAutoPaging	QuoteService.LineItems.ListAutoPaging
QuoteService.ListLineItemsAutoPagingAsync	QuoteService.LineItems.ListAutoPagingAsync
QuoteService.ListComputedUpfrontLineItems	QuoteService.ComputedUpfrontLineItems.List
QuoteService.ListComputedUpfrontLineItemsAsync	QuoteService.ComputedUpfrontLineItems.ListAsync
QuoteService.ListComputedUpfrontLineItemsAutoPaging	QuoteService.ComputedUpfrontLineItems.ListAutoPaging
QuoteService.ListComputedUpfrontLineItemsAutoPagingAsync	QuoteService.ComputedUpfrontLineItems.ListAutoPagingAsync
SessionService.ListLineItems	SessionService.LineItems.List
SessionService.ListLineItemsAsync	SessionService.LineItems.ListAsync
SessionService.ListLineItemsAutoPaging	SessionService.LineItems.ListAutoPaging
SessionService.ListLineItemsAutoPagingAsync	SessionService.LineItems.ListAutoPagingAsync
SourceService.Attach	CustomerService.PaymentSources.Create
SourceService.AttachAsync	CustomerService.PaymentSources.CreateAsync
SourceService.Detach	CustomerService.PaymentSources.Delete
SourceService.DetachAsync	CustomerService.PaymentSources.DeleteAsync
TaxIdService.Create(string parentId, …)	CustomerService.TaxIds.Create
TaxIdService.CreateAsync(string parentId, …)	CustomerService.TaxIds.CreateAsync
TaxIdService.Delete(string parentId, …)	CustomerService.TaxIds.Delete
TaxIdService.DeleteAsync(string parentId, …)	CustomerService.TaxIds.DeleteAsync
TaxIdService.Get(string parentId, …)	CustomerService.TaxIds.Get
TaxIdService.GetAsync(string parentId, …)	CustomerService.TaxIds.GetAsync
TaxIdService.List(string parentId, …)	CustomerService.TaxIds.List
TaxIdService.ListAsync(string parentId, …)	CustomerService.TaxIds.ListAsync
TaxIdService.ListAutoPaging(string parentId, …)	CustomerService.TaxIds.ListAutoPaging
TaxIdService.ListAutoPagingAsync(string parentId, …)	CustomerService.TaxIds.ListAutoPagingAsync
Tax.CalculationService.ListLineItems	Tax.CalculationService.LineItems.List
Tax.CalculationService.ListLineItemsAsync	Tax.CalculationService.LineItems.ListAsync
Tax.CalculationService.ListLineItemsAutoPaging	Tax.CalculationService.LineItems.ListAutoPaging
Tax.CalculationService.ListLineItemsAutoPagingAsync	Tax.CalculationService.LineItems.ListAutoPagingAsync
Tax.TransactionService.ListLineItems	Tax.TransactionService.LineItems.List
Tax.TransactionService.ListLineItemsAsync	Tax.TransactionService.LineItems.ListAsync
Tax.TransactionService.ListLineItemsAutoPaging	Tax.TransactionService.LineItems.ListAutoPaging
Tax.TransactionService.ListLineItemsAutoPagingAsync	Tax.TransactionService.LineItems.ListAutoPagingAsync
Treasury.FinancialAccountService.RetrieveFeatures	Treasury.FinancialAccountService.Features.List
Treasury.FinancialAccountService.RetrieveFeaturesAsync	Treasury.FinancialAccountService.Features.ListAsync
Treasury.FinancialAccountService.UpdateFeatures	Treasury.FinancialAccountService.Features.ListAutoPaging
Treasury.FinancialAccountService.UpdateFeaturesAsync	Treasury.FinancialAccountService.Features.ListAutoPagingAsync

Obsolete options types

In connection with separating the child service methods, the following option types are obsolete and will be removed in a future release.

• InvoiceListLineItemsOptions
• InvoiceUpdateInvoiceLineItemsOptions
• SourceTransactionsGetOptions

To migrate, switch to the new accessor and method listed above and use the new options type specified on that method.