How to Integrate Acuity Scheduling with V0

Open V0 at v0.dev and describe the appointment booking interface you want to create. For an Acuity integration, you have two visual options: a multi-step wizard (service selection → date/time picker → contact form → confirmation) or a simpler single-page layout with all fields visible. Multi-step wizards work well for service businesses with multiple appointment types because they guide users through the decision process without overwhelming them. Describe the appointment types you offer and the color scheme or style that matches your brand. When prompting V0, specify the API routes your component will call: /api/acuity/types for fetching appointment types, /api/acuity/availability for open time slots, and /api/acuity/book for creating the appointment. V0 will generate the component with fetch calls already stubbed out to these routes. Include the request body shapes in your prompt so V0 generates the correct data structures — for booking, Acuity requires at minimum a datetime (ISO 8601 format), appointmentTypeID, firstName, lastName, and email. After generating the component, use V0's preview to check the layout on both desktop and mobile. Acuity is used heavily on mobile by clients booking while on the go, so a responsive design is essential. Use V0's Git panel to push the generated code to your GitHub repository before moving to the API route creation step.

Create three Next.js API routes to handle the three main operations: fetching appointment types, checking availability, and creating bookings. All three use HTTP Basic Authentication with your Acuity User ID and API key. Basic Auth encodes credentials as base64(userId:apiKey) and passes them in the Authorization header as 'Basic {encoded}'. In Node.js, you can generate this with Buffer.from(`${userId}:${apiKey}`).toString('base64'). The GET /api/acuity/types route fetches all appointment types from https://acuityscheduling.com/api/v1/appointment-types. This returns an array of objects with id, name, duration, price, and description fields that your frontend uses to populate the service selection step. The GET /api/acuity/availability route accepts appointmentTypeID and date as query parameters and calls https://acuityscheduling.com/api/v1/availability/times. The date should be in YYYY-MM-DD format. The response is an array of available time slots as ISO 8601 datetime strings. The POST /api/acuity/book route receives the booking details from your form and calls https://acuityscheduling.com/api/v1/appointments to create the appointment. Required fields are datetime (the selected slot from the availability response), appointmentTypeID, firstName, lastName, and email. On success, Acuity returns the created appointment object with a confirmation ID. Acuity automatically sends a confirmation email to the client and adds the appointment to your connected calendar.

1// app/api/acuity/book/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const ACUITY_BASE = 'https://acuityscheduling.com/api/v1';
5
6function getAuthHeader() {
7  const userId = process.env.ACUITY_USER_ID;
8  const apiKey = process.env.ACUITY_API_KEY;
9  if (!userId || !apiKey) throw new Error('Acuity credentials not configured');
10  const encoded = Buffer.from(`${userId}:${apiKey}`).toString('base64');
11  return `Basic ${encoded}`;
12}
13
14export async function POST(request: NextRequest) {
15  let body: {
16    datetime: string;
17    appointmentTypeID: number;
18    firstName: string;
19    lastName: string;
20    email: string;
21    phone?: string;
22    notes?: string;
23  };
24
25  try {
26    body = await request.json();
27  } catch {
28    return NextResponse.json({ error: 'Invalid request body' }, { status: 400 });
29  }
30
31  const { datetime, appointmentTypeID, firstName, lastName, email } = body;
32
33  if (!datetime || !appointmentTypeID || !firstName || !lastName || !email) {
34    return NextResponse.json(
35      { error: 'datetime, appointmentTypeID, firstName, lastName, and email are required' },
36      { status: 400 }
37    );
38  }
39
40  try {
41    const response = await fetch(`${ACUITY_BASE}/appointments`, {
42      method: 'POST',
43      headers: {
44        Authorization: getAuthHeader(),
45        'Content-Type': 'application/json',
46      },
47      body: JSON.stringify(body),
48    });
49
50    const data = await response.json();
51
52    if (!response.ok) {
53      return NextResponse.json(
54        { error: data.message || 'Booking failed' },
55        { status: response.status }
56      );
57    }
58
59    return NextResponse.json({
60      success: true,
61      appointmentId: data.id,
62      confirmationPage: data.confirmationPage,
63      datetime: data.datetime,
64    });
65  } catch (error) {
66    const msg = error instanceof Error ? error.message : 'Unknown error';
67    return NextResponse.json({ error: msg }, { status: 500 });
68  }
69}

The booking route handles appointment creation, but you also need routes for fetching appointment types and checking availability. Create app/api/acuity/types/route.ts to return your appointment type catalog, and app/api/acuity/availability/route.ts to return open time slots for a given type and date. Both are GET routes that read query parameters, authenticate with Acuity's API using the same Basic Auth pattern from the previous step, and return the raw Acuity response to your frontend. For the availability route, validate the appointmentTypeID and date query parameters before calling Acuity. A missing or malformed date will cause a confusing Acuity error instead of a clear 400 response to your frontend. The date must be YYYY-MM-DD format — validate with a simple regex or Date.parse check before proxying the request. For the types route, you may want to filter or transform the Acuity response before returning it to the frontend. Acuity returns many fields per appointment type (including internal metadata), and your frontend only needs id, name, duration, price, and description. Filtering the response reduces payload size and simplifies the frontend component's data handling. Cache the types response for a few minutes since appointment types rarely change, using Vercel's fetch cache headers.

1// app/api/acuity/availability/route.ts
2import { NextRequest, NextResponse } from 'next/server';
3
4const ACUITY_BASE = 'https://acuityscheduling.com/api/v1';
5
6function getAuthHeader() {
7  const userId = process.env.ACUITY_USER_ID;
8  const apiKey = process.env.ACUITY_API_KEY;
9  if (!userId || !apiKey) throw new Error('Acuity credentials not configured');
10  const encoded = Buffer.from(`${userId}:${apiKey}`).toString('base64');
11  return `Basic ${encoded}`;
12}
13
14export async function GET(request: NextRequest) {
15  const { searchParams } = new URL(request.url);
16  const appointmentTypeID = searchParams.get('appointmentTypeID');
17  const date = searchParams.get('date');
18
19  if (!appointmentTypeID || !date) {
20    return NextResponse.json(
21      { error: 'appointmentTypeID and date are required' },
22      { status: 400 }
23    );
24  }
25
26  // Validate date format (YYYY-MM-DD)
27  if (!/^\d{4}-\d{2}-\d{2}$/.test(date)) {
28    return NextResponse.json(
29      { error: 'date must be in YYYY-MM-DD format' },
30      { status: 400 }
31    );
32  }
33
34  try {
35    const url = new URL(`${ACUITY_BASE}/availability/times`);
36    url.searchParams.set('appointmentTypeID', appointmentTypeID);
37    url.searchParams.set('date', date);
38
39    const response = await fetch(url.toString(), {
40      headers: { Authorization: getAuthHeader() },
41      next: { revalidate: 60 }, // Cache availability for 60 seconds
42    });
43
44    const data = await response.json();
45
46    if (!response.ok) {
47      return NextResponse.json(
48        { error: data.message || 'Failed to fetch availability' },
49        { status: response.status }
50      );
51    }
52
53    return NextResponse.json(data);
54  } catch (error) {
55    const msg = error instanceof Error ? error.message : 'Unknown error';
56    return NextResponse.json({ error: msg }, { status: 500 });
57  }
58}

Push your code to GitHub and add your Acuity credentials to Vercel. Open the Vercel Dashboard, select your project, go to Settings → Environment Variables, and add two variables: ACUITY_USER_ID (your numeric Acuity user ID) and ACUITY_API_KEY (your API key). Both are found in your Acuity account under Integrations → API → API Credentials. Neither variable should have the NEXT_PUBLIC_ prefix — these are server-side secrets used only in your API routes and must never reach the browser. Add both variables for Production, Preview, and Development environments. For local development, add them to your project's .env.local file as well (this file is gitignored by default in Next.js projects and is safe for local secrets). Set ACUITY_USER_ID=your_user_id and ACUITY_API_KEY=your_api_key in .env.local, then run npm run dev to test locally before deploying. After adding the variables, trigger a redeployment from the Vercel Deployments tab by clicking Redeploy on the latest deployment. Once deployed, test the complete booking flow from your live URL: check that appointment types load, availability shows open slots, and submitting the booking form creates an appointment visible in your Acuity calendar. Acuity sends confirmation emails automatically to the client email address provided in the booking form, so you can verify delivery by using your own email address during testing. For complex scheduling setups with multiple service providers or locations, RapidDev's team can help configure the Acuity API routing logic.