API Reference

Send a shipping request, get ranked options back, pick one (or let Treoir pick for you), and track it through delivery. Three endpoints cover the whole lifecycle.

Base URL:http://localhost:3000/api/v1

Format:JSON

POST/api/v1/fulfillment/optimize

Evaluate all feasible carrier × warehouse × service combinations for a shipment and return ranked fulfillment strategies. This is the core endpoint - send your logistics intent, get back the optimal options.

Example request

curl -X POST http://localhost:3000/api/v1/fulfillment/optimize \
  -H "Content-Type: application/json" \
  -d '{
    "destination": { "postal_code": "11201", "country": "US" },
    "items": [{ "weight_oz": 32 }],
    "constraints": { "deliver_by": "2026-03-20T23:59:59Z" }
  }'

Request body

{
  "origin": {
    "warehouse_id": "wh_nj_01"      // optional - omit to evaluate all warehouses
  },
  "destination": {
    "postal_code": "11201",
    "country": "US"
  },
  "items": [
    {
      "name": "Widget Pro",
      "sku": "WIDGET-001",
      "weight_oz": 32,
      "dimensions": { "length": 12, "width": 8, "height": 6 },
      "quantity": 1
    }
  ],
  "constraints": {
    "deliver_by": "2026-03-20T23:59:59Z",  // optional
    "max_cost_usd": 15.00,                  // optional
    "exclude_carriers": ["dhl"]             // optional
  },
  "preferences": {
    "weights": {
      "cost": 0.4,
      "transit_time": 0.3,
      "reliability": 0.2,
      "carbon": 0.1
    }
  }
}

Response

{
  "request_id": "req_a1b2c3d4",
  "strategies": [
    {
      "id": "strat_e5f6g7h8",
      "carrier": "USPS",
      "service": "Priority Mail",
      "origin": { "warehouse_id": "wh_nj_01", "city": "Avenel", "state": "NJ" },
      "estimated_cost_usd": 8.45,
      "delivery_window": {
        "p50": "2026-03-19",
        "p90": "2026-03-20",
        "p99": "2026-03-21"
      },
      "reliability_score": 0.912,
      "carbon_kg": 0.384,
      "composite_score": 0.847,
      "meets_constraints": true,
      "constraint_violations": []
    }
    // ... more strategies ranked by composite_score
  ],
  "evaluated_options": 36,
  "optimization_time_ms": 12,
  "warnings": []
}

Key concepts

Optimization weights

Weights are normalized values from 0 to 1 that tell the optimizer how much you care about each objective. A weight of 0.6 on cost and 0.4 on reliability means you want the cheapest option that is still reliable. The weights don't need to sum to 1. They're normalized internally.

Delivery windows

Instead of vague “3-5 days” estimates, Treoir returns probability distributions. The p50 date means there's a 50% chance it arrives by then; p90 means 90% confidence; p99 means near-certain. Constraint checking uses p90 by default.

Composite score

Each strategy gets a 0-1 composite score based on your weighted objectives. Higher is better. Strategies are Pareto-ranked, meaning no returned option is strictly worse than another on all dimensions.

Constraint violations

Strategies that violate your constraints (budget, deadline, carrier exclusions) are still returned but marked with meets_constraints: false and sorted below feasible options. This lets you see what would work if you relaxed a constraint.

Shipment lifecycle events

Shipments progress through these statuses. In production, you'd receive webhook callbacks for each transition.

booked→

label_generated→

picked_up→

in_transit→

out_for_delivery→

delivered