next-stripe-helper

next-stripe-helper

next-stripe-helper is a module designed to simplify the integration of Stripe's functionality into Next.js applications. Whether you're looking to process payments, manage customers, or handle subscriptions, this utility aims to streamline those interactions.

This utility is perfect for developers building e-commerce platforms, subscription-based services, or any other application that requires payment functionalities within a JS or TS ecosystem.

Includes a smart webhook handler that will automatically keep your database up to date with current plans, pricing, and subscriptions.

Installation

npm install next-stripe-helper

Prerequisites

Ensure you've set up Stripe and have an error handler in your project, as this utility relies on those components.

You will likely want to start in TEST MODE!! Make sure you use the test mode switch to turn Test Mode on before proceeding. Once you are setup and ready to take live payments, turn off test mode, get your LIVE stripe keys, and setup your LIVE webhooks secret and endpoint.

Ensure you have set the STRIPE_SECRET_LIVE or STRIPE_SECRET environment variables in your .env.local (or other environment-specific .env files). With Next.js, you can access these environment variables using process.env.

Ensure you have set the STRIPE_WEBHOOK_SECRET_LIVE or STRIPE_WEBHOOK_SECRET environment variables in your .env.local (or other environment-specific .env files).

# Stripe configuration
STRIPE_SECRET=your_stripe_TEST_secret_key
STRIPE_WEBHOOK_SECRET=your_TEST_stripe_webhook_secret

STRIPE_SECRET_LIVE=your_LIVE_stripe_secret_key
STRIPE_WEBHOOK_SECRET_LIVE=your_LIVE_stripe_webhook_secret

Make sure you complete your checkout settings from within the Stripe dashboard before using any checkout functions. Setup Checkout Settings

Make sure you add your webhooks endpoint URL!! Setup Webhook URL

Usage

Checkout Sessions

First, ensure that you've imported the necessary functions from the package:

import { createCheckoutSession, createCheckoutSessionForSavingCard } from 'next-stripe-helper';

Create Checkout Session

Create a checkout session with Stripe.

const session = await createCheckoutSession(
    'https://your-success-url.com',
    'https://your-cancel-url.com',
    itemsArray,  // Your array of line items
    'subscription',
    'customer_id',
    {}  // Additional optional parameters
);

Parameters:

• successUrl (required): The URL to redirect upon successful payment.
• cancelUrl (optional, default ""): The URL to redirect upon payment cancellation.
• itemsArray (required): An array of line items for the checkout.
• mode (optional, default subscription): The mode of the checkout session (subscription or payment).
• customerId (required): The Stripe customer ID.
• additionalParams (optional, default {}): Any other additional parameters.

Create Checkout Session for Saving Card

Create a checkout session with Stripe for the purpose of saving a card.

const sessionId = await createCheckoutSessionForSavingCard(
    'customer_id',
    'https://your-success-url.com',
    'https://your-cancel-url.com'
);

Parameters:

• customerId (required): The Stripe customer ID.
• successUrl (required): The URL to redirect upon successful card saving.
• cancelUrl (required): The URL to redirect upon cancellation.

Customer Utilities

Import the required functions:

import { createCustomer, getCustomer, updateCustomer } from 'next-stripe-helper';

Create a New Stripe Customer

Create a new customer in Stripe using their email address.

const newCustomer = await createCustomer('[e-mail]');

Parameters:

• email (required): The email address of the new customer.

Retrieve Customer Details

Fetch the details of a specific customer using their Stripe customer ID.

const customerDetails = await getCustomer('customer_id');

Parameters:

• customerId (required): The Stripe customer ID.

Update a Customer's Details

Update the details of a customer in Stripe.

const updates = {
    // Your update parameters here (e.g., email, name, etc.)
};
const updatedCustomer = await updateCustomer('customer_id', updates);

Parameters:

• customerId (required): The Stripe customer ID.
• updates (required): An object containing key-value pairs of the properties to be updated.

Get a Customer's Payment Details

Get the payment details of a customer in Stripe.

const paymentMethods = await getCustomerPaymentMethods('customer_id');

Parameters:

• customerId (required): The Stripe customer ID.

Billing Portal Utilities

The next-stripe-helper also facilitates easy interaction with Stripe's billing portal.

Usage

Firstly, remember to import the necessary function:

import { createPortalLink } from 'next-stripe-helper';

Create Portal Session Link

Generate a link for your users to access Stripe's billing portal where they can manage their billing details.

const portalUrl = await createPortalLink('customer_id', 'https://your-return-url.com');

Parameters:

• customer (required): The Stripe customer ID.
• returnUrl (required): The URL where the user will be redirected after exiting the billing portal.

Products and Prices Utilities

The next-stripe-helper provides utilities to help with the creation of products and their associated prices on Stripe.

Usage

Start by importing the functions you need:

import { createProduct, createPrice } from 'next-stripe-helper';

Create a Product

To create a new product in Stripe, use:

const newProduct = await createProduct('Product Name', 'Product Description');

Parameters:

• name (required): The name of the product.
• description (required): A brief description of the product.

Create a Price for a Product

Once you have a product, you can set its price:

const newPrice = await createPrice('product_id', 1000, 'usd', { optionalMetadata: 'value' });

Parameters:

• productID (required): The ID of the product for which the price is being set.
• amount (required): The amount to be charged for the product, in the smallest unit for the currency (e.g., cents for USD).
• currency (required): The three-letter ISO currency code. (e.g., 'usd', 'eur', 'gbp').
• metadata (optional): A key-value store for any additional information you want to store.

Note: The price is set up as recurring, with a monthly interval. If you wish to modify the recurrence, you would need to adjust the utility function accordingly.

Subscription Utilities

The next-stripe-helper package offers a suite of utilities designed to streamline interactions with Stripe subscriptions.

Usage

Before you can use these utilities, you need to import them:

import {
    getUserCurrentPlan,
    getUserSubscription,
    getUserSubscriptionDetails,
    updateUserSubscriptionMetadata,
    changeSubscriptionPlan,
    listUserSubscriptions,
    cancelUserSubscription
} from 'next-stripe-helper';

Retrieve a User's Current Plan (first subscription)

Fetch details of a users first plan using the Customer ID:

const plan = await getUserCurrentPlan('customer__id');

Parameters:

• customerId (required): The Customer ID of the user.

Returns:

• plan or null if no plan is found

Retrieve a User's Subscription

Fetch details of a specific subscription using its Stripe ID:

const subscriptionDetails = await getUserSubscription('subscription_id');

Parameters:

• subscriptionID (required): The Stripe ID of the subscription.

Change a User's Subscription

Change a users existing subscription using its Stripe ID:

This will use the current payment method by default. Customer must have an existing subscription.

const subscriptionDetails = await changeSubscriptionPlan('subscription_id', 'new_plan_id')

Parameters:

• subscriptionID (required): The Stripe ID of the existing subscription.
• new_plan_id (required): The Stripe plan ID of the new plan.

Get Detailed Information About a Subscription

To fetch comprehensive details about a subscription, including its associated price metadata:

const detailedInfo = await getUserSubscriptionDetails('subscription_id');

Parameters:

• subscriptionID (required): The Stripe ID of the subscription.

Update Metadata for a User's Subscription

If you wish to modify the metadata of a subscription:

const updatedSubscription = await updateUserSubscriptionMetadata('subscription_id', { key: 'newValue' });

Parameters:

• subscriptionID (required): The Stripe ID of the subscription.
• metadata (required): An object containing key-value pairs for metadata updates.

List All Active Subscriptions for a User

Retrieve a list of all active subscriptions associated with a particular customer:

const activeSubscriptions = await listUserSubscriptions('customer_id');

Parameters:

• customerID (required): The Stripe ID of the customer.

Cancel a User's Subscription

To cancel a subscription:

const cancelledSubscription = await cancelUserSubscription('subscription_id');

Parameters:

• subscriptionID (required): The Stripe ID of the subscription.

Retrieve User's Subscription Period

To cancel a subscription:

const periodData = await getSubscriptionPeriod('subscription_id');

Parameters:

• subscriptionID (required): The Stripe ID of the subscription.

Returns:

• start period start JS Date
• end period end JS Date

Webhook Handler with Next.js

In the Next.js environment, API routes provide a solution to build your backend functionality. The next-stripe-helper comes equipped with a webhook handler specifically designed for easy integration with Next.js API routes.

If you add the webhookHandler to an api route, your Database will automatically stay in sync with Stripe Products, Prices, and Subscriptions.

Usage

First, you'll need to import the webhook handler into your API route:

import { webhookHandler } from 'stripe-next-helper'; 

Then, set up an API route in Next.js to handle the Stripe webhook:

// pages/api/stripe/webhook/route.js

import { webhookHandler } from 'next-stripe-helper';
import { manageSubscriptionStatusChange, upsertPriceRecord, upsertProductRecord } from '@/lib/stripe';
import { headers } from "next/headers"

export async function POST(req) {
    try {
        const body = await req.text();
        const signature = headers().get("Stripe-Signature");

        if (!signature) {
            throw new Error('Stripe signature missing from headers');
        }

        await webhookHandler(
            upsertProductRecord, 
            upsertPriceRecord, 
            manageSubscriptionStatusChange, 
            { body, signature }
        );

        return new Response(null, { status: 200 });
    } catch (error) {
        console.error(error);
        return new Response(JSON.stringify({ error: error.message }), { status: 500 });
    }
}

Here's an example of Stripe Helper Functions for a MongoDB Database.

import clientPromise from '@/lib/mongodb'
import { ObjectId } from 'mongodb'

const dbName = process.env.MONGODB_DB

export const getActiveProductsWithPrices = async () => {
    try {
        const client = await clientPromise
        const data = await client
            .db(dbName)
            .collection('products')
            .aggregate([
                {
                    $lookup: {
                        from: 'prices',
                        localField: '_id',
                        foreignField: 'product_id',
                        as: 'prices',
                    },
                },
                { $match: { active: true, 'prices.active': true } },
                { $sort: { 'metadata.index': 1, 'prices.unit_amount': 1 } },
            ])
            .toArray()

        return data || []
    } catch (error) {
        console.log(error.message)
        return []
    }
}

export const getActiveApiProductsWithPrices = async () => {
    try {
        const client = await clientPromise
        const data = await client
            .db(dbName)
            .collection('products')
            .aggregate([
                {
                    $lookup: {
                        from: 'prices',
                        localField: '_id',
                        foreignField: 'product_id',
                        as: 'prices',
                    },
                },
                {
                    $match: {
                        active: true,
                        'prices.active': true,
                        'metadata.is_api_product': 'true',
                    },
                },
                { $sort: { 'metadata.index': 1, 'prices.unit_amount': 1 } },
            ])
            .toArray()

        return data || []
    } catch (error) {
        console.log(error.message)
        return []
    }
}


export const upsertProductRecord = async (product) => {
    const productData = {
        _id: product.id,
        active: product.active,
        name: product.name,
        description: product.description ?? undefined,
        image: product.images?.[0] ?? null,
        metadata: product.metadata,
    }
    const client = await clientPromise
    const result = await client
        .db(dbName)
        .collection('products')
        .updateOne(
            { _id: productData._id },
            { $set: productData },
            { upsert: true }
        )

    if (result.upsertedCount || result.modifiedCount) {
        console.log(`Product inserted/updated: ${product.id}`)
    }
}

export const upsertPriceRecord = async (price) => {
    const priceData = {
        _id: price.id,
        product_id: typeof price.product === 'string' ? price.product : '',
        active: price.active,
        currency: price.currency,
        description: price.nickname ?? undefined,
        type: price.type,
        unit_amount: price.unit_amount ?? undefined,
        interval: price.recurring?.interval,
        interval_count: price.recurring?.interval_count,
        trial_period_days: price.recurring?.trial_period_days,
        metadata: price.metadata,
    }
    const client = await clientPromise
    const result = await client
        .db(dbName)
        .collection('prices')
        .updateOne(
            { _id: priceData._id },
            { $set: priceData },
            { upsert: true }
        )

    if (result.upsertedCount || result.modifiedCount) {
        console.log(`Price inserted/updated: ${price.id}`)
    }
}

const copyBillingDetailsToCustomer = async (uuid, payment_method) => {
    const customer = payment_method.customer
    const { name, phone, address } = payment_method.billing_details
    if (!name || !phone || !address) return

    await stripe.customers.update(customer, { name, phone, address })
    const client = await clientPromise
    const result = await client.db(dbName).collection('users').findOneAndUpdate(
        { _id: uuid },
        {
            $set: {
                billing_address: { ...address },
                payment_method: { ...payment_method[payment_method.type] },
            },
        },
        { returnOriginal: false }
    )
    if (!result.value) {
        throw new Error('Error updating user billing details')
    }
}

export const manageSubscriptionStatusChange = async (
    subscriptionId,
    customerId,
    createAction = false
) => {
    console.log('manageSubscriptionStatusChange: Started.')
    console.log(customerId)
    const client = await clientPromise
    const customerData = await client
        .db(dbName)
        .collection('customers')
        .findOne({ stripe_customer_id: customerId })

    if (!customerData) {
        console.log(
            'manageSubscriptionStatusChange: Customer not found. id:',
            customerId
        )
        throw new Error('Customer not found')
    } else {
        console.log(
            'manageSubscriptionStatusChange: Customer found: ',
            customerData
        )
    }

    const uuid = customerData._id.toString()

    let subscription
    try {
        subscription = await stripe.subscriptions.retrieve(subscriptionId, {
            expand: ['default_payment_method'],
        })
    } catch (error) {
        console.log('manageSubscriptionStatusChange: Stripe Error: ', error)
        throw new Error(
            'Stripe error retrieving subscription in manageSubscriptionStatusChange.'
        )
    }

    if (!subscription) {
        throw new Error(
            'Stripe error retrieving subscription in manageSubscriptionStatusChange.',
            subscription
        )
    } else {
        console.log(
            'manageSubscriptionStatusChange: Stripe subscription found.',
            subscription.id
        )
    }
    const subscriptionItems = subscription.items.data.map((item) => ({
        price_id: item.price.id,
        product_id: item.price.product,
        quantity: item.quantity,
    }))

    // console.log('subscriptionItems',subscriptionItems)

    const subscriptionData = {
        _id: subscription.id,
        user_id: new ObjectId(uuid),
        team_id: new ObjectId(subscription.metadata.team_id),
        metadata: subscription.metadata,
        status: subscription.status,
        price_id: subscription.items.data[0].price.id,
        items: subscriptionItems,
        cancel_at_period_end: subscription.cancel_at_period_end,
        cancel_at: subscription.cancel_at
            ? new Date(subscription.cancel_at * 1000)
            : null,
        canceled_at: subscription.canceled_at
            ? new Date(subscription.canceled_at * 1000)
            : null,
        current_period_start: new Date(
            subscription.current_period_start * 1000
        ),
        current_period_end: new Date(subscription.current_period_end * 1000),
        created: new Date(subscription.created * 1000),
        ended_at: subscription.ended_at
            ? new Date(subscription.ended_at * 1000)
            : null,
        trial_start: subscription.trial_start
            ? new Date(subscription.trial_start * 1000)
            : null,
        trial_end: subscription.trial_end
            ? new Date(subscription.trial_end * 1000)
            : null,
    }
    const result = await client
        .db(dbName)
        .collection('subscriptions')
        .updateOne(
            { user_id: new ObjectId(uuid), _id: subscription.id },
            { $set: subscriptionData },
            { upsert: true }
        )

    console.log('manageSubscriptionStatusChange: update: ', result)

    if (result.upsertedCount || result.modifiedCount) {
        console.log(
            `Inserted/updated subscription [${subscription.id}] for user [${uuid}]`
        )
    } else {
        console.log(
            `manageSubscriptionStatusChange: Subscription for user [${uuid}] was not updated.`,
            result
        )
    }

    if (createAction && subscription.default_payment_method && uuid) {
        await copyBillingDetailsToCustomer(
            uuid,
            subscription.default_payment_method
        )
    }
}

Sync with Stripe

Syncing Stripe Products with Your Local Database

To ensure that your local database reflects your current Stripe products, you can utilize the provided syncing utility. First create DB functions, then use them with the syncWithStripe function in an api endpoint. You can then create a simple button in your app that triggers the sync function.

Note: If you add the webhookHandler shown above to an api route, your Database will automatically stay in sync with Stripe Products, Prices, and Subscriptions.

Integration Steps:

1. Add the Syncing Endpoint:

Set up an API route in your Next.js project that uses the sync utility:

// pages/api/syncStripe.js
import { syncWithStripe } from 'next-stripe-helper';

const dbOperations = {
    getAllLocalProducts: async () => { /* fetch all products from the DB */ },
    addProduct: async (product) => { /* add new product to the DB */ },
    updateProduct: async (product) => { /* update existing product in the DB */ },
};

export default async (req, res) => {
    if (req.method === 'POST') {
        const result = await syncWithStripe(dbOperations);

        if (result.success) {
            res.status(200).json({ message: result.message });
        } else {
            res.status(500).json({ error: result.error, details: result.details });
        }
    } else {
        res.status(405).end(); // Method Not Allowed
    }
};

Configuration

1. Environment Variables: Ensure you have set the STRIPE_WEBHOOK_SECRET_LIVE or STRIPE_WEBHOOK_SECRET environment variables in your .env.local (or other environment-specific .env files). With Next.js, you can access these environment variables using process.env.

2. Stripe Dashboard: Configure your Stripe dashboard to send webhooks to https://your-domain.com/api/stripe-webhook.

Important Notes

• As with the general use-case, you need to provide the upsertProduct, upsertPrice, and manageSubscriptionChange callback functions. These functions will handle the various events as they occur on Stripe.

• Always handle errors gracefully. The provided webhook handler has built-in error handling, but you may want to extend or customize this for your specific needs.

Deployment

When deploying your Next.js application, make sure to include your Stripe webhook secret in your production environment variables or secrets management solution.

Error Handling

All utility functions incorporate internal error handling. You can catch these errors using try/catch. Ensure your project provides meaningful and appropriate error handling based on your application's needs.

Contributing

Feel free to contribute to the project by submitting a pull request or raising an issue.

License

MIT License