1# V32 Migration Guide 2 3Version 32 of stripe-go contains some very sizable breaking changes. 4 5The major reason that we moved forward on them is that it was previously 6impossible when encoding a parameter struct for an API call to make a 7distinction between a field that a user had left unset versus a field that had 8been set explicitly, but to an empty value. So if we had a parameter struct 9like this: 10 11``` go 12type UsageRecordParams struct { 13 Quantity uint64 `form:"quantity"` 14} 15``` 16 17We were unable to differentiate these two cases: 18 19``` go 20// Initialized with no quantity 21UsageRecord {} 22 23// Initialized with an explicitly zero 24UsageRecord { 25 Quantity: 0, 26} 27``` 28 29This is because any uninitialized fields on a struct in Go are set to their 30type's "zero value", which for an integer is `0`. 31 32Working around the problem required a secondary field to help explicitly state 33that the zero value was intended, which was quite unintuitive for users: 34 35``` go 36type UsageRecordParams struct { 37 Quantity uint64 `form:"quantity"` 38 QuantityZero bool `form:"quantity,zero"` 39} 40 41UsageRecord { 42 QuantityZero: true, 43} 44``` 45 46To address the problem, we moved every parameter struct over to use pointers 47instead. So the above becomes: 48 49``` go 50type UsageRecordParams struct { 51 Quantity *int64 `form:"quantity"` 52} 53``` 54 55Because in Go you can't take the address of an inline value (`&0`), we provide 56a set of helper functions like `stripe.Int64` specifically for initializing 57these structs: 58 59``` go 60UsageRecord { 61 Quantity: stripe.Int64(0), 62} 63``` 64 65The zero value for pointers is `nil`, so we can now easily determine which 66values on a struct were never set, and which ones were explicitly set to a zero 67value, thus eliminating the need for the secondary fields like `QuantityZero`. 68 69Because this is a large change, we also took the opportunity to do some 70housekeeping throughout the library. Most of this involves renaming fields and 71some resources to be more accurate according to how they're named in Stripe's 72REST API, but it also involves some smaller changes like moving some types and 73constants around. 74 75Please see the list below for the complete set of changes. 76 77## Major changes 78 79* All fields on parameter structs (those that end with `*Params`) are now 80 pointers. Please use the new helper functions to set them: 81 * `stripe.Bool` 82 * `stripe.Float64` 83 * `stripe.Int64` 84 * `stripe.String` 85 86 This also means that extra fields that used to be solely used for tracking 87 meaningful zero values like `CouponEmpty` and `QuantityZero` have been 88 dropped. Use their corresponding field (e.g., `Coupon`, `Quantity`) with an 89 explicit empty value instead (`stripe.String("")`, `stripe.Int64(0)`). 90* Many fields have been renamed so that they're more consistent with their name 91 in Stripe's REST API. Most of the time, this changes abbreviations to a more 92 fully expanded form. For example: 93 * `Desc` becomes `Description`. 94 * `Live` becomes `Livemode`. 95* A few names of API resources (and their corresponding parameter and list 96 classes) have changed: 97 * `Fee` becomes `ApplicationFee`. 98 * `FeeRefund` becomes `ApplicationFeeRefund`. 99 * `Owner` becomes `AdditionalOwner`. 100 * `Sub` becomes `Subscription`. 101 * `SubItem` becomes `SubscriptionItem`. 102 * `Transaction` becomes `BalanceTransaction`. 103 * `TxFee` becomes `BalanceTransactionFee`. 104* Some sets of constants have been renamed and migrated to the top-level 105 `stripe` package. All constants now have a prefix according to what they 106 describe (for example, card brands all start with `CardBrand*` like 107 `CardBrandVisa`) and all now reside in the `stripe` package (for example 108 `dispute.Duplicate` is now `stripe.DisputeReasonDuplicate`). 109* Some structs that used to be shared between requests and responses are now 110 broken apart. All API calls should be using only structs that end with a 111 `*Params` suffix. So for example, if you were using `Address` or `DOB` 112 before, you should now use `AddressParams` and `DOBParams`. 113 114## Other changes 115 116* All integer values now use `int64` as their type. This means that the 117 `stripe.Int64` helper function is appropriate for setting all integer values. 118 This usually doesn't require a change because just setting these fields to a 119 numerical literal didn't require that the type be explicitly stated. 120* `Event.GetObjValue` becomes `Event.GetObjectValue` 121* `Params.AddMeta` becomes `Params.AddMetadata` 122* `Params.End` and `ListParams.End` become `EndingBefore`, and become a pointer 123 (use `stripe.String` to set them as with other parameters). 124* `Params.Expand` and `ListParams.Expand` (the fields) becomes a slice of 125 pointers (instead of a slice of strings). 126* `Params.Expand` and `ListParams.Expand` (the functions) become `AddExpand`. 127* `Params.IdempotencyKey` becomes a pointer. 128* `Params.Limit` becomes a pointer. 129* `Params.Meta` becomes `Params.Metadata` 130* `Params.Start` and `ListParams.Start` become `StartingAfter` 131* `Params.StripeAccount` and `ListParams.StripeAccount` become pointers. 132* List object data is now accessed with `object.Data` instead of `object.List`. 133 Nothing changes if you were using iterators and `Next`. 134* The previously deprecated `FileUploadParams.File` has been removed. Please 135 use `FileUploadParams.FileReader` instead. 136* The previously deprecated `Params.Account` has been removed. Please use 137 `Params.StripeAccount` instead. 138 139As usual, if you find bugs, please [open them on the repository][issues], or 140reach out to `support@stripe.com` if you have any other questions. 141 142[issues]: https://github.com/stripe/stripe-go/issues/new 143 144<!-- 145# vim: set tw=79: 146--> 147