This post covers one of most common use cases for apps today - providing premium tiers for your customers using Stripe. Here are a few assumptions we’re going to make:

* You want to offer users multiple tiers, with one or more common billing period (in this post we’ll assume Monthly & Yearly)  
* A user can only be on one tier at a time  
* You’ve done the upfront work of getting your company registered and verified in Stripe  
* You know the [Product tax code](https://docs.stripe.com/tax/tax-codes) you need to use  
* You’re building the frontend in React/NextJS and have a backend in NodeJS (if not, they offer [multiple SDKs](https://docs.stripe.com/sdks), you can still use the information in this post with some modifications)  
* We’ll use [tailwindcss v3](https://v3.tailwindcss.com/) for styling, feel free to use your own

### Setup

We HIGHLY recommend that you do your initial setup in [Stripe Test mode](https://docs.stripe.com/test-mode), which is easily accessible on your Stripe dashboard on the top right.  
![](/blog/media/stripe-integration-1-1.png)

Stripe has strict limitations on what data you can change, and it's best to find these out as you’re configuring stripe in test mode. For example, you cannot delete products or prices once they’ve been used in a subscription (even if the subscription is now deactivated), they can only be archived. Test mode also lets you test checkout workflows with fake payments, including testing payments that fail for various scenarios.

Here are key setup steps you’ll need to do:

* [Set up API keys in Stripe](https://dashboard.stripe.com/apikeys), you’ll need both **Secret key** and **Publishable key**  
* Install the [Stripe ReactJS SDK](https://www.npmjs.com/package/@stripe/react-stripe-js) & [Stripe.js SDK](https://www.npmjs.com/package/@stripe/stripe-js) on your frontend  
* Install the [Stripe NodeJS SDK](https://www.npmjs.com/package/stripe) on your backend

With that, let’s get going!

### Products & Prices

First we need to create some [products](https://docs.stripe.com/api/products) & [prices](https://docs.stripe.com/api/prices) in Stripe, which will allow the customer to create subscriptions to them.

* Create a new product in the [Product Catalog](https://dashboard.stripe.com/test/products?active=true) (you’ll also be creating your first price here)  
  ![](/blog/media/stripe-integration-1-2.png)
* Fill in all the required information  
* Make sure to put in a description, we’ll use this on the frontend  
* Make sure to put all the features of the tier in the Marketing feature list, we’ll use this on the frontend  
* You can add any other **Metadata** you might want to display to the user (for example, we use this to additional description information to display in a subsection)  
* Decide whether you want to [include tax in the price](https://docs.stripe.com/tax/products-prices-tax-codes-tax-behavior#tax-behavior)  
* Make sure to set the price to **Recurring** & the billing period to **Monthly** or **Yearly**

And that’s done! Now do it a few more times so you have multiple tiers, each with a **Monthly** & a **Yearly** price.

NOTE: You’ll need to decide what to do with your Free tier. Some companies prefer to have this workflow also go through Stripe (in which case make sure to create a Free product with a 0 currency price). We chose to avoid this step to streamline the workflow for free users, and to avoid having to create Stripe accounts for users unless they’re on a paid subscription.

### Pricing page (signed out experience)

There are two flavors of this page

* For a signed out experience - for example on the landing page  
* For a signed in experience - for example in the app, with customized CTAs based on the user’s current subscription

We’ll cover the signed out experience in this post (and signed in experience in the [next blog post](/blog/posts/stripe-integration-2)).

Now it’s time to build the pricing page on the frontend (no work is required on the backend for this step). We’ll assume you have a design in mind, if not feel free to use [The Possible Company Pricing](/pricing) page as inspiration.

* We recommend that you don’t just call the API to get ALL your stripe products, and instead use a configuration layer to specify which products you want to display to the user  
* Grab the list of product IDs from the [Product Catalog](https://dashboard.stripe.com/test/products?active=true), and store them as a list in a config

```
STRIPE_PRODUCT_IDS=prod_abcdefghijklm1,prod_abcdefghijklm2,prod_abcdefghijklm3
```

* Create a server-side API, we’ll call ours

```
/api/products
```

* Get all the products & prices

```javascript
const [stripeProducts, stripePrices] = await Promise.all([
  Promise.all(
    productsList.map(async (productId) => {
      try {
        return await stripe.products.retrieve(productId);
      } catch (error) {
        console.error(`Error retrieving product ${productId}:`, error);
        return null;
      }
    })
  ).then((results) => results.filter((product) => product !== null)), // Filter null products
  stripe.prices.list({ active: true }),
]);
```

* Structure the data the way you would like and return it, here are the key fields to account for  
  * Product ID  
  * Product name  
  * Product description  
  * Product marketing features  
  * Product metadata (if any)  
  * Price ID  
  * Price currency  
  * Price unit amount (usually 1)  
  * Price recurrence interval

```javascript
const productsWithPrices: Product[] = stripeProducts.map((stripeProduct) => {
  const productPrices = stripePrices.data.filter(
    (price) => price.product === stripeProduct!.id
  );

  // Extract marketing features
  const marketingFeatures = {
    description: stripeProduct!.metadata.marketingFeaturesDescription || 'Includes',
    features: (stripeProduct!.marketing_features || []).map((feature) => (
      feature.name || ''
    )),
  };

  return {
    id: stripeProduct!.id,
    name: stripeProduct!.name || '',
    description: stripeProduct!.description || '',
    prices: productPrices.filter(price => price.recurring).map((price) => ({
      id: price.id,
      currency: price.currency,
      unit_amount: price.unit_amount || 0,
      recurring: {
        interval: price.recurring!.interval,
      }
    })),
    marketingFeatures,
  };
});
```

* Optionally, you can also add your free tier information in the same JSON format to the response before returning it  
* Call this API in a pricing component

```javascript
const [products, setProducts] = useState<Product[]>([]);
const [showMonthly, setShowMonthly] = useState(true);

useEffect(() => {
  async function fetchProducts() {
    try {
      const response = await fetch('/api/products');
      const data = await response.json();
      setProducts(data);
    } catch (error) {
      console.error('Error fetching products:', error);
    }
  }
  fetchProducts();
}, []);

const togglePricing = () => {
  setShowMonthly(!showMonthly);
};

return (
  <div className="flex-row md:flex items-center justify-between">
    <div className="flex justify-center md:justify-end font-bold space-x-4 mt-4 md:pr-24">
      <span className={ showMonthly ? "flex items-center text-black" : "flex items-center text-slate-400"}>
        Monthly
      </span>
      <button onClick={togglePricing}>
// Put some toggle icon here
      </button>
      <span className={ !showMonthly ? "flex items-center text-black" : "flex items-center text-slate-400"}>
        Annual
      </span>
    </div>
  </div>
  <div className="pt-8 pb-16 md:px-16 flex flex-col lg:flex-row justify-center">
    <PricingTable
      products={products}
      showMonthly={showMonthly}
    />
  </div>
);
```

* Then send the API data to a pricing table component to render

```javascript
const PricingTier = (product: Product, showMonthly: boolean, tier: number) => {
  const currentPrice = product.prices.filter((price) =>
    showMonthly
      ? price.recurring?.interval === "month"
      : price.recurring?.interval === "year"
  )[0];
  const isFreeTier = product.id === 'free';

  return (
    <div key={product.id} className="rounded-lg shadow-md p-6 hover:shadow-xl sm:hover:scale-105 transition w-64 flex flex-col justify-center">
      <div>
        <h2 className="text-black text-xl font-bold mb-2">{product.name}</h2>
        <p className="text-slate-400 mb-4">{product.description}</p>
        <div className="mb-4">
          <h3 className="text-md font-semibold mb-2">Features</h3>
          <p className="text-slate-400 text-sm mb-2">{product.marketingFeatures.description}</p>
          <ul className="text-gray-400 text-sm list-none space-y-1">
            {product.marketingFeatures.features.map((feature, index) => (
              <li key={`${product.id}-feature-${index}`} className="flex items-start text-slate-400 stroke-slate-400">
              {feature}
            </li>
            ))}
          </ul>
        </div>
      </div>
      <div className="mt-auto">
        <div key={currentPrice.id} className="mb-4">
          <p className="text-black text-lg font-medium">
            <span className="text-3xl font-bold">
              {new Intl.NumberFormat('en-US', {
                style: 'currency',
                currency: currentPrice.currency,
                maximumFractionDigits: 0,
              }).format(currentPrice.unit_amount / 100)}
            </span>{' '}
            per {currentPrice.recurring.interval}
          </p>
        </div>
        <div className="flex justify-center mt-4">
          <button className="w-full" onClick={() => { // Route to your checkout page here }>
            { isFreeTier ? "Get started" : "Subscribe" }
          </button>
        </div>
      </div>
    </div>
  );
}

export const PricingTable = ({ products, showMonthly }: PricingTableProps) => {
  return (
    <div className="px-4 sm:px-8 lg:px-8">
      <div className="flex flex-wrap gap-8 justify-center md:justify-start">
        {products.map((product, index) => PricingTier(product, showMonthly, index + 1))}
      </div>
    </div>
  );
};
```

### Subscription checkout workflow

With the pricing page done, the user is ready to checkout. Stripe provides [3 ways to create a checkout flow](https://docs.stripe.com/payments/checkout/build-integration), we’re going to use the [embedded form](https://docs.stripe.com/checkout/embedded/quickstart) as that is low-lift while also allowing you to keep your website URL & other key design elements (branding, nav etc).

The embedded form essentially just needs 2 parameters - the price ID for the user to check out, and a return URL to send the user back to after the checkout transaction is complete:

* You can pass these parameters to the checkout component however you like, in our case we pass query parameters for a unique number (tier #) and whether the recurrence is monthly or annual, then translate those back into a price ID to use (we hardcode the relative return URL)  
* After passing these parameters, build out the checkout component

```javascript
const stripePromise = loadStripe(process.env.NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY as string);

interface CheckoutProps {
  priceId: string;
}

export default function Checkout({
  priceId
}: CheckoutProps) {
  const router = useRouter();

  const fetchClientSecret = useCallback(() => {
    return fetch("/api/subscriptions/checkout", {
      method: "POST",
      body: JSON.stringify({
        priceId: priceId,
// Stripe will manage the CHECKOUT_SESSION_ID for you
        returnUrl: "/checkout/complete?sessionId={CHECKOUT_SESSION_ID}"
      })
    }).then((res) => res.json()).then((data) => data.clientSecret);
  }, []);
  const options = { fetchClientSecret };

  return (
    <div>
      <EmbeddedCheckoutProvider stripe={stripePromise} options={options}>
        <EmbeddedCheckout />
      </EmbeddedCheckoutProvider>
    </div>
  )
}
```

* Finally, just create a checkout complete page with important information for the user  
* Stripe will pass a query parameter called  sessionId  back to this page  
* In your backend, you can query the [Stripe Checkout Session Retrieval API](https://docs.stripe.com/api/checkout/sessions/retrieve) with this  sessionId , like so

```javascript
  const session = await stripe.checkout.sessions.retrieve(sessionId);
  return (session.status || "");
```

* Check the result of this query to ensure that it returns  complete , add some confetti, and you’re done!

Congratulations, you now have a basic functioning checkout workflow. In the [next blog post](/blog/posts/stripe-integration-2) we’ll cover the remaining workflows:

* Creating a pricing page when the user is signed in  
* Allowing users to upgrade or downgrade their subscription  
* Allowing users to cancel their subscription  
* Giving users the ability to manage their billing & invoices
