Lessons From the Docs — Stripe API

Nathan K.
4 min readDec 11, 2022

Working with the Stripe API as a front-end web developer brings its own set of questions. The API is vast and contains its own nuances and patterns which may only be familiar to those who’ve implemented payment processes. Luckily, Stripe has well-designed documentation that clearly showcases everything from how to implement webhooks to endpoints.

There are a lot of different ways of implementing the Stripe API. This publication will be focused on some of the lessons I’ve come across from implementing a payment process for the first time.

Do Your Deliverables Require a Backend Server?

A client of mine wanted to implement a payment portal and membership plans page for their subscription memberships. I researched different payment processing services and settled on utilizing Stripe Checkout. Stripe Checkout is a prebuilt and hosted payment page that is used for one-time payments and subscriptions.

After reading the documentation the prebuilt checkout seemed to be a viable option. The client's deliverables specifically included having the option to add discounts and coupons during subscription checkouts.

A few months into implementation I came across my first roadblock. Due to some of the limitations of the prebuilt checkout, adding discounts and coupons could not be implemented without a backend API integration to handle it. The documentation below notes that the following functionalities need integration ( API integration ).

Lesson Learned: Implementing discounts, coupons and other features below will need a backend server.

The below image is from this section of the documentation that goes through what implementations need backend API Integration. https://stripe.com/docs/billing/subscriptions/build-subscriptions?ui=checkout

The documentation for knowing when you can use the prebuild stripe checkout and when you need to add custom API integration should be more pronounced in the documentation. Due to running into this roadblock I wanted to list 3 things to keep in mind when working with Stripe (especially as a frontend dev or devs who never implemented payment processes).

Dig Deeper Into The Stripe API Documentation

The documentation can be daunting but they do cover the API in-depth. The search capabilities make it easier to find what you're looking for but sometimes that's not enough. Each section can obtain small disclaimers. If these are overlooked it can lead to possible rework issues down the road. In order for you to avoid some mistakes I made along the process, I’ve outlined a 3-point Checklist for when you’re looking through Stripe documentation.

1. List Your Deliverables.

This will give you a sense of what needs to be researched.

2. Search The Functionality For Each Deliverable

This may take time but you need to find all the sections in the documentation that cater to the needs of your deliverable. This step is where I stopped during my project.

3. Test Desired Stripe Features Isolation

This step is essential for making sure you don’t miss any disclaimers that could set you back on a project. After researching how Stripe implements your desired functionality, an isolated test will help you find any blockers or issues that you need to bring to the client's attention. Most of the time the client will decide if the feature is needed or can be implemented in the future. Either way, putting in the extra time to test may have saved hours or days of rework.

Stripe Webhook Events(Actions) Are Asynchronous

When implementing the Stripe webhook API on the server there are certain events or actions that trigger functions in Stripe.

Here are all the Stripe event types:


Lesson Learned: It’s important to note that webhook actions don’t run synchronously ( even within a conditional )

For example:

When a user is in the checkout phase you might be using a webhook to retrieve or store data during the following events.

  1. customer.created When the user enters checkout, pass the user’s email into Stripe’s customer object.

2. customer.subscription.created — Then when the subscription is created, retrieve the subscription information and store it in a database.

3. checkout.session.completed — Then trigger an email to the user notifying them that they have completed their checkout

During the checkout this is how the webhooks could resolve:


Test Your Checkout Processes Using The Stripe CLI Tool

When building an app with payment processing, testing is essential to see if the payments and data are handled properly. The Stripe CLI tool is key for testing payments (without using your actual money). The Stripe CLI tool allows you to log your events in real-time and see how the data is flowing through a checkout process while on your localhost.

Here’s a good video to start with Stripe CLI Tool.


The Stripe API is vast and I’m continuing to learn new things about it. These are a few of the gotchas I’ve come across when working with it. Below are some good resources I found that helped me learn more about the API.



Nate Keeys — Digital Anthro



Nathan K.

Owner | UI/UX Consultant | Frontend Web Engineer @ Digital Anthro, LLC— UI/UX consulting for startups and small businesses