Skip to main content
Feel free to use our quick-start script to get started inside a new Next.js project:
Terminal
# Inside a new Next.js project
npx spaire-init
Consider following this guide while using the Spaire Sandbox Environment. This will allow you to test your integration without affecting your production data. A complete code-example of this guide can be found on GitHub.

​
Install the Spaire JavaScript SDK

To get started, you need to install the Spaire JavaScript SDK and the Spaire Nextjs helper package. You can do this by running the following command:
Terminal
pnpm install @spaire/sdk @spaire/nextjs

​
Setting up environment variables

​
Spaire Access Token

To authenticate with Spaire, you need to create an access token, and supply it to Next.js using a SPAIRE_ACCESS_TOKEN environment variable. You can create an organization access token from your organization settings.

​
Configuring a Spaire API Client

To interact with the Spaire API, you need to create a new instance of the Spaire class. This class uses the provided access token to authenticate with the Spaire API. 
// src/spaire.ts
import { Spaire } from "@spaire/sdk";

export const api = new Spaire({
  accessToken: process.env.SPAIRE_ACCESS_TOKEN!,
  server: "sandbox", // Use this option if you're using the sandbox environment - else use 'production' or omit the parameter
});
Remember to replace sandbox with production when you’re ready to switch to the production environment.

​
Generating Spaire Checkout Sessions

Next up, we need to create a checkout endpoint to handle the creation of checkout sessions. Go ahead and create a new GET route in Next.js. 
// src/app/checkout/route.ts
import { Checkout } from "@spaire/nextjs";

export const GET = Checkout({
  accessToken: process.env.SPAIRE_ACCESS_TOKEN!,
  successUrl: "https://your-app.com/confirmation?checkout_id={CHECKOUT_ID}",
  server: "sandbox", // Use this option if you're using the sandbox environment - else use 'production' or omit the parameter
});

​
Handling Spaire Webhooks

Spaire can send you events about various things happening in your organization. This is very useful for keeping your database in sync with Spaire checkouts, orders, subscriptions, etc. Configuring a webhook is simple. Head over to your organization’s settings page and click on the “Add Endpoint” button to create a new webhook.

​
Tunneling webhook events to your local development environment

If you’re developing locally, you can use a tool like ngrok to tunnel webhook events to your local development environment. This will allow you to test your webhook handlers without deploying them to a live server. Run the following command to start an ngrok tunnel:
Terminal
ngrok http 3000

​
Add Webhook Endpoint

  1. Point the Webhook to your-app.com/api/webhook/spaire. This must be an absolute URL which Spaire can reach. If you use ngrok, the URL will look something like this: https://<your-ngrok-id>.ngrok-free.app/api/webhook/spaire.
  2. Select which events you want to be notified about. You can read more about the available events in the Events section.
  3. Generate a secret key to sign the requests. This will allow you to verify that the requests are truly coming from Spaire.
  4. Add the secret key to your environment variables.
Terminal
# .env
SPAIRE_ACCESS_TOKEN="spaire_pat..."
SPAIRE_WEBHOOK_SECRET="..."

​
Setting up the Webhook handler

// src/app/api/webhook/spaire/route.ts
import { Webhooks } from "@spaire/nextjs";

export const POST = Webhooks({
	webhookSecret: process.env.SPAIRE_WEBHOOK_SECRET,
	onPayload: async (payload) => // Handle payload...
});
The webhook event is now verified and you can proceed to handle the payload data.

​
Handling Webhook Events

Depending on which events you’ve subscribed to, you’ll receive different payloads. This is where you can update your database, send notifications, etc. 
// src/app/api/webhook/spaire/route.ts
import { Webhooks } from "@spaire/nextjs";

export const POST = Webhooks({
  webhookSecret: process.env.SPAIRE_WEBHOOK_SECRET,
  onPayload: async (payload) => ...,
  onOrderCreated: async (order) => ...,
  onCustomerStateChanged: async (customerState) => ...,
  ...
});

​
Notifying the client about the event

If you’re building a real-time application, you might want to notify the client about the event. On the confirmation-page, you can listen for the checkout.updated event and update the UI accordingly when it reaches the succeeded status.

​
Conclusion

If you have issues or need support, feel free to join our Discord.