Build a Shipping Feature in 10 Minutes

What you will build

A shipping module that connects your application to real freight capacity. By the end of this tutorial, your app will be able to:

• -Accept origin and destination addresses
• -Get instant freight quotes across LTL, box truck, and cargo van
• -Book the selected option
• -Track the shipment in real time
• -Receive webhook notifications for delivery and exceptions

Step 1: Set up your Warp client

Minute 0 to 2. Create a simple wrapper around the Warp API. This handles authentication and provides clean methods for quoting, booking, and tracking. Here it is in Python and Node.js.

import requests

class WarpClient:
    BASE_URL = "https://api.wearewarp.com/api/v1"

    def __init__(self, api_key: str):
        self.headers = {
            "Content-Type": "application/json",
            "apikey": api_key
        }

    def quote(self, pickup_zip, delivery_zip, items):
        return requests.post(
            f"{self.BASE_URL}/freights/quote",
            headers=self.headers,
            json={
                "pickupDate": ["2026-04-07"],
                "pickupInfo": {"zipCode": pickup_zip},
                "deliveryInfo": {"zipCode": delivery_zip},
                "listItems": items
            }
        ).json()

    def book(self, quote_id, pickup_info, delivery_info, items):
        return requests.post(
            f"{self.BASE_URL}/freights/booking",
            headers=self.headers,
            json={
                "quoteId": quote_id,
                "pickupInfo": pickup_info,
                "deliveryInfo": delivery_info,
                "listItems": items
            }
        ).json()

    def track(self, tracking_numbers):
        return requests.post(
            f"{self.BASE_URL}/freights/tracking",
            headers=self.headers,
            json={"trackingNumbers": tracking_numbers}
        ).json()

warp = WarpClient("YOUR_API_KEY")

const BASE_URL = "https://api.wearewarp.com/api/v1";

class WarpClient {
  constructor(apiKey) {
    this.headers = {
      "Content-Type": "application/json",
      "apikey": apiKey,
    };
  }

  async quote(pickupZip, deliveryZip, items) {
    const res = await fetch(`${BASE_URL}/freights/quote`, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({
        pickupDate: ["2026-04-07"],
        pickupInfo: { zipCode: pickupZip },
        deliveryInfo: { zipCode: deliveryZip },
        listItems: items,
      }),
    });
    return res.json();
  }

  async book(quoteId, pickupInfo, deliveryInfo, items) {
    const res = await fetch(`${BASE_URL}/freights/booking`, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({
        quoteId,
        pickupInfo,
        deliveryInfo,
        listItems: items,
      }),
    });
    return res.json();
  }

  async track(trackingNumbers) {
    const res = await fetch(`${BASE_URL}/freights/tracking`, {
      method: "POST",
      headers: this.headers,
      body: JSON.stringify({ trackingNumbers }),
    });
    return res.json();
  }
}

const warp = new WarpClient("YOUR_API_KEY");

Replace YOUR_API_KEY with the key from your Warp dashboard. All requests go to https://api.wearewarp.com/api/v1 with the apikey header for authentication.

Step 2: Get freight quotes

Minute 2 to 4. Call the quote method with item dimensions and origin/destination zip codes. Warp returns pricing across available vehicle types and service levels. If you omit the vehicle type, Warp selects the right asset for your freight automatically.

# Define items to ship
items = [{
    "name": "Pallet - Electronics",
    "length": 48, "width": 40, "height": 48,
    "sizeUnit": "in",
    "totalWeight": 800, "weightUnit": "lb",
    "quantity": 2,
    "packaging": "pallet",
    "stackable": False
}]

# Get quotes from LA to Phoenix
response = warp.quote("90001", "85001", items)

# Parse the response
quote = response["data"]
print(f"Quote ID: {quote['quoteId']}")
print(f"Price: ${quote['totalCost']}")
print(f"Transit: {quote['transitDays']} days")
print(f"Carrier: {quote['carrierName']}")

The response includes a quoteId that you pass to the booking endpoint in the next step. Quotes include the carrier name, transit time, total cost, and available pickup/delivery windows.

Step 3: Book the shipment

Minute 4 to 6. Pass the quote ID along with full pickup and delivery details. Warp confirms the booking and returns a tracking number immediately.

# Full pickup and delivery details
pickup_info = {
    "zipCode": "90001",
    "city": "Los Angeles",
    "state": "CA",
    "street": "123 Warehouse Blvd",
    "contactName": "Dispatch Team",
    "phone": "3105551234",
    "specialInstruction": "Dock 4, call 30 min before arrival"
}

delivery_info = {
    "zipCode": "85001",
    "city": "Phoenix",
    "state": "AZ",
    "street": "456 Distribution Dr",
    "contactName": "Receiving Dock",
    "phone": "6025551234",
    "specialInstruction": "Receiving hours 7am to 3pm"
}

# Book with the quote ID from step 2
booking = warp.book(quote["quoteId"], pickup_info, delivery_info, items)

shipment = booking["data"]
print(f"Shipment ID: {shipment['shipmentId']}")
print(f"Tracking: {shipment['trackingNumber']}")
print(f"Status: {shipment['status']}")

The booking response includes the shipmentId, trackingNumber, and orderId. Save all three. You need the tracking number for status checks and the order ID for invoices and documents later.

Step 4: Track the shipment

Minute 6 to 8. Use the tracking number to get the current status, location, and full event history. Warp provides granular statuses from pickup through delivery, not just "in transit" and "delivered."

# Track using the tracking number from the booking response
result = warp.track([shipment["trackingNumber"]])

tracking = result["data"][0]
print(f"Status: {tracking['status']}")
print(f"Location: {tracking['currentLocation']['city']}, {tracking['currentLocation']['state']}")
print(f"ETA: {tracking['estimatedDelivery']}")

# Walk through event history
for event in tracking["events"]:
    print(f"  {event['timestamp']} | {event['status']} | {event['location']}")

Each event in the history includes a timestamp, status code, location, and description. Statuses include PICKED_UP, IN_TRANSIT, arrivedAtWarehouse, departedFromWarehouse, arrivedAtDelivery, and delivered among others.

Step 5: Set up webhooks

Minute 8 to 10. Instead of polling the tracking endpoint, register a webhook URL in your Warp dashboard and receive real time status events pushed directly to your application. Here is a simple Flask handler that processes delivery and exception events.

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/webhooks/warp", methods=["POST"])
def warp_webhook():
    event = request.json

    if event["status"] == "delivered":
        # Shipment delivered. Update your order system.
        order_id = event["orderId"]
        tracking = event["trackingNumber"]
        print(f"Delivered: {tracking} for order {order_id}")
        # update_order_status(order_id, "delivered")

    elif event["status"] == "exception":
        # Something went wrong. Alert your ops team.
        print(f"Exception on {event['trackingNumber']}: {event['description']}")
        # send_alert(event)

    elif event["status"] == "pickupSuccessful":
        # Freight picked up. Notify your customer.
        print(f"Picked up: {event['trackingNumber']}")
        # notify_customer(event)

    return jsonify({"received": True}), 200

# Register this URL in your Warp dashboard under Webhooks

Warp pushes events as shipments move through each status. Your handler receives the full event payload including tracking number, order ID, status, timestamps, and GPS coordinates. No polling required.

Even faster with AI coding tools

Everything above took 10 minutes to code manually. With Claude Code, Cursor, or another AI coding tool, you can describe the entire shipping feature in natural language and have the AI generate it. Tell it: "Add a freight shipping module to this app. Use Warp's API. Support quoting, booking, and tracking." The AI reads the docs and writes the integration.

The Warp CLI adds another option. AI agents running in terminals can call warp quote, warp book, and warp track as shell commands without writing any integration code at all.

What modes are available

The same API handles all of these. Omit the vehicle type and Warp selects the right one automatically based on your freight dimensions and weight.

Frequently asked questions

Related pages