Stripe Go

https://github.com/stripe/stripe-go
Admin
The official Go client library for interacting with the Stripe API, enabling developers to process...
Tokens:740,399
Snippets:5,254
Trust Score:9.7
License:MIT
Update:3 days ago
Show doc for...
Tokens:
Raw
### Add beta version to go.mod

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Example go.mod require block for installing a public preview SDK version with a beta suffix. Replace the version placeholder with the desired version.

```go
require (
	...
	github.com/stripe/stripe-go/v87 <replace-with-the-version-of-your-choice>
	...
)
```

--------------------------------

### Update Search iteration to use .All(ctx)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Before and after examples for Search methods. The 'After' example adds .All(ctx) to the range expression.

```go
// Before
for customer, err := range client.V1Customers.Search(ctx, params) { ... }

// After
for customer, err := range client.V1Customers.Search(ctx, params).All(ctx) { ... }
```

--------------------------------

### Update callback-style iteration to use .All(ctx)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Before and after examples for the callback-style iteration pattern on older Go versions. The 'After' example adds .All(ctx) to the method call.

```go
// Before
client.V1Customers.List(ctx, params)(func(customer *stripe.Customer, err error) bool {
    // handle customer
    return true
})

// After
client.V1Customers.List(ctx, params).All(ctx)(func(customer *stripe.Customer, err error) bool {
    // handle customer
    return true
})
```

--------------------------------

### Global configuration pattern

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Example of the legacy pattern using package-level functions and global API key configuration.

```go
stripe.APIKey = "sk_test_123"

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

--------------------------------

### Stripe Client initialization

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Example of the modern pattern using stripe.NewClient to avoid global state.

```go
sc := stripe.NewClient("sk_test_123")

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

--------------------------------

### Update List iteration to use .All(ctx)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Before and after examples for auto-paginating List methods on stripe.Client services. The 'After' example adds .All(ctx) to the range expression to obtain the iterator.

```go
// Before
for customer, err := range client.V1Customers.List(ctx, params) {
    if err != nil {
        return err
    }
    fmt.Println(customer.ID)
}

// After
for customer, err := range client.V1Customers.List(ctx, params).All(ctx) {
    if err != nil {
        return err
    }
    fmt.Println(customer.ID)
}
```

--------------------------------

### Fetch Stripe Go with go get

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Alternatively, explicitly fetch the Stripe Go module into your project using this command.

```bash
go get -u github.com/stripe/stripe-go/v87
```

--------------------------------

### Method-specific parameter runtime error example

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

An example of the old pattern that could lead to runtime errors when passing incorrect parameters.

```go
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
```

--------------------------------

### Customer Create CRUD migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Migration example for creating a customer, moving from CustomerParams to CustomerCreateParams.

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

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

--------------------------------

### Fetch and run stripe-mock

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Commands to install and run stripe-mock, a dependency for testing the Stripe Go library. Run these in a background terminal.

```sh
go get -u github.com/stripe/stripe-mock
stripe-mock
```

--------------------------------

### Customer CRUD migration: Retrieve

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of the old package-level Get method and the new client-based Retrieve method.

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

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

--------------------------------

### Using stripe.Client to access Customer resource

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Recommended pattern for accessing Stripe resources. Setup with stripe.NewClient, then use sc.V1Customers for CRUD operations and sc.Customers.List for listing. Supports custom backends via stripe.WithBackends.

```go
import "github.com/stripe/stripe-go/v87"

// Setup
sc := stripe.NewClient("sk_key")
// To set backends, e.g. for testing, or to customize use this instead:
// sc := stripe.NewClient("sk_key", stripe.WithBackends(backends))

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

// Retrieve
c, err := sc.V1Customers.Retrieve(context.TODO(), id, &stripe.CustomerRetrieveParams{})

// Update
c, err := sc.V1Customers.Update(context.TODO(), id, &stripe.CustomerUpdateParams{})

// Delete
c, err := sc.V1Customers.Delete(context.TODO(), id, &stripe.CustomerDeleteParams{})

// List
for c, err := range sc.Customers.List(context.TODO(), &stripe.CustomerListParams{}) {
	// handle err
	// do something
}
```

--------------------------------

### Customer Update CRUD migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Migration example for updating a customer, moving from CustomerParams to CustomerUpdateParams.

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

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

--------------------------------

### Expanding Objects with AddExpand

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Shows the difference between retrieving a charge without expansion (only ID populated) and with expansion using AddExpand on parameter structs. The example uses ChargeCreateParams and Retrieve.

```go
//
// *Without* expansion
//
c, _ := sc.V1Charges.Retrieve(context.TODO(), "ch_123", nil)

c.Customer.ID    // Only ID is populated
c.Customer.Name  // All other fields are always empty

//
// With expansion
//
p := &stripe.ChargeCreateParams{}
p.AddExpand("customer")
c, _ = sc.V1Charges.Retrieve(context.TODO(), "ch_123", p)

c.Customer.ID    // ID is still available
c.Customer.Name  // Name is now also available (if it had a value)
```

--------------------------------

### Customer Retrieve CRUD migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Migration example for retrieving a customer, moving from CustomerParams to CustomerRetrieveParams.

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

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

--------------------------------

### Make custom raw request with rawrequest package

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Go function demonstrating how to send raw requests to undocumented or preview APIs using the rawrequest package. Shows both v2 (JSON) and v1 (form-encoded) request examples. Requires version 80 or later of the SDK.

```go
import (
	"encoding/json"
	"fmt"

	"github.com/stripe/stripe-go/v87"
	"github.com/stripe/stripe-go/v87/form"
	"github.com/stripe/stripe-go/v87/rawrequest"
)

func make_raw_request() error {
	stripe.Key = "sk_test_123"

	b, err := stripe.GetRawRequestBackend(stripe.APIBackend)
	if err != nil {
		return err
	}

	client := rawrequest.Client{B: b, Key: apiKey}

	payload := map[string]interface{}{
		"event_name": "hotdogs_eaten",
		"payload": map[string]string{
			"value":              "123",
			"stripe_customer_id": "cus_Quq8itmW58RMet",
		},
	}

	// for a v2 request, json encode the payload
	body, err := json.Marshal(payload)
	if err != nil {
		return err
	}

	v2_resp, err := client.RawRequest(http.MethodPost, "/v2/billing/meter_events", string(body), nil)
	if err != nil {
		return err
	}

	var v2_response map[string]interface{}
	err = json.Unmarshal(v2_resp.RawJSON, &v2_response)
	if err != nil {
		return err
	}
	fmt.Printf("%#v\n", v2_response)

	// for a v1 request, form encode the payload
	formValues := &form.Values{}
	form.AppendTo(formValues, payload)
	content := formValues.Encode()

	v1_resp, err := client.RawRequest(http.MethodPost, "/v1/billing/meter_events", content, nil)
	if err != nil {
		return err
	}

	var v1_response map[string]interface{}
	err = json.Unmarshal(v1_resp.RawJSON, &v1_response)
	if err != nil {
		return err
	}
	fmt.Printf("%#v\n", v1_response)

	return nil
}
```

--------------------------------

### Setting DefaultLeveledLogger for Global Logging

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Configure default logging by setting the global DefaultLeveledLogger variable. The example sets the level to LevelInfo.

```go
stripe.DefaultLeveledLogger = &stripe.LeveledLogger{
    Level: stripe.LevelInfo,
}
```

--------------------------------

### Customer Delete CRUD migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Migration example for deleting a customer, moving from CustomerParams to CustomerDeleteParams.

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

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

--------------------------------

### Configuring MaxNetworkRetries with BackendConfig

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Configure the number of automatic retries using MaxNetworkRetries in BackendConfig. The example sets zero retries. Idempotency keys are always added to requests.

```go
import (
	"github.com/stripe/stripe-go/v87"
)

config := &stripe.BackendConfig{
    MaxNetworkRetries: stripe.Int64(0), // Zero retries
}

backends := &stripe.NewBackendWithConfig(config)
sc := stripe.NewClient("sk_key", stripe.WithBackends(backends))
coupon, err := sc.V1Coupons.Create(...)
```

--------------------------------

### Access RawJSON while iterating List results

Source: https://github.com/stripe/stripe-go/blob/master/README.md

For List and Search operations, access each resource's RawJSON as you iterate. The example logs the raw JSON for each customer.

```go
for cust, err := range sc.V1Customers.List(context.TODO(), &stripe.CustomerListParams{}) {
    if err != nil {
        return err
    }
    customerJSON := cust.LastResponse.RawJSON
    log.Printf("Customer JSON: %s", customerJSON) // {"id":"cus_123",...}
}
```

--------------------------------

### Generate and construct a signed webhook payload

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Use stripe.GenerateTestSignedPayload to mock webhook events and stripe.ConstructEvent to validate them. The example shows how to create a signed payload and verify the event ID.

```go
payload := map[string]interface{}{
	"id":          "evt_test_webhook",
	"object":      "event",
	"api_version": stripe.APIVersion,
}
testSecret := "whsec_test_secret"

payloadBytes, err := json.Marshal(payload)

signedPayload := stripe.GenerateTestSignedPayload(&webhook.UnsignedPayload{Payload: payloadBytes, Secret: testSecret})
event, err := stripe.ConstructEvent(signedPayload.Payload, signedPayload.Header, signedPayload.Secret)

if event.ID == payload["id"] {
	// Do something with the mocked signed event
} else {
	// Handle invalid event payload
}
```

--------------------------------

### Client creation with backends

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

How to pass custom backends when initializing the new stripe.Client.

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

--------------------------------

### Client creation migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of the old client initialization versus the new stripe.NewClient approach.

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

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

--------------------------------

### Customer CRUD migration: Create

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of the old package-level Create method and the new client-based Create method.

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

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

--------------------------------

### Initialize Go module

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Run this command to create a go.mod file in your project root, which is required before using the Stripe Go library.

```sh
go mod init
```

--------------------------------

### Setting V2 decimal params before v85

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Shows the previous implementation where PercentOwnership required a string pointer.

```go
pct := "75.25"
params := &stripe.V2CoreAccountCreateParams{
    Identity: &stripe.V2CoreAccountCreateIdentityParams{
        Individual: &stripe.V2CoreAccountCreateIdentityIndividualParams{
            Relationship: &stripe.V2CoreAccountCreateIdentityIndividualRelationshipParams{
                PercentOwnership: &pct,  // was *string
            },
        },
    },
}
```

--------------------------------

### Create a Customer with stripe-go

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Creates a new customer using the Stripe Go client. Requires an API key and sets description, email, and preferred locales.

```go
sc := stripe.NewClient(apiKey)
params := &stripe.CustomerCreateParams{
	Description:      stripe.String("Stripe Developer"),
	Email:            stripe.String("gostripe@stripe.com"),
	PreferredLocales: stripe.StringSlice([]string{"en", "es"}),
}

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

--------------------------------

### Run all tests with just or go test

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Runs the full test suite. The just command is preferred; the go test equivalent is provided.

```sh
just test
# or: go test ./...
```

--------------------------------

### Authenticate with Connect Using Account Keys

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Creates a Stripe client using an access token for a connected account. This is an alternative to using the Stripe-Account header.

```go
import (
	"github.com/stripe/stripe-go/v87"
)

sc := stripe.NewClient("access_token")
```

--------------------------------

### Use Backend mock to test Stripe client

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Go test function that initializes a Stripe client with a mocked backend, sets up an expected call, and verifies the result. Requires the generated mock and dependencies like gomock and testify.

```go
import (
	"example/hello/mocks"
	"testing"

	"github.com/golang/mock/gomock"
	"github.com/stretchr/testify/assert"
	"github.com/stripe/stripe-go/v87"
)

func UseMockedStripeClient(t *testing.T) {
	// Create a mock controller
	mockCtrl := gomock.NewController(t)
	defer mockCtrl.Finish()
	// Create a mock stripe backend
	mockBackend := mocks.NewMockBackend(mockCtrl)
	backends := &stripe.Backends{API: mockBackend}
	client := stripe.NewClient("sk_test", stripe.WithBackends(backends))

	// Set up a mock call
	mockBackend.EXPECT().Call("GET", "/v1/accounts/acc_123", gomock.Any(), gomock.Any(), gomock.Any()).
		// Return nil error
		Return(nil).
		Do(func(method string, path string, key string, params stripe.ParamsContainer, v *stripe.Account) {
			// Set the return value for the method
			*v = stripe.Account{
				ID: "acc_123",
			}
		}).Times(1)

	// Call the client method
	acc, _ := client.V1Accounts.GetByID(context.TODO(), "acc_123", nil)

	// Asset the result
	assert.Equal(t, "acc_123", acc.ID)
}
```

--------------------------------

### Metadata and Expand parameters after v75

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v75

Shows the updated way of setting Metadata and Expand fields directly on the Params class.

```go
params := &stripe.AccountParams{
          Expand: []*string{stripe.String("business_profile")},
          Metadata: map[string]string{
                    "order_id": "6735",
          },
}
```

--------------------------------

### Customer list iteration: New pattern

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

The modern way of iterating through a list of customers using the client and the All method.

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

--------------------------------

### AddMetadata and AddExpand usage

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v75

Demonstrates that calls to AddMetadata and AddExpand remain unchanged in v75.

```go
params.AddMetadata("order_id", "6735") 
params.AddExpand("business_profile")
```

--------------------------------

### Run a single test

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Runs a single test by name, e.g., TestInvoiceGet in the ./invoice package. The just command is preferred; the go test equivalent is provided.

```sh
just test ./invoice -run TestInvoiceGet
# or: go test ./invoice -run TestInvoiceGet
```

--------------------------------

### Legacy resource pattern without a client

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Legacy pattern using package-level functions like customer.New and customer.Get. Requires setting stripe.Key. Does not support V2 APIs. Marked for deprecation.

```go
import (
	"github.com/stripe/stripe-go/v87"
	"github.com/stripe/stripe-go/v87/customer"
)

// Setup
stripe.Key = "sk_key"

// Set backend (optional, useful for mocking)
// stripe.SetBackend("api", backend)

// Create
c, err := customer.New(&stripe.CustomerParams{})

// Get
c, err := customer.Get(id, &stripe.CustomerParams{})

// Update
c, err := customer.Update(id, &stripe.CustomerParams{})

// Delete
c, err := customer.Del(id, &stripe.CustomerParams{})

// List
i := customer.List(&stripe.CustomerListParams{})
for i.Next() {
	c := i.Customer()
	// do something
}

if err := i.Err(); err != nil {
	// handle
}
```

--------------------------------

### Setting V2 decimal params after v85

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Shows the updated implementation where PercentOwnership now uses a float64 pointer.

```go
pct := 75.25
params := &stripe.V2CoreAccountCreateParams{
    Identity: &stripe.V2CoreAccountCreateIdentityParams{
        Individual: &stripe.V2CoreAccountCreateIdentityIndividualParams{
            Relationship: &stripe.V2CoreAccountCreateIdentityIndividualRelationshipParams{
                PercentOwnership: &pct,  // now *float64
            },
        },
    },
}
```

--------------------------------

### Import Stripe Go packages

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Add these import statements to your Go program to use the Stripe client and customer package.

```go
import (
	"github.com/stripe/stripe-go/v87"
	"github.com/stripe/stripe-go/v87/customer"
)
```

--------------------------------

### Read response values with decimal methods

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v87

Use decimal methods like Equal and String instead of converting response values to float64. The package also provides arithmetic and rounding methods.

```go
expected := decimal.RequireFromString("0.0123456789")
if price.UnitAmountDecimal.Equal(expected) {
	fmt.Println(price.UnitAmountDecimal.String())
}
```

--------------------------------

### Run tests for one package

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Runs tests for a specific package, e.g., ./invoice. The just command is preferred; the go test equivalent is provided.

```sh
just test ./invoice
# or: go test ./invoice
```

--------------------------------

### Reading V2 decimal responses before v85

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Shows the previous method of reading decimal fields, which required manual parsing from a string.

```go
pctStr := *account.Identity.Individual.Relationship.PercentOwnership  // string
pct, _ := strconv.ParseFloat(pctStr, 64)
```

--------------------------------

### Regex for client.New to stripe.NewClient migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

A regex pattern to assist in replacing the old client.New constructor with the new stripe.NewClient.

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

--------------------------------

### Customer CRUD migration: Update

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of the old package-level Update method and the new client-based Update method.

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

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

--------------------------------

### List methods migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of the old iterator-based list pattern versus the new range-based iteration.

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

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

--------------------------------

### Add beta version header with stripe.AddBetaVersion

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Go code to set a beta version in the Stripe-Version header for preview features that require it. Only available in public preview SDKs.

```go
stripe.AddBetaVersion("feature_beta", "v3")
```

--------------------------------

### Identify a plugin with SetAppInfo

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Call stripe.SetAppInfo to identify your plugin when using the library. Name is required; URL and Version are optional.

```go
stripe.SetAppInfo(&stripe.AppInfo{
	Name:    "MyAwesomePlugin",
	URL:     "https://myawesomeplugin.info",
	Version: "1.2.34",
})
```

--------------------------------

### AppsSecret parameter migration

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of old generic AppsSecretParams versus new method-specific AppsSecretCreateParams.

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

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

--------------------------------

### Create a Per-Request Stripe Client in Google AppEngine

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Creates a Stripe client with a custom HTTP client for Google AppEngine, since the default client is not available. The handler creates a customer and writes the result to the response.

```go
import (
	"fmt"
	"net/http"

	"google.golang.org/appengine"
	"google.golang.org/appengine/urlfetch"

	"github.com/stripe/stripe-go/v87"
)

func handler(w http.ResponseWriter, r *http.Request) {
	ctx := appengine.NewContext(r)
	httpClient := urlfetch.Client(ctx)

	backends := stripe.NewBackends(httpClient)
	sc := stripe.NewClient("sk_test_123", stripe.WithBackends(backends))

	params := &stripe.CustomerCreateParams{
		Description: stripe.String("Stripe Developer"),
		Email:       stripe.String("gostripe@stripe.com"),
	}
	customer, err := sc.V1Customers.Create(ctx, params)
	if err != nil {
		fmt.Fprintf(w, "Could not create customer: %v", err)
		return
	}
	fmt.Fprintf(w, "Customer created: %v", customer.ID)
}
```

--------------------------------

### Accessing Amount fields before and after v85

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Demonstrates the transition from specific per-field types to the shared stripe.Amount type when accessing monetary properties.

```go
// Before
// amount was *stripe.V2CoreAccountIdentityBusinessDetailsAnnualRevenue
Amount
amount := account.Identity.BusinessDetails.AnnualRevenue.Amount
fmt.Println(amount.Value)    // int64
fmt.Println(amount.Currency) // stripe.Currency

// After
// amount is now *stripe.Amount
amount := account.Identity.BusinessDetails.AnnualRevenue.Amount
fmt.Println(amount.Value)    // int64
fmt.Println(amount.Currency) // stripe.Currency
```

--------------------------------

### Customer list iteration: Old pattern

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

The legacy way of iterating through a list of customers using an iterator.

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

--------------------------------

### Metadata and Expand parameters before v75

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v75

Shows the deprecated way of setting Metadata and Expand fields by nesting them within the embedded Params struct.

```go
params := &stripe.AccountParams{
          Params: stripe.Params{
            Expand: []*string{stripe.String("business_profile")},
            Metadata: map[string]string{
              "order_id": "6735",
            },
          },
}
```

--------------------------------

### Generate Backend mock with mockgen

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Command to generate a mock for the Stripe Backend interface using GoMock. Run this before using the mock in unit tests.

```bash
mockgen -destination=mocks/backend.go -package=mocks github.com/stripe/stripe-go/v87 Backend
```

--------------------------------

### Access per-page data from V1List struct

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Shows how to access Data, Meta, Err, and LastResponse from the V1List struct returned by List methods.

```go
list := client.V1Customers.List(ctx, params)

data := list.Data()          // []*stripe.Customer for the current page
meta := list.Meta()          // stripe.ListMeta — includes HasMore
err := list.Err()            // error from fetching the current page
resp := list.LastResponse()  // *stripe.APIResponse with RawJSON
```

--------------------------------

### List Events with stripe-go

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Lists all events using the Stripe Go client. Shows how to access event data and previous attributes using helper methods or direct map access.

```go
sc := stripe.NewClient(apiKey)
for e, err := range sc.V1Events.List(context.TODO(), nil) {
	// access event data via e.GetObjectValue("resource_name_based_on_type", "resource_property_name")
	// alternatively you can access values via e.Data.Object["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]

	// access previous attributes via e.GetPreviousValue("resource_name_based_on_type", "resource_property_name")
	// alternatively you can access values via e.Data.PreviousAttributes["resource_name_based_on_type"].(map[string]interface{})["resource_property_name"]
}
```

--------------------------------

### Update request values with decimal.Decimal (v87)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v87

In v87, parse input with decimal.NewFromString and use stripe.Pointer for nullable fields. Requires importing github.com/shopspring/decimal and github.com/stripe/stripe-go/v87.

```go
import (
	"github.com/shopspring/decimal"
	"github.com/stripe/stripe-go/v87"
)

value, err := decimal.NewFromString(input)
if err != nil {
	return err
}
params := &stripe.PriceParams{
	UnitAmountDecimal: stripe.Pointer(value),
}
```

--------------------------------

### Set beta header per request

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Set a beta header on a per-request basis using the Params.Headers field. This is needed for private preview features when using a release version like v83.1.0.

```go
params := &stripe.CustomerCreateParams{
	...
	Params: stripe.Params{
		Headers: http.Header{
			"Stripe-Version": []string{"2025-10-29.preview; beta_feature_1=v3; beta_feature_2=v1"},
		},
	},
}
```

--------------------------------

### Reading V2 decimal responses after v85

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Shows the updated method of reading decimal fields, which now returns a float64 directly.

```go
pct := account.Identity.Individual.Relationship.PercentOwnership  // float64
fmt.Println(pct)  // 75.25
```

--------------------------------

### stripe-go v70 import paths without major version

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Shows the import paths used before v71, without a major version. Needed to understand the required change.

```go
import (
    "github.com/stripe/stripe-go"
    "github.com/stripe/stripe-go/customer"
)
```

--------------------------------

### Update PlanParams ProductID to Product.ID

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v73

The PlanParams.ProductID field has been removed. Use the nested PlanParams.Product.ID field instead.

```go
// Before
params := &stripe.PlanParams{
  ProductID: stripe.String("prod_12345abc"),
}

// After
params := &stripe.PlanParams{
  Product: &stripe.PlanProductParams{
    ID:                  stripe.String("plan_id"),
  },
}
```

--------------------------------

### Update AccountParams to use Capabilities instead of RequestedCapabilities

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v73

Shows the before and after for replacing the removed RequestedCapabilities field with the Capabilities struct. The after version uses AccountCapabilitiesParams with CardPayments and Requested set to true.

```go
// Before
params := &stripe.AccountParams{
  RequestedCapabilities: ["card_payments"],
}

// After
params := &stripe.AccountParams{
  Capabilities: &stripe.AccountCapabilitiesParams{
      CardPayments: &stripe.AccountCapabilitiesCardPaymentsParams{
          Requested: stripe.Bool(true),
      },
  },
}
```

--------------------------------

### Customer CRUD migration: Delete

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-Stripe-Client

Comparison of the old package-level Del method and the new client-based Delete method.

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

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

--------------------------------

### Set Stripe-Account Header for Connect

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Sets the Stripe-Account header on a list request to authenticate on behalf of a connected account. This is the recommended approach for Connect authentication.

```go
// For a list request
listParams := &stripe.CustomerListParams{}
listParams.SetStripeAccount("acct_123")
```

--------------------------------

### Update request values with *float64 (before v87)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v87

Shows the pre-v87 pattern for decimal request fields using *float64. Parse input with strconv.ParseFloat and assign with stripe.Float64.

```go
value, err := strconv.ParseFloat(input, 64)
if err != nil {
	return err
}
params := &stripe.PriceParams{
	UnitAmountDecimal: stripe.Float64(value),
}
```

--------------------------------

### Use decimal.RequireFromString for fixed values

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v87

For fixed values where invalid input should be a programming error, use decimal.RequireFromString instead of handling errors.

```go
params := &stripe.PriceParams{
	UnitAmountDecimal: stripe.Pointer(decimal.RequireFromString("0.0123456789")),
}
```

--------------------------------

### Set MaxNetworkRetries with stripe.Int64 helper

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Use the stripe.Int64 helper to set MaxNetworkRetries on a BackendConfig. This is necessary because the field now takes a *int64 pointer, allowing the library to distinguish between an unset value and an explicit zero.

```go
config := &stripe.BackendConfig{
    MaxNetworkRetries: stripe.Int64(2),
}
```

--------------------------------

### Opt-out of API version mismatch with ConstructEventWithOptions (Tolerance)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v73

Opt-out of the new API version mismatch error for webhook events when previously using ConstructEventWithTolerance. Set Tolerance to the desired value and IgnoreAPIVersionMismatch to false.

```go
ConstructEventWithOptions(payload, header, secret, ConstructEventOptions{Tolerance: tolerance, IgnoreAPIVersionMismatch: false})
```

--------------------------------

### stripe-go v71 import paths with major version

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Shows the required import paths for stripe-go v71, which include the major version /v71 in the import path. This change applies to all imports and the Go toolchain will automatically fetch the module.

```go
import (
    "github.com/stripe/stripe-go/v71"
    "github.com/stripe/stripe-go/v71/customer"
)
```

--------------------------------

### Opt-out of API version mismatch with ConstructEventWithOptions (IgnoreTolerance)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v73

Opt-out of the new API version mismatch error for webhook events when previously using ConstructEventIgnoringTolerance. Set IgnoreTolerance to true and IgnoreAPIVersionMismatch to false.

```go
ConstructEventWithOptions(payload, header, secret, ConstructEventOptions{IgnoreTolerance: true, IgnoreAPIVersionMismatch: false})
```

--------------------------------

### List Payment Intents for a Customer

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Lists payment intents for a specific customer using the Stripe Go client. The loop iterates over the results and handles errors.

```go
sc := stripe.NewClient(apiKey)
params := &stripe.PaymentIntentListParams{
	Customer: stripe.String(customer.ID),
}

for pi, err := range sc.V1PaymentIntents.List(context.TODO(), params) {
	// handle err
	// do something
}
```

--------------------------------

### Clear fields with AddExtra (Before v85)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

The previous method for clearing fields in V1 requests using AddExtra.

```go
params := &stripe.SubscriptionUpdateParams{}
params.AddExtra("pause_collection", "")
```

--------------------------------

### Disable retries by setting MaxNetworkRetries to 0

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

To revert to the previous behavior of no retries, set MaxNetworkRetries to stripe.Int64(0). The library now retries intermittently failed requests up to two times by default.

```go
config := &stripe.BackendConfig{
    MaxNetworkRetries: stripe.Int64(0), // Zero retries
}
```

--------------------------------

### LeveledLoggerInterface Definition

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Stripe expects loggers to comply with this interface. Logrus and Zap's SugaredLogger support it out-of-the-box; others may need a shim.

```go
type LeveledLoggerInterface interface {
	Debugf(format string, v ...interface{})
	Errorf(format string, v ...interface{})
	Infof(format string, v ...interface{})
	Warnf(format string, v ...interface{})
}
```

--------------------------------

### Referencing the Amount type directly

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Shows the change in type declaration when referencing the Amount type directly in code.

```go
// Before
var amt *stripe.V2CoreAccountIdentityBusinessDetailsAnnualRevenueAmount

// After
var amt *stripe.Amount
```

--------------------------------

### Set LeveledLogger on BackendConfig

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Alternatively, set the LeveledLogger explicitly on a BackendConfig to override the default logger for that specific backend configuration.

```go
config := &stripe.BackendConfig{
    LeveledLogger: &stripe.LeveledLogger{
        Level: stripe.LevelDebug,
    },
}
```

--------------------------------

### Set DefaultLeveledLogger for global logging

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Replace the deprecated stripe.LogLevel and stripe.Logger variables by setting stripe.DefaultLeveledLogger to a new LeveledLogger instance. This configures the default logger used by the library.

```go
stripe.DefaultLeveledLogger = &stripe.LeveledLogger{
    Level: stripe.LevelDebug,
}
```

--------------------------------

### Clear map entries with pointer values

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

Demonstrates clearing individual map entries by setting the pointer value to nil.

```go
params := &stripe.BalanceSettingsUpdateParams{
    Payments: &stripe.BalanceSettingsUpdatePaymentsParams{
        Payouts: &stripe.BalanceSettingsUpdatePaymentsPayoutsParams{
            MinimumBalanceByCurrency: map[string]*int64{
                "usd": stripe.Int64(5000),
                // To clear a currency's minimum balance:
                "eur": nil
            },
        },
    },
}
```

--------------------------------

### Update CheckoutSessionListLineItemsParams to use Session field

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v73

Shows the before and after for replacing the removed id parameter with the Session field in CheckoutSessionListLineItemsParams. The after version passes the session ID as a string parameter.

```go
// Before
params := &stripe.CheckoutSessionListLineItemsParams{}
i := ListLineItems("cs_123", params)

// After
params := &stripe.CheckoutSessionListLineItemsParams{Session: stripe.String("cs_123")}
i := ListLineItems(params)
```

--------------------------------

### Disable telemetry

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Disable telemetry by setting EnableTelemetry to false in the BackendConfig. Telemetry is enabled by default.

```go
config := &stripe.BackendConfig{
	EnableTelemetry: stripe.Bool(false),
}
```

--------------------------------

### Clear fields with AddUnsetField (v85+)

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v85

The new mechanism for explicitly clearing scalar fields using AddUnsetField and typed constants.

```go
params := &stripe.SubscriptionUpdateParams{}
params.AddUnsetField(stripe.SubscriptionUpdateParamsUnsetFieldPauseCollection)
```

--------------------------------

### Access LastResponse RequestID

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Shows how to access the RequestID from the LastResponse field of a customer resource after creating it. Note that LastResponse is only populated for the top-level API resource returned, not for nested resources like invoice items.

```go
customer, err := customer.New(params)
fmt.Printf("request ID = %s\n", customer.LastResponse.RequestID)
```

--------------------------------

### APIResponse struct definition

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Defines the APIResponse struct that is embedded in LastResponse. It includes fields for HTTP headers, idempotency key, raw JSON body, request ID, status, and status code.

```go
// APIResponse encapsulates some common features of a response from the
// Stripe API.
type APIResponse struct {
	// Header contain a map of all HTTP header keys to values. Its behavior and
	// caveats are identical to that of http.Header.
	Header http.Header

	// IdempotencyKey contains the idempotency key used with this request.
	// Idempotency keys are a Stripe-specific concept that helps guarantee that
	// requests that fail and need to be retried are not duplicated.
	IdempotencyKey string

	// RawJSON contains the response body as raw bytes.
	RawJSON []byte

	// RequestID contains a string that uniquely identifies the Stripe request.
	// Used for debugging or support purposes.
	RequestID string

	// Status is a status code and message. e.g. "200 OK"
	Status string

	// StatusCode is a status code as integer. e.g. 200
	StatusCode int
}
```

--------------------------------

### Pass undocumented parameters with AddExtra

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Use the AddExtra() method on request params to pass undocumented parameters to Stripe. This is needed for private preview features that lack typed accessors.

```go
params := &stripe.CustomerCreateParams{
	Email: stripe.String("jenny.rosen@example.com")
}
params.AddExtra("secret_feature_enabled", "true")
params.AddExtra("secret_parameter[primary]","primary value")
params.AddExtra("secret_parameter[secondary]","secondary value")

customer, err := sc.V1Customer.Create(context.TODO(), params)
```

--------------------------------

### Set default logger to informational level in stripe-go

Source: https://github.com/stripe/stripe-go/wiki/Migration-guide-for-v71

Use this snippet to revert the default logging behavior in stripe-go v7.1 to log informational messages in addition to errors. This is necessary if you want to restore the previous logging behavior that showed both errors and informational messages.

```go
stripe.DefaultLeveledLogger = &stripe.LeveledLogger{
    Level: stripe.LevelInfo,
}
```

--------------------------------

### Accessing LastResponse on an APIResource

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Use LastResponse on any APIResource to inspect the API response that generated the object. Only the top-level resource's LastResponse is set for nested resources.

```go
coupon, err := sc.V1Coupons.Create(...)
requestID := coupon.LastResponse.RequestID
```

--------------------------------

### Access undocumented properties from raw JSON

Source: https://github.com/stripe/stripe-go/blob/master/README.md

Query the raw response JSON to access undocumented properties returned by Stripe. Unmarshal customer.LastResponse.RawJSON into a map and extract values with type assertions.

```go
customer, _ = sc.V1Charges.Retrieve(context.TODO(), "cus_1234", nil);

var rawData map[string]interface{}
_ = json.Unmarshal(customer.LastResponse.RawJSON, &rawData)

secretFeatureEnabled, _ := string(rawData["secret_feature_enabled"].(bool))

secretParameter, ok := rawData["secret_parameter"].(map[string]interface{})
if ok {
	primary := secretParameter["primary"].(string)
	secondary := secretParameter["secondary"].(string)
}
```
Tokens:
Raw