Hyperfold AI

Shippo Integration

Simple shipping API with rate shopping and discounted carrier rates.

Overview

Shippo provides a unified shipping API with access to discounted carrier rates. It's ideal for merchants who want simple shipping integration without managing individual carrier accounts.

Shippo offers pre-negotiated discounts with major carriers, often 20-30% below retail rates. No carrier account setup required.

Setup

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
# Connect Shippo
$ hyperfold fulfill add shippo --api-key=shippo_live_xxx
 
Testing connection...
✓ Connected to Shippo
 
SHIPPO CONNECTED
  Account:          acme-sports-001
  Default Carrier:  USPS
  Features:         Rate shopping, Label creation, Tracking
 
# View connection status
$ hyperfold fulfill show shippo
 
INTEGRATION: Shippo
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Account:            acme-sports-001
Status:             connected
Mode:               live
 
CARRIERS (via Shippo)
  ✓ USPS            All services
  ✓ FedEx           All services
  ✓ UPS             All services
  ✓ DHL Express     International
 
ADDRESS VALIDATION
  Status:           enabled
  Auto-correct:     true
 
METRICS (30 days)
  Labels Created:   1,456
  Avg Rate Savings: 18%
  Tracking Events:  12,450

Prerequisites

  • Shippo account (free to create)
  • API token from Shippo dashboard
  • Ship-from address configured

Rate Shopping

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# Rate shopping across carriers
$ hyperfold fulfill rates \
  --provider=shippo \
  --origin="Los Angeles, CA 90001" \
  --destination="New York, NY 10001" \
  --weight=2 \
  --dimensions="10x8x4"
 
Fetching rates from all carriers...
 
SHIPPING RATES: LA → NYC (2 lbs, 10x8x4 in)
 
CARRIER          SERVICE              RETAIL    SHIPPO    SAVINGS   DELIVERY
USPS             Priority Mail        $12.80    $9.45     26%       2-3 days
USPS             First Class         $5.20     $4.15     20%       4-5 days
FedEx            Ground              $14.50    $11.20    23%       4-5 days
FedEx            2Day                $28.00    $22.40    20%       2 days
UPS              Ground              $15.20    $12.30    19%       4-5 days
 
Best Value: USPS Priority Mail ($9.45, 2-3 days)
Fastest: FedEx 2Day ($22.40, 2 days)
 
# Agent rate shopping
@OnACPEvent("checkout.init")
async calculateShipping(event: CheckoutEvent) {
  const rates = await this.tools.fulfillment.getRates({
    provider: "shippo",
    origin: this.getWarehouseAddress(event.items),
    destination: event.shipping_address,
    parcels: this.calculateParcels(event.items)
  });
 
  // Return cheapest option as default, with alternatives
  return {
    shipping_options: rates.map(rate => ({
      id: rate.service,
      name: rate.carrier + " " + rate.service_name,
      price: rate.amount,
      delivery_estimate: rate.estimated_days + " days"
    })),
    selected: rates[0].service  // Cheapest by default
  };
}

Supported Carriers

CarrierServicesDiscount
USPSPriority, First Class, ExpressUp to 40%
FedExGround, Express, OvernightUp to 30%
UPSGround, 2Day, Next DayUp to 25%
DHL ExpressInternational ExpressUp to 35%

Label Creation

typescript
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# Create shipping labels
$ hyperfold fulfill label create \
  --provider=shippo \
  --order=ord_xyz789
 
Creating label...
✓ Label created
 
SHIPPING LABEL
  Tracking:         9400111899223456789012
  Carrier:          USPS Priority Mail
  Cost:             $9.45
  Label:            https://labels.shippo.com/xxx.pdf
 
# Batch label creation
$ hyperfold fulfill label batch \
  --provider=shippo \
  --orders=ord_001,ord_002,ord_003
 
Creating 3 labels...
✓ ord_001: USPS Priority ($9.45) - 9400111899223456789012
✓ ord_002: USPS Priority ($8.20) - 9400111899223456789013
✓ ord_003: FedEx Ground ($11.20) - 794644790100
 
Batch complete:
  Labels: 3
  Total cost: $28.85
  Download: https://labels.shippo.com/batch_xxx.pdf
 
# Agent label creation workflow
@OnACPEvent("order.confirmed")
async createShippingLabel(event: OrderEvent) {
  // Create shipment in Shippo
  const shipment = await this.tools.fulfillment.createShipment({
    provider: "shippo",
    address_from: this.warehouse.address,
    address_to: event.order.shipping_address,
    parcels: [{
      length: 10,
      width: 8,
      height: 4,
      distance_unit: "in",
      weight: event.order.total_weight,
      mass_unit: "lb"
    }]
  });
 
  // Get best rate and create label
  const rate = shipment.rates.find(r => r.service === event.shipping_service);
  const label = await this.tools.fulfillment.createLabel({
    provider: "shippo",
    rate_id: rate.object_id
  });
 
  return {
    tracking_number: label.tracking_number,
    label_url: label.label_url,
    carrier: label.carrier_account
  };
}

Tracking

bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
# Configure tracking
$ hyperfold fulfill tracking enable shippo
 
Tracking enabled:
  Webhook URL:      https://api.hyperfold.io/webhooks/shippo/track/xxx
  Events:           All status updates
 
# Track a shipment
$ hyperfold fulfill track 9400111899223456789012
 
TRACKING: 9400111899223456789012
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
Carrier:            USPS
Service:            Priority Mail
Status:             In Transit
Est. Delivery:      Jan 25, 2025
 
TRACKING HISTORY
 
Jan 22, 08:00 AM    In Transit
                    Arrived at USPS Regional Facility
                    Denver, CO
 
Jan 21, 06:00 PM    In Transit
                    Departed USPS Origin Facility
                    Los Angeles, CA
 
Jan 21, 02:30 PM    Picked Up
                    Shipment picked up
                    Los Angeles, CA
 
# Tracking webhooks in agent
@OnTrackingEvent("delivered")
async handleDelivery(event: TrackingEvent) {
  await this.tools.orders.updateStatus(event.order_id, "delivered");
  await this.notifyCustomer({
    type: "delivered",
    tracking: event.tracking_number,
    delivery_time: event.timestamp
  });
}
 
@OnTrackingEvent("exception")
async handleException(event: TrackingEvent) {
  await this.alertOps({
    type: "shipping_exception",
    order_id: event.order_id,
    message: event.status_details
  });
}
For multi-warehouse setups, consider ShipStation.