ShipEngine Integration with Next.js

Overview

Features

Prerequisites

Getting Started

1. Clone the repository

git clone https://github.com/yourusername/shipengine-with-nextjs.git
cd shipengine-with-nextjs

2. Install dependencies

npm install
# or
yarn install

3. Set up environment variables

SHIPENGINE_API_KEY=your_api_key_here
# Optional: Add specific carrier IDs if you have them
SHIPENGINE_FIRST_COURIER=carrier_id_1
SHIPENGINE_SECOND_COURIER=carrier_id_2
SHIPENGINE_THIRD_COURIER=carrier_id_3
SHIPENGINE_FOURTH_COURIER=carrier_id_4
SHIPENGINE_FIFTH_COURIER=carrier_id_5

4. Run the development server

npm run dev
# or
yarn dev

Project Structure

├── app/ # Next.js app directory
│ ├── api/ # API routes
│ │ └── shipengine/ # ShipEngine API endpoints
│ │ ├── get-rates/ # Shipping rates endpoint
│ │ ├── label/ # Label creation endpoint
│ │ └── tracking/ # Tracking endpoint
│ ├── components/ # React components
│ │ ├── Footer.tsx # Footer component
│ │ └── Navbar.tsx # Navigation component
│ ├── tracking/ # Tracking page
│ ├── globals.css # Global styles
│ ├── layout.tsx # Root layout
│ └── page.tsx # Home page
├── lib/ # Utility functions
│ ├── data.ts # Sample data
│ ├── shipEngine.ts # ShipEngine client setup
│ └── types.ts # TypeScript types
├── public/ # Static assets
├── .env.local # Environment variables (create this)
├── next.config.js # Next.js configuration
├── package.json # Project dependencies
├── README.md # Project documentation
└── tsconfig.json # TypeScript configuration

Integration Guide

1. Setting Up ShipEngine Client

// lib/shipEngine.ts
import { ShipEngine } from 'shipengine';
export const shipengine = new ShipEngine(process.env.SHIPENGINE_API_KEY!);

2. Creating API Routes

Shipping Rates API

// app/api/shipengine/get-rates/route.ts
import { shipengine } from '@/lib/shipEngine';
import { NextResponse } from 'next/server';
export async function POST(request: Request) {
 try {
 const { toAddress } = await request.json();
 
 // Define shipment details
 const shipmentDetails = {
 rateOptions: {
 carrierIds: [
 // Your carrier IDs
 ],
 },
 shipment: {
 validateAddress: 'validate_and_clean',
 shipTo: toAddress,
 shipFrom: {
 // Your warehouse address
 },
 packages: [
 // Package details
 ],
 },
 };
 
 // Get rates from ShipEngine
 const ratesResult = await shipengine.getRatesWithShipmentDetails(shipmentDetails);
 
 return NextResponse.json(ratesResult);
 } catch (error) {
 console.error('Error getting rates:', error);
 return NextResponse.json({ error: 'Failed to get shipping rates' }, { status: 500 });
 }
}

Label Creation API

// app/api/shipengine/label/route.ts
import { shipengine } from '@/lib/shipEngine';
import { NextResponse } from 'next/server';
export async function POST(request: Request) {
 try {
 const { rateId } = await request.json();
 
 if (!rateId) {
 return NextResponse.json({ error: 'Rate ID is required' }, { status: 400 });
 }
 
 // Create label using the selected rate
 const label = await shipengine.createLabelFromRate({
 rateId,
 validateAddress: 'validate_and_clean',
 });
 
 return NextResponse.json(label);
 } catch (error) {
 console.error('Error creating label:', error);
 return NextResponse.json({ error: 'Failed to create shipping label' }, { status: 500 });
 }
}

Tracking API

// app/api/shipengine/tracking/[labelId]/route.ts
import { shipengine } from '@/lib/shipEngine';
import { NextResponse } from 'next/server';
export async function GET(
 request: Request,
 { params }: { params: { labelId: string } }
) {
 try {
 const labelId = params.labelId;
 
 if (!labelId) {
 return NextResponse.json({ error: 'Label ID is required' }, { status: 400 });
 }
 
 // Track shipment using label ID
 const tracking = await shipengine.trackUsingLabelId({
 labelId,
 });
 
 return NextResponse.json(tracking);
 } catch (error) {
 console.error('Error tracking shipment:', error);
 return NextResponse.json({ error: 'Failed to track shipment' }, { status: 500 });
 }
}

3. Frontend Implementation

Fetching Shipping Rates

const fetchRates = async () => {
 try {
 setLoading(true);
 setError('');
 
 const response = await fetch('/api/shipengine/get-rates', {
 method: 'POST',
 headers: {
 'Content-Type': 'application/json',
 },
 body: JSON.stringify({
 toAddress: shippingAddress,
 }),
 });
 
 const data = await response.json();
 
 if (!response.ok) {
 throw new Error(data.error || 'Failed to get shipping rates');
 }
 
 setRates(data.rates);
 } catch (error) {
 setError(error.message);
 } finally {
 setLoading(false);
 }
};

Creating a Shipping Label

const createLabel = async () => {
 try {
 setLabelLoading(true);
 setError('');
 
 const response = await fetch('/api/shipengine/label', {
 method: 'POST',
 headers: {
 'Content-Type': 'application/json',
 },
 body: JSON.stringify({
 rateId,
 }),
 });
 
 const data = await response.json();
 
 if (!response.ok) {
 throw new Error(data.error || 'Failed to create shipping label');
 }
 
 setLabel(data);
 } catch (error) {
 setError(error.message);
 } finally {
 setLabelLoading(false);
 }
};

Tracking a Shipment

const trackShipment = async (labelId) => {
 try {
 setTrackingLoading(true);
 setTrackingError('');
 
 const response = await fetch(`/api/shipengine/tracking/${labelId}`);
 const data = await response.json();
 
 if (!response.ok) {
 throw new Error(data.error || 'Failed to track shipment');
 }
 
 setTrackingData(data);
 } catch (error) {
 setTrackingError(error.message);
 } finally {
 setTrackingLoading(false);
 }
};

Best Practices

Resources