Hyperfold AI

Fulfillment Agent

Automated order processing, shipping, and delivery tracking.

Overview

The Fulfillment Agent handles everything that happens after a purchase: order processing, carrier selection, label generation, tracking updates, and return handling. It integrates with ShipStation, EasyPost, or Shippo for carrier connectivity.

Capabilities

FULFILLMENT AGENT CAPABILITIES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

EVENT HANDLERS:
  order.completed        Process new orders
  order.cancelled        Handle cancellations
  shipment.created       Track shipment creation
  shipment.delivered     Handle delivery confirmation
  return.requested       Process return requests

FEATURES:
  ✓ Carrier selection    Rate shopping across providers
  ✓ Label generation     Automatic shipping labels
  ✓ Tracking updates     Real-time shipment tracking
  ✓ Inventory updates    Sync inventory on ship/receive
  ✓ Return processing    Handle returns and refunds
  ✓ Split shipments      Multiple packages per order

INTEGRATIONS:
  • ShipStation / EasyPost / Shippo
  • Cloud Spanner (inventory)
  • Firestore (order state)
  • Pub/Sub (event coordination)

Deployment

Deploy the Fulfillment Agent:

# Deploy reference fulfillment agent
$ hyperfold agent deploy --type=fulfillment --name="fulfillment-01"

> [Build] Using reference implementation...
> [Config] Loading shipping rules...
> [Deploy] Creating Cloud Run service...
> [Events] Subscribing to order events...

✓ Fulfillment agent deployed!

  Name:           fulfillment-01
  Subscriptions:  order.completed, shipment.*, return.*
  Carriers:       USPS, FedEx, UPS (via ShipStation)

# Deploy with custom configuration
$ hyperfold agent deploy --type=fulfillment \
  --name="fulfillment-premium" \
  --config=./agents/fulfillment-config.yaml

Order Flow

How orders flow through the Fulfillment Agent:

ORDER FULFILLMENT FLOW
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  Negotiator Agent          Fulfillment Agent            ShipStation
        │                          │                          │
        │  order.completed         │                          │
        │─────────────────────────▶│                          │
        │                          │ [load order details]     │
        │                          │ [check inventory]        │
        │                          │ [select carrier]         │
        │                          │  Create Shipment         │
        │                          │─────────────────────────▶│
        │                          │  Label + Tracking        │
        │                          │◀─────────────────────────│
        │                          │ [update inventory]       │
        │                          │ [send tracking email]    │
        │  shipment.created        │                          │
        │◀─────────────────────────│                          │
                              [MONITORING]
        │                          │  Status: Delivered       │
        │                          │◀─────────────────────────│
        │                          │ [confirm delivery]       │
        │  order.delivered         │                          │
        │◀─────────────────────────│                          │

Shipping Logic

The agent's shipping decision logic:

// Fulfillment agent shipping logic
@OnEvent('order.completed')
async handleOrderCompleted(order: Order) {
  const inventory = await this.checkInventory(order.items);
  if (!inventory.canFulfill) {
    await this.handleBackorder(order, inventory);
    return;
  }

  const shippingOptions = await this.getRates({
    from: this.selectWarehouse(order),
    to: order.shipping_address,
    items: order.items,
    weight: order.total_weight,
  });

  const selectedRate = this.applyShippingRules(order, shippingOptions);

  const shipment = await this.createShipment({
    order_id: order.id,
    carrier: selectedRate.carrier,
    service: selectedRate.service,
    items: order.items,
  });

  const label = await this.generateLabel(shipment);
  await this.decrementInventory(order.items);
  await this.sendTrackingEmail(order.customer, {
    order_id: order.id,
    tracking_number: shipment.tracking_number,
    carrier: shipment.carrier,
    estimated_delivery: shipment.estimated_delivery,
  });
  await this.events.publish('shipment.created', { order, shipment });
}

selectCarrier(order: Order, rates: ShippingRate[]): ShippingRate {
  if (order.customer.tier === 'platinum') {
    return rates.find(r => r.service.includes('Express')) || rates[0];
  }
  if (order.total > 200) {
    return rates.find(r => r.insurance_included) || rates[0];
  }
  return rates
    .filter(r => r.estimated_days <= order.shipping_sla)
    .sort((a, b) => a.cost - b.cost)[0];
}

Configuration

Configure warehouses, carriers, and shipping rules:

# fulfillment-config.yaml
name: fulfillment-agent
type: fulfillment
version: "1.0"

shipping_provider: shipstation
shipstation:
  api_key: $SHIPSTATION_API_KEY
  api_secret: $SHIPSTATION_API_SECRET

warehouses:
  - id: warehouse_west
    name: "West Coast DC"
    address:
      city: Los Angeles
      state: CA
      zip: "90001"
    carriers: [usps, fedex, ups]
    priority: 1
  - id: warehouse_east
    name: "East Coast DC"
    address:
      city: Newark
      state: NJ
      zip: "07102"
    carriers: [usps, fedex, ups]
    priority: 2

shipping_rules:
  - name: free_shipping
    condition: "order.subtotal >= 100"
    action:
      free_shipping: true
      method: "standard"
  - name: premium_expedited
    condition: "customer.tier in ['gold', 'platinum']"
    action:
      upgrade_to: "express"
      cost_to_customer: 0
  - name: heavy_freight
    condition: "order.total_weight > 70"
    action:
      carrier: "freight"
      method: "ltl"
  - name: west_coast_usps
    condition: "shipping.state in ['CA', 'OR', 'WA', 'NV', 'AZ']"
    action:
      preferred_carrier: "usps"
      warehouse: "warehouse_west"

notifications:
  send_tracking: true
  send_delivery: true
  send_delay_alert: true
  delay_threshold_hours: 24

returns:
  window_days: 30
  free_return_shipping: true
  restocking_fee_percent: 0
  auto_approve_under: 100