How to Integrate Printful with V0

Start by prompting V0 to create the React components for your merchandise storefront. A print-on-demand store typically needs at minimum a product listing page with a grid of products, and a product detail page with variant selection and an add-to-cart or buy button. For the product listing, describe to V0 how many columns you want in the grid, what information to show per card (product image, name, starting price), and how the grid should respond across screen sizes. V0 generates responsive Tailwind CSS grids well — specify mobile-first requirements like 'one column on mobile, two on tablet, three on desktop'. For the product detail page, specify the components you need: a large product image (or image gallery for multiple color variants), a name and description section, size/color variant selectors, quantity input, price display, and a prominent purchase button. V0 can also generate a cart system with React state management if you want customers to add multiple items before checkout. A key design decision: for print-on-demand stores, the product mockup images (showing your design on the actual product) are more important than generic stock photos. Tell V0 to render the product image prominently and design the variant selectors so switching between color variants can update the displayed image. V0 will generate the components with placeholder image URLs. The real product data, including actual mockup image URLs from Printful, will be fetched through your API routes in later steps. Confirm the generated fetch calls reference the correct API route paths before moving on.

Create the server-side API route that fetches your product catalog from Printful. Printful's API uses Bearer token authentication — your API key goes in the Authorization header as 'Bearer YOUR_API_KEY'. Printful's API base URL is https://api.printful.com. The primary endpoints you need are: - GET /store/products — lists all products in your Printful store with basic information - GET /store/products/{id} — returns full product details including all variants with their prices, sizes, colors, and stock availability The store/products endpoint returns an array of product objects, each with an id, name, thumbnail_url (a small preview image), variants (list of available variants), and sync_variants (detailed variant information with prices and stock status). The thumbnail_url is what you display in the product listing grid. For the product detail endpoint, the sync_variants array contains each combination of size and color as a separate variant object with its own price, sku, availability_status, and main_category_id. Parse this into a usable structure: group by color to create the color selector options, and for each color collect the available sizes. Printful's API includes rate limits — 120 requests per minute for most endpoints. For a product catalog that does not change frequently, cache the API response in your Next.js route using the Next.js fetch cache with revalidate: 3600 (1 hour). This prevents hitting rate limits and speeds up page loads significantly. The Printful API response format includes a top-level 'code' (200 for success) and 'result' key containing the actual data. Always check response.code === 200 before processing the result.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface PrintfulVariant {
4  id: number;
5  name: string;
6  retail_price: string;
7  availability_status: string;
8  color: string;
9  size: string;
10}
11
12interface PrintfulProduct {
13  id: number;
14  name: string;
15  thumbnail_url: string;
16  sync_variants: PrintfulVariant[];
17}
18
19export async function GET(request: NextRequest) {
20  try {
21    const response = await fetch('https://api.printful.com/store/products', {
22      headers: {
23        Authorization: `Bearer ${process.env.PRINTFUL_API_KEY}`,
24        'Content-Type': 'application/json',
25      },
26      // Cache for 1 hour — product catalogs do not change frequently
27      next: { revalidate: 3600 },
28    });
29
30    if (!response.ok) {
31      const error = await response.json();
32      return NextResponse.json(
33        { error: error.error?.message || 'Failed to fetch products' },
34        { status: response.status }
35      );
36    }
37
38    const data = await response.json();
39
40    if (data.code !== 200) {
41      return NextResponse.json(
42        { error: 'Printful API returned an error' },
43        { status: 500 }
44      );
45    }
46
47    // Transform Printful products into a simplified format
48    const products = data.result.map((item: any) => ({
49      id: item.id,
50      name: item.name,
51      thumbnailUrl: item.thumbnail_url,
52      variantCount: item.variants,
53      // Get starting price from the lowest-priced variant
54      startingPrice: item.sync_variants
55        ? Math.min(...item.sync_variants.map((v: any) => parseFloat(v.retail_price || '0')))
56        : null,
57    }));
58
59    return NextResponse.json({ products });
60  } catch (error) {
61    console.error('Printful products fetch error:', error);
62    return NextResponse.json(
63      { error: 'Failed to fetch product catalog' },
64      { status: 500 }
65    );
66  }
67}

When a customer completes payment, your app needs to create a Printful order to trigger manufacturing and fulfillment. This is done via a POST to Printful's /orders endpoint. The order creation request requires the recipient's shipping address, the list of items (each item specifies a sync_variant_id and quantity), and optional settings like shipping method. Printful uses your API key to associate the order with your store and bill your Printful account for the production and shipping costs. For the order items array, each item needs: sync_variant_id (the specific variant ID from your Printful product catalog — not a generic product ID but a specific size+color combination), and quantity. The retail_price field is optional but helps with Printful's reporting. The shipping method options for Printful are 'STANDARD', 'EXPRESS', and 'OVERNIGHT' — check Printful's documentation for availability by destination country. 'STANDARD' is the default. Critical security point: the order creation API route should verify payment was actually completed before calling Printful. If you are using Stripe, call Printful only inside the Stripe webhook handler for the checkout.session.completed event — never trust a client-side signal that payment succeeded. Creating a Printful order deducts from your Printful account balance even if the customer's payment failed. The confirm field in the order request controls whether Printful immediately sends the order to production (confirm: true) or creates it as a draft for review (confirm: false). For automated checkout flows, use confirm: true. For orders that need manual review before printing, use confirm: false and review them in the Printful dashboard.

1import { NextRequest, NextResponse } from 'next/server';
2
3interface OrderRecipient {
4  name: string;
5  address1: string;
6  city: string;
7  state_code: string;
8  country_code: string;
9  zip: string;
10  email?: string;
11  phone?: string;
12}
13
14interface OrderItem {
15  sync_variant_id: number;
16  quantity: number;
17}
18
19export async function POST(request: NextRequest) {
20  try {
21    const { recipient, items }: { recipient: OrderRecipient; items: OrderItem[] } = await request.json();
22
23    if (!recipient || !items || items.length === 0) {
24      return NextResponse.json(
25        { error: 'recipient and items are required' },
26        { status: 400 }
27      );
28    }
29
30    const orderResponse = await fetch('https://api.printful.com/orders', {
31      method: 'POST',
32      headers: {
33        Authorization: `Bearer ${process.env.PRINTFUL_API_KEY}`,
34        'Content-Type': 'application/json',
35      },
36      body: JSON.stringify({
37        recipient,
38        items: items.map((item) => ({
39          sync_variant_id: item.sync_variant_id,
40          quantity: item.quantity,
41        })),
42        shipping: 'STANDARD',
43        confirm: true, // Send to production immediately
44      }),
45    });
46
47    if (!orderResponse.ok) {
48      const error = await orderResponse.json();
49      console.error('Printful order creation error:', error);
50      return NextResponse.json(
51        { error: error.error?.message || 'Failed to create Printful order' },
52        { status: orderResponse.status }
53      );
54    }
55
56    const data = await orderResponse.json();
57
58    if (data.code !== 200) {
59      return NextResponse.json(
60        { error: 'Order creation failed' },
61        { status: 500 }
62      );
63    }
64
65    return NextResponse.json(
66      {
67        orderId: data.result.id,
68        externalId: data.result.external_id,
69        status: data.result.status,
70        estimatedShippingDate: data.result.shipping_service_name,
71      },
72      { status: 201 }
73    );
74  } catch (error) {
75    console.error('Printful order error:', error);
76    return NextResponse.json(
77      { error: 'Internal server error creating order' },
78      { status: 500 }
79    );
80  }
81}

Add your Printful API key to Vercel's environment variables so your API routes can authenticate with Printful's API. Go to Vercel Dashboard → your project → Settings → Environment Variables. Add PRINTFUL_API_KEY with the value of your Printful API token. Find this in Printful Dashboard → Settings → API → Generate API Token. The token is a long alphanumeric string. Do not add the NEXT_PUBLIC_ prefix — this key is server-only and must never appear in browser code. Set this variable for Production, Preview, and Development environments. For local development, add it to your .env.local file. For a complete checkout flow, you also need to connect Printful with Stripe. The recommended pattern is: 1. User clicks 'Buy Now' on your V0 product page 2. Your Stripe checkout route creates a Checkout Session, storing the Printful sync_variant_id and quantity in the Stripe session metadata 3. Stripe collects payment and sends a checkout.session.completed webhook event to your server 4. Your Stripe webhook handler reads the metadata, collects the shipping address from the Stripe session, and calls your Printful order creation route 5. Printful manufactures and ships the item directly to the customer This sequence ensures Printful orders are only created for confirmed payments. The session metadata is the bridge between Stripe and Printful — store the Printful variant IDs and quantities there when creating the Checkout Session. After saving PRINTFUL_API_KEY and redeploying, test the product catalog endpoint first to confirm authentication works before testing order creation.

1// In your Stripe checkout route — add Printful variant info to metadata
2const session = await stripe.checkout.sessions.create({
3  mode: 'payment',
4  line_items: [{ price_data: { currency: 'usd', product_data: { name: productName }, unit_amount: priceInCents }, quantity: 1 }],
5  success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/order-confirmed`,
6  cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/shop`,
7  // Store Printful variant info for fulfillment
8  metadata: {
9    printful_variant_id: String(variantId),
10    quantity: String(quantity),
11    customer_name: customerName,
12  },
13  shipping_address_collection: {
14    allowed_countries: ['US', 'CA', 'GB', 'DE', 'FR', 'AU'],
15  },
16});

Test the end-to-end flow from product browsing to Printful order creation before launching. Start with the product catalog — load your V0 product listing page and verify it shows your Printful products with real mockup images and prices. For order creation testing, Printful has a 'draft' mode: when you create an order with confirm: false, the order appears in your Printful Dashboard under Orders with 'Draft' status. You can review it there without sending it to production. Change your test API route to use confirm: false during initial testing so you do not accidentally incur production costs. For a full Stripe + Printful test: complete a checkout using Stripe's test card (4242 4242 4242 4242) with a test shipping address. Verify the Stripe webhook fires (check Stripe Dashboard → Webhooks), the webhook handler calls the Printful API, and a new order appears in Printful Dashboard. Check Vercel Function Logs for any errors during the webhook processing. Common issues at this stage include: the sync_variant_id being from the wrong store (if you have multiple Printful stores, make sure you are using variant IDs from the store that matches your API key), the shipping address fields not matching Printful's expected format (state_code should be a 2-letter US state abbreviation, country_code should be ISO 2-letter), and the Printful API rejecting the order due to address validation failures. When you are satisfied the flow works correctly, change confirm: true for production order creation. Monitor your first few live orders in both Stripe Dashboard (payment confirmed) and Printful Dashboard (order in production) to catch any edge cases before scaling.