Versioning API Stripe: cara kerjanya dan apa yang ditiru

Versioning API Stripe bekerja berdasarkan tanggal. Setiap akun dikunci ke versi API yang dinamai menurut tanggal rilis, dan satu request mana pun bisa menimpa kunci itu dengan header Stripe-Version. Saat artikel ini ditulis (Oktober 2026), versi terkini di dokumentasi Stripe adalah 2026-09-30.endive, dan skema yang sama bisa ditiru API yang jauh lebih kecil dalam satu akhir pekan.

Setiap fakta tentang Stripe di bawah berasal dari halaman Stripe sendiri, ditautkan di tempat dipakai.

Bagaimana versioning API Stripe bekerja?

Stripe memberi setiap akun versi API default, dan setiap request yang tidak menyebut versi memakai versi itu. Pemanggil memilih kapan berpindah, dengan mengubah default atau mengatur versi pada request tertentu.

Engineering post Stripe menyatakan akun dikunci saat pertama kali membuat request API: akun itu “automatically pinned to the most recent version available”, dan sejak itu setiap panggilan secara implisit diberi versi tersebut.

String versinya adalah tanggal. Sejak rilis 2024-09-30.acacia, string itu juga membawa nama, seperti 2026-09-30.endive. Tanggal mengurutkan versi, dan nama memberi tahu keluarga rilis mayor mana yang dimiliki sebuah versi.

Bagaimana memilih versi per request?

Kirim header Stripe-Version pada request, atau atur versi di SDK. Panduan upgrade Stripe menunjukkan bentuk header, dan panggilan yang sama berfungsi di lingkungan live maupun test.

curl https://api.stripe.com/v1/charges \
  -u "$STRIPE_SECRET_KEY:" \
  -H "Stripe-Version: 2026-09-30.endive"

Panduan Stripe mencatat bahwa ketika Anda mengatur versi secara global atau per request di SDK, objek respons kembali dalam versi itu.

Stripe juga menyarankan agar tidak bersandar pada default akun. Dengan kata-katanya, tentukan versi untuk setiap request, dengan header atau SDK yang dikunci, agar kode Anda yang memutuskan versinya dan bukan pengaturan di dasbor.

SDK mengunci dengan cara berbeda per bahasa. Dokumentasi menyatakan versi terbaru dari pustaka berbahasa dinamis memakai versi API yang paling baru saat rilis SDK itu terbit, sedangkan yang bertipe kuat (Java, Go, dan .NET) terkunci padanya. Memasang versi pustaka pada dasarnya adalah memilih versi API.

Apa yang terjadi pada webhook ketika versi berubah?

Event webhook dirender dalam versi API yang melekat pada endpoint-nya, bukan versi yang dipakai kode server Anda. Dokumentasi Stripe menyatakan event memakai versi yang diatur saat endpoint dibuat, dan selain itu default akun. Mengubah versi SDK tidak mengubah apa yang diterima handler webhook Anda.

Jalur request dan jalur event Anda karena itu bisa berada pada dua versi berbeda. Untuk event destination, Anda mengatur snapshot_api_version hanya saat membuat destination, jadi versi yang berbeda berarti destination baru.

Jalur upgrade Stripe untuk ini adalah menjalankan secara paralel. Buat endpoint baru pada versi target, kirim event yang sama ke keduanya, ajari handler memproses satu dan mengabaikan yang lain, lalu beralih dan nonaktifkan endpoint lama. Karena setiap event tiba dua kali selama tumpang tindih, handler harus idempoten. Itu pola yang bagus untuk ditiru bagi API apa pun yang memancarkan event, dan changelog webhook adalah tempat Anda mengumumkan perubahan payload yang membuatnya diperlukan.

Apa itu rilis bulanan dan rilis mayor?

Sejak rilis 2024-09-30.acacia, Stripe merilis versi API baru setiap bulan tanpa breaking change, dan menerbitkan rilis mayor baru dua kali setahun yang dimulai dengan versi berisi breaking change. Halaman versioning-nya menyatakan Anda bisa upgrade ke rilis bulanan mana pun tanpa memperbarui kode, sedangkan rilis mayor bisa membutuhkan perubahan.

Rilis mayor punya nama. Halaman versioning memberi Basil sebagai contoh, dan pengumuman proses dari Stripe menyatakan nama-namanya berasal dari tumbuhan, dimulai dengan Acacia, dan rilis bulanan mempertahankan nama rilis mayor sebelumnya agar namanya menandakan aman untuk di-upgrade. Changelog Stripe mendaftar nama yang dipakai, dan saat artikel ini ditulis entri terbarunya adalah 2026-09-30.endive.

Jadi tanggal menjawab “seberapa baru”, dan nama menjawab “apakah ini batas breaking”. Pengumuman Stripe juga menyisakan ruang untuk pengecualian: Stripe berhak merilis breaking change di luar siklus jika sebuah integrasi akan sangat terdampak tanpanya. Pengumumannya ada di proses rilis API baru Stripe.

Apa versi terbaru API Stripe?

Saat artikel ini ditulis (Oktober 2026), halaman versioning Stripe menyatakan versi terkini adalah 2026-09-30.endive, dan changelog-nya mencantumkan versi yang sama sebagai yang terbaru. Stripe menerbitkan versi baru setiap bulan, jadi string apa pun yang tercetak di artikel cepat usang. Baca changelog langsung sebelum mengunci apa pun, dan kunci versi yang Anda uji.

Bagaimana Stripe menjaga versi lama tetap berfungsi?

Stripe menjaga versi lama tetap hidup dengan menulis setiap breaking change sebagai modul perubahan versi yang berdiri sendiri dan menerapkan modul-modul itu mundur dari bentuk data terbaru. Engineering post tentang versioning API menjelaskan mekanismenya.

Setiap modul menyatakan apa yang diubahnya, mendokumentasikan perubahan itu, dan menyertakan fungsi transformasi. Post itu memberi contoh sebuah field yang berubah dari string menjadi hash. Untuk membangun respons, sistem menentukan versi target, lalu berjalan mundur dalam waktu dan menerapkan setiap modul yang ditemuinya sampai mencapai versi itu.

Dua efek samping mengikuti dari desain itu, dan post tersebut menyebut keduanya. Karena modul menyatakan field dan resource yang disentuhnya, Stripe bisa menghasilkan changelog API-nya dari modul saat deployment. Dan karena versi akun diketahui, dokumentasi bisa menyesuaikan diri dengan versi itu dan memperingatkan perubahan yang tidak kompatibel ke belakang sejak versi tersebut.

Berapa biayanya, dan apa yang sebaiknya ditiru API yang lebih kecil?

Versioning membutuhkan perhatian engineering, dan Stripe mengatakannya. Engineering post mengakui adanya beban pemeliharaan dan menyatakan tujuan bahwa makin sedikit pemikiran yang dibutuhkan untuk perilaku lama saat menulis kode baru, makin baik. Post itu juga menjelaskan tinjauan API ringan sebelum rilis, agar perubahan versi tidak perlu dilakukan sama sekali.

API kecil tidak sanggup membiayai rantai modul untuk setiap versi lama, dan tidak membutuhkannya. Tiru bagian yang membawa nilai:

1. Versi bertanggal. Tanggal tidak membutuhkan penilaian tentang apa yang dihitung “mayor”, dan pemanggil bisa membacanya. Artikel praktik terbaik versioning membandingkannya dengan skema URL dan header.
2. Default yang dikunci. Kunci akun atau key ke versi saat pemakaian pertama, agar API tidak bergeser di bawah integrasi yang sudah berjalan.
3. Override per request. Header yang memungkinkan pemanggil menguji versi baru pada satu panggilan, di produksi, sebelum berkomitmen.
4. Versi pada endpoint webhook. Payload event adalah tempat pemanggil paling sering terkejut.
5. Satu entri changelog per versi. Buat entri itu menyebut versi, tanggal, siapa yang terdampak, dan apa yang harus dilakukan. Apa yang dihitung breaking adalah ujian untuk apa yang pantas masuk versi baru, dan artikel changelog API membahas entrinya sendiri.

Lewati rantai modul sampai jumlah versi yang didukung memaksanya. Dua atau tiga versi aktif bisa ditangani dengan beberapa cabang dan tanggal sunset, yang dibahas menutup versi API.

Jika Anda menerbitkan changelog bertanggal, riwayat versi hanya sebaik entri-entrinya. Di Changeloop, draf entri dibuat dari setiap pull request yang di-merge dan ditahan agar manusia menyetujuinya sebelum diterbitkan ke halaman dan feed changelog. Di situlah entri per versi ditulis, dan satu gerbang manusia adalah tinjauan yang menyatakan apa yang harus dilakukan pemanggil.

FAQ

Apa versi terbaru API Stripe? Saat artikel ini ditulis (Oktober 2026), halaman versioning Stripe menyatakan versi terkini adalah 2026-09-30.endive. Stripe menerbitkan versi baru setiap bulan, jadi periksa changelog-nya sebelum mengunci, dan tulis versinya di kode Anda alih-alih bersandar pada default akun.

Bagaimana mengatur versi API Stripe pada sebuah request? Kirim header Stripe-Version, misalnya Stripe-Version: 2026-09-30.endive, atau atur versi di SDK sisi server Anda secara global atau per request. Tanpa keduanya, request memakai versi default akun Anda, yang Anda atur di Workbench.

Apakah webhook memakai versi API Stripe yang sama dengan request saya? Belum tentu. Event webhook memakai versi yang diatur saat endpoint dibuat, dan default akun jika tidak ada yang diatur. Meng-upgrade SDK tidak mengubah payload yang diterima handler webhook Anda, jadi upgrade endpoint secara terpisah dan uji secara paralel.

Apakah versioning bertanggal ala Stripe cocok untuk API kecil? Versi bertanggal, default yang dikunci, header per request, dan satu entri changelog per versi itu murah dan layak ditiru. Rantai modul perubahan versi internal tidak, sampai Anda mendukung banyak versi lama sekaligus. Mulailah dengan dua versi aktif dan tanggal sunset untuk yang lebih tua.

Klaim teknis dalam artikel ini belum ditinjau secara independen. Jika ada yang keliru, beri tahu kami dan kami akan memperbaikinya.

Terkait di changeloop: Dokumentasi developer