Starting with v82.1, the new stripe.Client type is replacing client.API to provide a more ergonomic, consistent, and less error-prone experience. You create the former using stripe.NewClient(stripeKey). It’s almost a drop-in replacement, except for the differences listed below.

1. Service method names now align with Stripe API docs. The stripe.Client uses Create, Retrieve, Update, and Delete (instead of New, Get, Update, and Del).
2. The first argument of each service method is a context.Context.
3. Parameter objects are now method-specific. For example, CustomerCreateParams and CustomerDeleteParams instead of simply CustomerParams. This allows us to put the right fields in the right methods at compile time.
4. Services are all version-namespaced for symmetry. E.g. stripeClient.V1Accounts and stripeClient.V2Accounts.
5. List methods return an iter.Seq2, so they can be ranged over without explicit calls to Next, Current, and Err.

The new stripe.Client is almost, but not quite, a drop-in replacement for client.API. You create a new client using stripe.NewClient(apiKey). You can replace client.API construction with stripe.Client using this regex:

/client.New\((.*), nil\)/stripe.NewClient($1)/

Before

sc := client.New(env().StripeKey, nil)

After

sc := stripe.NewClient(env().StripeKey)

If you are passing in your own stripe.Backends into client.New, you pass them into the stripe.Client as follows

sc := stripe.NewClient(stripeKey, stripe.WithBackends(backends))

CRUD methods are now called Create, Retrieve, Update, and Delete

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
sc.Customers.New(params)

params := &stripe.CustomerCreateParams{...} 
sc.V1Customers.Create(context.TODO(), params)

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
sc.Customers.Get(params)

params := &stripe.CustomerRetrieveParams{...} 
sc.V1Customers.Retrieve(context.TODO(), params)

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
sc.Customers.Update(params)

params := &stripe.CustomerUpdateParams{...} 
sc.V1Customers.Update(context.TODO(), params)

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
sc.Customers.Del(params)

params := &stripe.CustomerDeleteParams{...} 
sc.V1Customers.Delete(context.TODO(), params)

OLD

i := sc.Customers.List(&stripe.CustomerListParams{})
for i.Next() {
	cust := i.Customer()
	// handle cust
}
if err := i.Err(); err != nil {
	// handle err
}

NEW

params := &stripe.CustomerListParams{}
for cust, err := range sc.V1Customers.List(context.TODO(), params) {
	// handle err
	// handle cust
}

All params are now method-specific. This prevents runtime errors where you pass the wrong params to the Stripe API.
Old

params := &stripe.CustomerParams{Name: stripe.String("Jenny Rosen")}
params.Context = context.TODO()
sc.Customers.Del("cus_123", params) // ❌ -- runtime error from Stripe: Name param not allowed

The general pattern is:

• Old: {resource_name}{subresource_names?}Params
• New: {resource_name}{method_name}{subresource_names?}Params

Old

params := &stripe.AppsSecretParams{
	Name:    stripe.String("sec_123"),
	Payload: stripe.String("very secret string"),
	Scope: &stripe.AppsSecretScopeParams{
		Type: stripe.String(stripe.AppsSecretScopeTypeAccount),
	},
}

New

params := &stripe.AppsSecretCreateParams{
	Name:    stripe.String("sec_123"),
	Payload: stripe.String("very secret string"),
	Scope: &stripe.AppsSecretCreateScopeParams{
		Type: stripe.String(stripe.AppsSecretScopeTypeAccount),
	},
}

In the global configuration pattern, instead of making calls to Stripe through a client, you set a global stripe.APIKey (as well as possibly other globally-configured options) and use package-level functions. For example:

stripe.APIKey = "sk_test_123"

cust, err := customer.New(params) // uses the global stripe.APIKey

Instead, to use stripe.Client, the above code would be written as:

sc := stripe.NewClient("sk_test_123")

cust, err := sc.V1Customers.Create(context.TODO(), params)

Each stripe.Client can be configured with a different API key, a different HTTP client, a different backend, etc., does not depend on global state, and is easy to mock/configure for testing. The global configuration pattern is not supported by new V2 APIs, and will eventually be deprecated.

The migration path is similar to that from client.API to stripe.Client. Here is how the CRUD methods change:

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
customer.New(params)

params := &stripe.CustomerCreateParams{...} 
sc.V1Customers.Create(context.TODO(), params)

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
customer.Get(params)

params := &stripe.CustomerRetrieveParams{...} 
sc.V1Customers.Retrieve(context.TODO(), params)

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
customer.Update(params)

params := &stripe.CustomerUpdateParams{...} 
sc.V1Customers.Update(context.TODO(), params)

params := &stripe.CustomerParams{...}
params.Context = context.TODO() 
customer.Del(params)

params := &stripe.CustomerDeleteParams{...} 
sc.V1Customers.Delete(context.TODO(), params)

And the list methods change as follows:

OLD

i := customer.List(&stripe.CustomerListParams{})
for i.Next() {
	cust := i.Customer()
	// handle cust
}
if err := i.Err(); err != nil {
	// handle err
}

NEW

params := &stripe.CustomerListParams{}
for cust, err := range sc.V1Customers.List(context.TODO(), params) {
	// handle err
	// handle cust
}