Invoice Management Patterns | Bootspring Docs

Generate, retrieve, and manage invoices with Stripe.

Overview#

Invoices provide billing history and receipts. This pattern covers:

Retrieving invoice history
Invoice webhooks
Creating custom invoices
Displaying invoices to users
Handling failed payments

Prerequisites#

npm install stripe

Get Invoice History#

Retrieve a customer's invoices from Stripe.

// lib/billing.ts
import { stripe } from '@/lib/stripe'
import { prisma } from '@/lib/db'

interface Invoice {
  id: string
  number: string | null
  status: string | null
  amount: number
  currency: string
  created: Date
  dueDate: Date | null
  paidAt: Date | null
  pdfUrl: string | null
  hostedUrl: string | null
}

export async function getInvoices(userId: string, limit = 10): Promise<Invoice[]> {
  const user = await prisma.user.findUnique({
    where: { id: userId }
  })

  if (!user?.stripeCustomerId) {
    return []
  }

  const invoices = await stripe.invoices.list({
    customer: user.stripeCustomerId,
    limit,
    expand: ['data.subscription']
  })

  return invoices.data.map(invoice => ({
    id: invoice.id,
    number: invoice.number,
    status: invoice.status,
    amount: invoice.amount_due,
    currency: invoice.currency,
    created: new Date(invoice.created * 1000),
    dueDate: invoice.due_date ? new Date(invoice.due_date * 1000) : null,
    paidAt: invoice.status_transitions.paid_at
      ? new Date(invoice.status_transitions.paid_at * 1000)
      : null,
    pdfUrl: invoice.invoice_pdf,
    hostedUrl: invoice.hosted_invoice_url
  }))
}

Invoice API Route#

API endpoint to fetch invoices.

// app/api/billing/invoices/route.ts
import { auth } from '@/auth'
import { getInvoices } from '@/lib/billing'
import { NextResponse } from 'next/server'

export async function GET(request: Request) {
  const session = await auth()

  if (!session?.user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const { searchParams } = new URL(request.url)
  const limit = parseInt(searchParams.get('limit') ?? '10')

  try {
    const invoices = await getInvoices(session.user.id, limit)
    return NextResponse.json({ invoices })
  } catch (error) {
    console.error('Failed to fetch invoices:', error)
    return NextResponse.json(
      { error: 'Failed to fetch invoices' },
      { status: 500 }
    )
  }
}

Invoice List Component#

Display invoice history to users.

// components/billing/InvoiceList.tsx
'use client'

import { useState, useEffect } from 'react'
import { FileText, Download, ExternalLink } from 'lucide-react'
import { formatCurrency, formatDate } from '@/lib/utils'

interface Invoice {
  id: string
  number: string | null
  status: string | null
  amount: number
  currency: string
  created: string
  pdfUrl: string | null
  hostedUrl: string | null
}

export function InvoiceList() {
  const [invoices, setInvoices] = useState<Invoice[]>([])
  const [loading, setLoading] = useState(true)

  useEffect(() => {
    fetch('/api/billing/invoices')
      .then(res => res.json())
      .then(data => setInvoices(data.invoices))
      .catch(console.error)
      .finally(() => setLoading(false))
  }, [])

  if (loading) {
    return <InvoiceListSkeleton />
  }

  if (invoices.length === 0) {
    return (
      <div className="rounded-lg border p-8 text-center">
        <FileText className="mx-auto h-8 w-8 text-gray-400" />
        <p className="mt-2 text-gray-500">No invoices yet</p>
      </div>
    )
  }

  return (
    <div className="divide-y rounded-lg border">
      {invoices.map(invoice => (
        <div key={invoice.id} className="flex items-center justify-between p-4">
          <div>
            <p className="font-medium">
              Invoice {invoice.number ?? invoice.id.slice(0, 8)}
            </p>
            <p className="text-sm text-gray-500">
              {formatDate(new Date(invoice.created))}
            </p>
          </div>

          <div className="flex items-center gap-4">
            <StatusBadge status={invoice.status} />

            <span className="font-medium">
              {formatCurrency(invoice.amount / 100, invoice.currency)}
            </span>

            <div className="flex gap-2">
              {invoice.pdfUrl && (
                <a
                  href={invoice.pdfUrl}
                  target="_blank"
                  rel="noopener noreferrer"
                  className="rounded p-2 hover:bg-gray-100"
                  title="Download PDF"
                >
                  <Download className="h-4 w-4" />
                </a>
              )}
              {invoice.hostedUrl && (
                <a
                  href={invoice.hostedUrl}
                  target="_blank"
                  rel="noopener noreferrer"
                  className="rounded p-2 hover:bg-gray-100"
                  title="View Invoice"
                >
                  <ExternalLink className="h-4 w-4" />
                </a>
              )}
            </div>
          </div>
        </div>
      ))}
    </div>
  )
}

function StatusBadge({ status }: { status: string | null }) {
  const styles = {
    paid: 'bg-green-100 text-green-800',
    open: 'bg-amber-100 text-amber-800',
    void: 'bg-gray-100 text-gray-800',
    uncollectible: 'bg-red-100 text-red-800',
    draft: 'bg-blue-100 text-blue-800'
  }[status ?? 'draft'] ?? 'bg-gray-100 text-gray-800'

  return (
    <span className={`rounded-full px-2 py-1 text-xs ${styles}`}>
      {status ?? 'Unknown'}
    </span>
  )
}

Invoice Webhooks#

Handle invoice-related webhook events.

// lib/webhook-handlers.ts
import { stripe } from '@/lib/stripe'
import { prisma } from '@/lib/db'
import { sendEmail } from '@/lib/email'
import Stripe from 'stripe'

export async function handleInvoicePaid(invoice: Stripe.Invoice) {
  const customerId = invoice.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) return

  // Store invoice record locally
  await prisma.invoice.upsert({
    where: { stripeInvoiceId: invoice.id },
    create: {
      userId: user.id,
      stripeInvoiceId: invoice.id,
      number: invoice.number,
      amount: invoice.amount_paid,
      currency: invoice.currency,
      status: 'paid',
      paidAt: new Date()
    },
    update: {
      status: 'paid',
      paidAt: new Date()
    }
  })

  // Send receipt email
  await sendEmail({
    to: user.email,
    subject: `Receipt for Invoice ${invoice.number}`,
    template: 'invoice-receipt',
    data: {
      invoiceNumber: invoice.number,
      amount: invoice.amount_paid,
      currency: invoice.currency,
      pdfUrl: invoice.invoice_pdf
    }
  })
}

export async function handleInvoicePaymentFailed(invoice: Stripe.Invoice) {
  const customerId = invoice.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) return

  // Update invoice status
  await prisma.invoice.upsert({
    where: { stripeInvoiceId: invoice.id },
    create: {
      userId: user.id,
      stripeInvoiceId: invoice.id,
      number: invoice.number,
      amount: invoice.amount_due,
      currency: invoice.currency,
      status: 'failed'
    },
    update: {
      status: 'failed'
    }
  })

  // Send payment failed notification
  await sendEmail({
    to: user.email,
    subject: 'Payment Failed - Action Required',
    template: 'payment-failed',
    data: {
      amount: invoice.amount_due,
      currency: invoice.currency,
      updateUrl: `${process.env.NEXT_PUBLIC_URL}/settings/billing`
    }
  })
}

export async function handleUpcomingInvoice(invoice: Stripe.Invoice) {
  const customerId = invoice.customer as string

  const user = await prisma.user.findFirst({
    where: { stripeCustomerId: customerId }
  })

  if (!user) return

  // Send reminder for upcoming charge
  await sendEmail({
    to: user.email,
    subject: 'Upcoming Invoice',
    template: 'invoice-upcoming',
    data: {
      amount: invoice.amount_due,
      currency: invoice.currency,
      date: new Date((invoice.next_payment_attempt ?? invoice.created) * 1000)
    }
  })
}

Create Custom Invoice#

Generate invoices for one-off charges.

// lib/billing.ts
export async function createCustomInvoice(
  userId: string,
  items: { description: string; amount: number }[]
) {
  const user = await prisma.user.findUnique({
    where: { id: userId }
  })

  if (!user?.stripeCustomerId) {
    throw new Error('No billing account')
  }

  // Create invoice items
  for (const item of items) {
    await stripe.invoiceItems.create({
      customer: user.stripeCustomerId,
      amount: item.amount, // in cents
      currency: 'usd',
      description: item.description
    })
  }

  // Create and finalize invoice
  const invoice = await stripe.invoices.create({
    customer: user.stripeCustomerId,
    auto_advance: true, // Auto-finalize
    collection_method: 'send_invoice',
    days_until_due: 30
  })

  // Send the invoice
  await stripe.invoices.sendInvoice(invoice.id)

  return invoice
}

Best Practices#

Store invoices locally - Keep a record for quick access
Send receipt emails - Always confirm successful payments
Handle failures gracefully - Notify users and provide update links
Show invoice history - Let users access past invoices easily
Support PDF downloads - Users need invoices for accounting

Stripe - Stripe setup
Webhooks - Webhook handling
Subscriptions - Subscription invoices