Changelog


I am super happy to announce the new design for the Makerkit subscriptions pages. This includes both a new dynamic pricing table and a much-improved subscription management page.

In this blog post, I want to introduce the new design and explain why we made the changes shipped today.

## The new pricing table

The new pricing table introduces the ability to have multiple plans with multiple variations. For example, you could have 3 different plans (Basic, Pro and Enterprise), each with a monthly or an annual price.

<Image src='/assets/images/posts/pricing-table.webp' width="2832" height="1884" />

The dynamic variant switcher will automatically show the prices for the selected variant.

### Configuring the plans

Below is how to configure the new Makerkit's configuration for Stripe:

```ts
stripe: {
  products: [
    {
      name: 'Basic',
      description: 'Description of your Basic plan',
      badge: `Up to 20 users`,
      features: [
        'Basic Reporting',
        'Up to 20 users',
        '1GB for each user',
        'Chat Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$9',
          stripePriceId: 'basic-plan-mth',
          trialPeriodDays: 7,
        },
        {
          name: 'Yearly',
          price: '$90',
          stripePriceId: 'basic-plan-yr',
          trialPeriodDays: 7,
        },
      ],
    },
    {
      name: 'Pro',
      badge: `Most Popular`,
      recommended: true,
      description: 'Description of your Pro plan',
      features: [
        'Advanced Reporting',
        'Up to 50 users',
        '5GB for each user',
        'Chat and Phone Support',
      ],
      plans: [
        {
          name: 'Monthly',
          price: '$29',
          stripePriceId: 'pro-plan-mth',
          trialPeriodDays: 7,
        },
        {
          name: 'Yearly',
          price: '$200',
          stripePriceId: 'pro-plan-yr',
          trialPeriodDays: 7,
        },
      ],
    },
    {
      name: 'Premium',
      description: 'Description of your Premium plan',
      badge: ``,
      features: [
        'Advanced Reporting',
        'Unlimited users',
        '50GB for each user',
        'Account Manager',
      ],
      plans: [
        {
          name: '',
          price: 'Contact us',
          stripePriceId: '',
          trialPeriodDays: 7,
          label: `Contact us`,
          href: `/contact`,
        },
      ],
    },
  ],
}
```

There are various options available, such as:

1. Adding a custom label using the `label` property in each plan. Useful, for example, if you want to add a "Contact us" button instead of a "Checkout" button.
2. Adding a custom link using the `href` property in each plan. Useful, for example, if you want to link to a contact form instead of a checkout page.

## The new subscription management page

The new subscription management page is a much-improved version of the previous one. 

It now includes a much better overview of the current subscription. Thanks to granular labels and descriptions, you can now show the exact state of the subscription.

Furthermore, we simplified the plan selector by reusing the same pricing table used on the pricing page.

### Plan selector

The old plan selector has been removed. Instead, we now use the pricing table from the pricing page. This makes it easier to understand the different plans and variants when picking a plan from within the subscription management page.

<Image src='/assets/images/posts/plan-selector.webp' width="2832" height="2024" />

### Subscription Status

The subscription status has been improved to show the exact state of the subscription. This includes the current plan, the current status, the next billing date, and whether the subscription is set to be renewed automatically.

Furthermore, unless the subscription is active, users will now see a badge in the top-right corner of the page to indicate the current status of their subscription.

<Image src='/assets/images/posts/subscription-status.webp' width="2844" height="2024" />


## Conclusion

I am super excited about the new design for the Makerkit subscription pages. I hope you like it as much as I do. 

If you have any questions or feedback, please let me know!


Changelog: New Stripe Subscriptions Pages

Tutorials

The complete guide to Stripe and Next.js


Testing is a crucial part of software development, but it can be difficult to know where to start, especially if you are interacting with the code of a third party on a different application; as it turns out, this is the case with Stripe, the most famous payment processor for developers.

Unfortunately, from what I've seen around, it's very hard to test its implementation, especially if you are using Stripe Checkout, a hosted portal that lives on Stripe's platform.

## Testing external pages with Cypress can be challenging

Why is it hard, you ask?

- Testing applications you do not own is very risky because the code can change anytime and without warning
- Testing real applications can be very time-consuming

Long story short, the Cypress team discourages testing other applications and instead recommends mocking or programmatically interacting with the third party, which is what we'll be doing.

## Testing your Stripe implementation is crucial

Testing your Stripe implementation is crucial to making sure your payments are being processed as intended. If you're building a website, it's best to test out the functionality early and often.

Skipping testing your Stripe may be tempting due to its complexity, and the fact that the Stripe Checkout portal actually does most of the heavy lifting, but it's not something we'd recommend for such a crucial part of your SaaS.

## We assume you have already a working implementation

This guide assumes you have already a working implementation of Stripe in your application.

For this article, I'll show how we can test three scenarios:

- **Creating a subscription**
- **Deleting a subscription**

But first, we have to run a Stripe emulator to mock the calls to the Stripe backend.

## Install stripe-mock, an official library to emulate a Stripe server locally

Stripe has released `stripe-mock`, an official library to **emulate a Stripe server locally**, it will allow you to run your tests against the mocked API and make sure that the changes you've made don't break anything.

To run it, we can use Docker with the following command:

```
docker run --rm -it -p 12111-12112:12111-12112 stripe/stripe-mock:latest
```

The server will run at `localhost:12111` for HTTP and `localhost:12112` for HTTPS.

Additionally, you need to make sure to be running the Stripe CLI server with the following command:

```
stripe listen --forward-to localhost:3000/api/stripe/webhook
```

Of course, remember to update the command with your application's details.

### Stripe Emulator Limitations

The above is amazing, isn't it?

Well, yes, but you should be aware of the limitations of the library:

- **it's stateless**: what does it mean? It does not store the data we create, which means we need to stick to the data that has been preloaded.
- **no webhooks**: it does not automatically send webhooks, which means we have to do it manually.
- **does not cover the full API**: it does not handle the full API, and it only works with the latest version's specs

This is not great, but we can make it work.

## Changing your Stripe instance to work with the emulator

Now that the Stripe server is running, we have to update the Stripe client's to be pointing to the emulator's server, rather than the real Stripe endpoints.

To do so, we also need to discriminate between a production instance and a testing one. Of course, this will depend on how you structured your application; in our case, we use a simple check (the below is based on a Next.js application)

- we check if the `NODE_ENV` variable is `"development"`
- we check if the `NEXT_PUBLIC_EMULATOR` variable is `"true"`

```tsx
function isCypressEnv() {
  return Boolean(
    process.env.NODE_ENV === `development` &&
      process.env.NEXT_PUBLIC_EMULATOR === `true`
  );
}
```

The Stripe emulator instance is created in the following way.

### Loading the Stripe client

1) First, we lazy load the Stripe client library to reduce the API execution time:

```tsx
async function loadStripe() {
  const { default: Stripe } = await import('stripe');

  return Stripe;
}
```

### Initialize the Stripe emulator

Then, we initialize the Stripe emulator instance by passing the correct host and port and changing the protocol to `http` (if you run localhost with HTTPS, feel free to ignore it)

```tsx
async function getStripeEmulatorInstance() {
  const Stripe = await loadStripe();

  return new Stripe(`sk_test_12345`, {
    host: `localhost`,
    port: 12111,
    apiVersion: STRIPE_API_VERSION,
    protocol: `http`,
  });
}
```
Finally, we export a factory that passes the correct instance based on the environment:

```tsx
export async function getStripeInstance() {
  if (isCypressEnv()) {
    console.warn(`Stripe is running in Testing mode`);

    return getStripeEmulatorInstance();
  }

  return getStripeProductionInstance();
}
```
And that's it! All our code that calls the **Stripe API will now interact with the emulator instance** rather than the real Stripe endpoints.

## Creating a Stripe Page Object in Cypress

I'm old-fashioned, so I create page objects in my Cypress tests.

The code below is a small utility to help us write tests more declaratively and in a more reusable fashion:

```tsx
import * as StripeLib from 'stripe';
import { StripeWebhooks } from '~/core/stripe/stripe-webhooks.enum';

const stripe = new StripeLib.Stripe(`sk_test_12345`, {
  host: `localhost`,
  port: 12111,
  apiVersion: '2020-08-27',
  protocol: `http`,
});

const $get = cy.cyGet.bind(cy);
const PORT = 12111;

const stripePo = {
  $plans: () => $get('subscription-plan'),
  $checkoutForm: () => $get('checkout-form'),
  $subscriptionName: () => $get('subscription-name'),
  createWebhookPayload,
  sendWebhook(params: { type: StripeWebhooks; body: UnknownObject }) {
    const body = this.createWebhookPayload(params.body, params.type);
    const signature = stripePo.createSignature(body);

    cy.request({
      url: 'http://localhost:3000/api/stripe/webhook',
      method: `POST`,
      headers: {
        ['stripe-signature']: signature,
      },
      body,
    });
  },
  selectPlan(number: number = 0) {
    this.$plans().eq(number).click();
    this.$checkoutForm().submit();
  },
  createSignature(payload: unknown) {
    return stripe.webhooks.generateTestHeaderString({
      payload: JSON.stringify(payload),
      secret: Cypress.env('STRIPE_WEBHOOK_SECRET'),
    });
  },
};

function createWebhookPayload(data: unknown, type: StripeWebhooks) {
  return {
    id: 'evt_1LK3nDI1i3VnbZTqgFqyzkWx',
    object: 'event',
    api_version: '2020-08-27',
    created: 1657473579,
    data: {
      object: data,
    },
    livemode: false,
    pending_webhooks: 0,
    request: {
      id: null,
      idempotency_key: null,
    },
    type,
  };
}

export default stripePo;
```

Most of it is quite simple if you're not new to Cypress, but you may want to check out the snippet where we send Webhooks to our Stripe endpoint, which can help you write more tests if your code handles more scenarios.

## Sending Webhooks to our Stripe endpoint manually

Makerkit implements a webhook handler at `/api/stripe/webhook.ts` that responds to the event sent by Stripe:

```tsx
switch (event.type) {
  case StripeWebhooks.Completed: {
    // handle Completed
  }

  case StripeWebhooks.AsyncPaymentSuccess: {
    // handle SubscriptionDeleted
  }

  case StripeWebhooks.SubscriptionDeleted: {
    // handle SubscriptionDeleted
  }

  case StripeWebhooks.SubscriptionUpdated: {
    // handle SubscriptionUpdated
    break;
  }

  case StripeWebhooks.PaymentFailed: {
    // handle PaymentFailed
  }
}
```

That means, to send a webhook that targets one of the code paths below (for example, the `Completed` event), **we would do the following request**:

```tsx
stripePo.sendWebhook({
  body: session,
  type: StripeWebhooks.Completed,
});
```

The request above (as you can see from the page object snippet), uses Cypress' `cy.request` to send an HTTP request to our endpoint. By doing so, we emulate the Stripe client:
- instead of having the Stripe emulator run the webhooks requests (which cannot do), **we send them manually with Cypress**
- the tricky part is sending the data with the correct payloads, which **requires work and changing the fixture's data according to both our database's data and the Stripe emulator's static data** (remember, it's stateless! data won't change, and we cannot use our own)
  - fortunately, we provide the `gists` at the end of the article that you can use with your tests

Where does `session` come from? I took them from the mock server's data: because it's static, we are forced to use the same as the server's to make it work.

To load them, we use a `Cypress fixture`, i.e. a piece of data we can load from the `fixtures` folder:

```tsx
cy.fixture('session').then((session) => {
 // session is the JSON stored in the file fixtures/session.json
});
```

## 1) Testing the creation of a Stripe subscription

Let's implement the first scenario, i.e. creating a simple Stripe subscription with immediate payment.

What we are going to do:

- send the webhook above
- verify the UI works
  - in our case, we verify is the subscription has been displayed
    - it's very important to reload your page using `cy.reload()` if you don't update your UI in real-time to see the changes
  - if you want to take it a step further, you could check if the DB's data matches the UI

Let's take a look below:

```tsx
import stripePo from '../../support/stripe.po';
import { StripeWebhooks } from '~/core/stripe/stripe-webhooks.enum';

describe(`Create Subscription`, () => {
  before(() => {
    cy.signIn(`/settings/subscription`);
  });

  describe('Using Webhooks', () => {
    describe(`When the user creates a subscription`, () => {
      before(() => {
        cy.fixture('session').then((session) => {
          stripePo.sendWebhook({
            body: session,
            type: StripeWebhooks.Completed,
          });
        });
      });

      it(`should display a Subscription Card`, () => {
        cy.reload();

        stripePo.$subscriptionName().should('have.text', 'Testing Plan');
      });
    });
  });
});
```

## 2) Testing the deletion of a Stripe subscription

The implementation is very similar to the above, with the exception that we pass:

- the `subscription` fixture instead of `session`
- the event type `StripeWebhooks.SubscriptionDeleted`

```tsx
describe(`When the user unsubscribes`, () => {
  before(() => {
    cy.fixture('subscription').then((subscription) => {
      stripePo.sendWebhook({
        body: subscription,
        type: StripeWebhooks.SubscriptionDeleted,
      });
    });
  });

  it('should delete the subscription', () => {
    cy.reload();

    stripePo.$subscriptionName().should('not.exist');
  });
});
```

## Demo: testing Stripe with Cypress

Here is a short video of the Stripe E2E tests with Cypress that are included in Makerkit:

<Video src='/assets/images/posts/e2e-stripe.mp4' />

It's **fast**, isn't it?

## The fixtures

If you want, you can check out the Stripe fixtures I use for my tests in the `gists` below:

[Click here to download the Subscription and Session gists](https://gist.github.com/Gbuomprisco/3a0969ef9cf82d2b79c6e018a983b964)

Edit the fixtures for your own data:

- for example, `client_reference_id` in `subscription.json` is my own testing organization: you should edit this value to match your database's.

## Conclusion

Testing Stripe with Cypress is a great way to ensure that your payment form, including the callbacks and server-side validation, is working as expected.

I hope the guide above can help you write your Stripe tests with ease and confidence.

Too bothered to write the code yourself? If you purchase Makerkit, it's already done for you!

If you want to give it a try and need a hand, please contact me at [info@makerkit.dev](mailto:info@makerkit.dev); always happy to help!


How to test Stripe Checkout with Cypress


Hey everyone, happy new year!

Here at MakerKit, I started my 2022... making, of course!

More specifically, I improved MakerKit to support payments and
subscriptions using Stripe Checkout!

The last time I had used Stripe, the Checkout product was still unavailable:
it is incredible the amount of work it can save developers.

As incredible as is, Stripe Checkout cannot do everything for you. This is where
MakerKit jumps in.

At MakerKit, I wanted to make it dead-easy to define your Stripe plans,
automatically create a plan selector, and enable your app to
handle the webhooks received by Stripe to update your application's database
accordingly.

With this release, this is all possible.

## Defining the Plans

After having added and configured the plans in
Stripe, we do the same in your application.

We're going to add the plans to the `~/configuration.ts` file, which is
where we store most of our application's config:

```tsx title="configuration.ts"
plans: [
    {
      name: 'Basic',
      description: '3 users and 10 todos',
      price: '$249/year',
      stripePriceId: '<STRIPE_PRICE_ID>',
    },
    {
      name: 'Pro',
      description: 'Unlimited users and todos',
      price: '$999/year',
      stripePriceId: '<STRIPE_PRICE_ID>',
    },
  ]
```

These are already configured to work with the `PlanSelector.tsx` component,
which pulls the plans from the configuration and creates a checkbox with the
data entered.

It's going to look similar to the below:

<Image
  layout={'responsive'}
  width={'2390'}
  height={'1610'}
  src={'/assets/images/posts/stripe-plan-selector.webp'}
/>

You can select a plan by clicking on one and then proceeding by clicking on
"Continue to Checkout".

<Video src={'/assets/images/posts/stripe-plan-selector-video.mp4'} />

## Checkout

Once a plan gets selected, the user can then continue to Stripe Checkout,
which is a page hosted and managed by Stripe.

Once selected and subscribed to plan the user gets redirected back to the
subscription page.

<Video src={'/assets/images/posts/subscribe-to-plan.mp4'} />

## Billing Portal

Once the user has subscribed, they should also be able to perform the
following actions:

- cancel the plan
- update to a new plan
- update payment method
- see previous invoices

Thankfully, the Stripe Portal can handle most of these for us!

The application's side (MakerKit) takes care of handling the webhooks sent
by Stripe when the user takes any of the actions above.

<Video src={'/assets/images/posts/billing-portal.mp4'} />

In the video above, the user accessed the Stripe billing portal, canceled their
plan, and then went back to the subscriptions page.

The user can now pick a plan again or visit their Billing Portal (as we
now can identify the user with a Stripe ID), so that they can manage their
billing settings directly from the customer portal.

## Documentation

Check out <a href="/docs/stripe-configuration">the documentation for setting up
Stripe and MakerKit</a>.

Thank you for reading so far! If you have any questions, please <a
href="/contact">contact us</a>.


Stripe

Tutorials and Guides about Stripe

Changelog: New Stripe Subscriptions Pages

The complete guide to Stripe and Next.js

How to test Stripe Checkout with Cypress

Get paid with Stripe