Integrate Stripe with UploadThing

Synchronizing Digital Asset Permissions via Stripe Webhooks

In a modern Next.js ecosystem, the intersection of commerce and file management requires a seamless configuration of event-driven architecture. By bridging Stripe’s payment triggers with UploadThing’s simple file-hosting logic, developers can create gatekept experiences where uploads are only permitted upon successful checkout. Similar to how developers bridge algolia and convex to sync real-time data with search indices, connecting Stripe to your upload pipeline ensures that your storage costs are always offset by verified revenue.

To begin, you must ensure your UPLOADTHING_SECRET and Stripe API key are correctly defined in your environment variables. This creates a secure handshake between the two services, preventing unauthorized users from consuming your bandwidth.

Orchestrating Middleware for Tier-Based Storage Limits

The most effective way to handle this integration is through a production-ready middleware or a custom UploadThing onUploadBegin callback. By querying the Stripe API within the upload route, you can verify if a user has exceeded their "Premium" storage quota before the file even hits the server.

1. Paid Content Marketplaces: A user pays for a "Digital Storefront" via Stripe Checkout. Once the checkout.session.completed webhook fires, the system unlocks specific FileRouter endpoints in UploadThing, allowing them to upload high-resolution product images.
2. Tiered SaaS Storage: Free users are restricted to 4MB uploads, while "Pro" subscribers—verified via Stripe metadata—gain access to 1GB video uploads through a dynamic uploadthing configuration.
3. Bounty-Based Asset Collection: In platforms where users are paid to provide data (e.g., training sets), Stripe Connect can be used to escrow funds, which are only released after a successful UploadThing server-side callback confirms the asset meets quality standards.

Validating Upload Entitlements through Stripe Metadata

When building this bridge, the primary challenge is ensuring that the file metadata in UploadThing reflects the payment status in Stripe. This setup guide recommends using Stripe's metadata field to store the userId or orgId that corresponds to your UploadThing file registry. This allows for effortless lookups during the indexing phase, much like the sophisticated pipelines used when integrating algolia and anthropic to generate AI-powered metadata for searchable assets.

 typescript
import { utapi } from "./server/uploadthing";
import { stripe } from "./lib/stripe";

export async function validateAndPurge(stripeSessionId: string, fileKey: string) {
  const session = await stripe.checkout.sessions.retrieve(stripeSessionId);
  
  // If payment failed or was cancelled, delete the orphaned upload
  if (session.payment_status !== 'paid') {
    await utapi.deleteFiles(fileKey);
    return { success: false, reason: "Payment verification failed" };
  }

  // Update metadata in your DB to link the Stripe record to the UploadThing key
  await db.asset.update({
    where: { fileKey },
    data: { isPaid: true, stripeId: session.id }
  });

  return { success: true };
}

Navigating the Lifecycle of Paid File Assets

Two major technical hurdles often arise when marrying these two platforms. First is Eventual Consistency: A user might upload a file exactly as their subscription expires. Your FileRouter must perform a live check against the Stripe API rather than relying on cached session data to prevent "zombie" uploads.

Second is Webhook Idempotency: Stripe may send the same event multiple times. If your logic triggers an UploadThing file move or deletion based on a charge.refunded event, you must ensure your backend tracks event IDs to avoid redundant API calls that could lead to data corruption or accidental file loss.

Accelerating Deployment with Pre-Configured Architectures

Building a production-ready bridge from scratch involves significant boilerplate for error handling, webhook signing, and type-safety. Utilizing a pre-configured boilerplate or starter kit saves dozens of hours by providing a battle-tested setup guide for these edge cases. It ensures that your Stripe webhooks and UploadThing callbacks communicate over a secure, authenticated channel from day one, allowing you to focus on the unique business logic of your application rather than the plumbing of file permissions.