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