ShipAgent360 API

# Pass your API key in the Authorization header
curl https://api.shipagent360.com/api/v1/public/me \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"

# Step 1 — Verify key
curl https://api.shipagent360.com/api/v1/public/me -H "Authorization: Bearer sa_live_YOUR_KEY"

# Step 2 — Get rates
curl -X POST https://api.shipagent360.com/api/v1/public/rates \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"shipper":{"name":"Sender","street1":"123 Main St","city":"Los Angeles","state":"CA","zip":"90210","phone":"3105550000"},"recipient":{"name":"Receiver","street1":"456 Park Ave","city":"New York","state":"NY","zip":"10001","phone":"2125550000","isResidential":false},"packages":[{"weightLbs":5,"lengthIn":12,"widthIn":10,"heightIn":8}]}'

# Step 3 — Book (use carrierId + serviceCode from step 2)
curl -X POST https://api.shipagent360.com/api/v1/public/shipments \
  -H "Authorization: Bearer sa_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"rateId":"rate_abc123","carrierId":"FEDEX","serviceCode":"GROUND_HOME_DELIVERY","shipper":{...},"recipient":{...},"packages":[{...}],"reference":"ORDER-001"}'

curl -X POST https://api.shipagent360.com/api/v1/public/rates \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shipper": {
      "name": "Acme Corp",
      "street1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90210",
      "phone": "3105550000"
    },
    "recipient": {
      "name": "Jane Smith",
      "street1": "456 Park Ave",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "phone": "2125550000",
      "isResidential": false
    },
    "packages": [
      {
        "weightLbs": 5.2,
        "lengthIn": 12,
        "widthIn": 10,
        "heightIn": 8,
        "declaredValue": 150,
        "packagingType": "MY_PACKAGING"
      }
    ]
  }'

{
  "quotes": [
    {
      "rateId": "rate_abc123",
      "carrierId": "FEDEX",
      "serviceCode": "GROUND_HOME_DELIVERY",
      "serviceName": "FedEx Ground Home Delivery",
      "price": 18.45,
      "currency": "USD",
      "estimatedDelivery": "2026-07-06",
      "transitDays": 3,
      "signatureAvailable": false
    },
    {
      "rateId": "rate_def456",
      "carrierId": "UPS",
      "serviceCode": "03",
      "serviceName": "UPS Ground",
      "price": 19.12,
      "currency": "USD",
      "estimatedDelivery": "2026-07-07",
      "transitDays": 4
    },
    {
      "rateId": "rate_ghi789",
      "carrierId": "GLS",
      "serviceCode": "CPS",
      "serviceName": "GLS Ground",
      "price": 17.80,
      "currency": "USD",
      "estimatedDelivery": "2026-07-06",
      "transitDays": 3
    },
    {
      "rateId": "rate_jkl012",
      "carrierId": "ROADIE",
      "serviceCode": "ROADIE_SAME_DAY",
      "serviceName": "Roadie Same-Day Delivery (8.2 mi)",
      "price": 14.00,
      "currency": "USD",
      "estimatedDelivery": "2026-07-02",
      "transitDays": 0
    }
  ],
  "errors": []
}

curl -X POST https://api.shipagent360.com/api/v1/public/shipments \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "rateId": "rate_abc123",
    "carrierId": "FEDEX",
    "serviceCode": "GROUND_HOME_DELIVERY",
    "shipper": {
      "name": "Acme Corp",
      "street1": "123 Main St",
      "city": "Los Angeles",
      "state": "CA",
      "zip": "90210",
      "phone": "3105550000"
    },
    "recipient": {
      "name": "Jane Smith",
      "street1": "456 Park Ave",
      "city": "New York",
      "state": "NY",
      "zip": "10001",
      "phone": "2125550000",
      "isResidential": false
    },
    "packages": [
      {
        "weightLbs": 5.2,
        "lengthIn": 12,
        "widthIn": 10,
        "heightIn": 8,
        "declaredValue": 150
      }
    ],
    "reference": "ORDER-12345",
    "labelFormat": "PDF"
  }'

{
  "id": "shp_abc123",
  "trackingNumber": "794835001234",
  "status": "BOOKED",
  "carrierId": "FEDEX",
  "serviceCode": "GROUND_HOME_DELIVERY",
  "price": 18.45,
  "labelUrl": "https://api.shipagent360.com/v1/public/shipments/shp_abc123/label",
  "estimatedDelivery": "2026-07-06",
  "createdAt": "2026-07-01T14:23:00Z"
}

// POST /shipments — GLS booked from an origin outside the pickup area
{
  "statusCode": 400,
  "message": "GLS does not offer pickup service from ZIP 10001. Choose a different carrier or ship from an address inside GLS's pickup area.",
  "error": "Bad Request"
}

// POST /shipments — a booked GLS shipment carries its pickup
{
  "id": "shp_abc123",
  "status": "BOOKED",
  "carrierId": "GLS",
  "serviceCode": "CPS",
  "trackingNumber": "12345678",
  "customerPrice": 18.75,
  "pickupStatus": "SCHEDULED",
  "pickupConfirmationNumber": "4204661",
  "pickupDate": "2026-09-04",
  "pickupWindowStart": "08:00 AM",
  "pickupWindowEnd": "07:00 PM"
}

// The label printed but GLS would not take the pickup. The shipment is still
// booked and the label is still valid — we retry automatically.
{
  "id": "shp_abc124",
  "status": "BOOKED",
  "trackingNumber": "12345679",
  "pickupStatus": "FAILED",
  "pickupConfirmationNumber": null,
  "pickupError": "GLS pickup was not scheduled — 77: Zip not serviced"
}

// Roadie rate quote — only returned for deliveries within 40 miles
{
  "carrierId": "ROADIE",
  "serviceCode": "ROADIE_SAME_DAY",
  "serviceName": "Roadie Same-Day Delivery (8.2 mi)",
  "price": 14.00,
  "currency": "USD",
  "transitDays": 0
}

// Roadie booking response — note labelUrl is null
{
  "id": "shp_xyz789",
  "trackingNumber": "1847392",
  "status": "BOOKED",
  "carrierId": "ROADIE",
  "serviceCode": "ROADIE_SAME_DAY",
  "price": 14.00,
  "labelUrl": null
}

// FedEx SameDay Local rate quote
{
  "carrierId": "FEDEX_SAMEDAY",
  "serviceCode": "FEDEX_SDL_2_HOUR",
  "serviceName": "FedEx SameDay Local — 2-Hour Window",
  "price": 24.50,
  "currency": "USD",
  "estimatedDays": 0
}

curl "https://api.shipagent360.com/api/v1/public/shipments?page=1&limit=20&status=IN_TRANSIT" \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"

{
  "shipments": [ /* array of shipment objects */ ],
  "total": 142,
  "page": 1,
  "limit": 20,
  "pages": 8
}

curl https://api.shipagent360.com/api/v1/public/shipments/shp_abc123 \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"

# The file you get back depends on how the shipment was booked.
# -OJ writes it under the filename the API sends (.pdf, .zpl or .zip).
curl -L -OJ https://api.shipagent360.com/api/v1/public/shipments/shp_abc123/label \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY" \

curl https://api.shipagent360.com/api/v1/public/shipments/shp_abc123/tracking \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"

{
  "status": "IN_TRANSIT",
  "events": [
    {
      "timestamp": "2026-08-28T14:22:00.000Z",
      "status": "IN_TRANSIT",
      "description": "Departed FedEx location",
      "location": "Memphis, TN"
    },
    {
      "timestamp": "2026-08-27T22:05:00.000Z",
      "status": "PICKED_UP",
      "description": "Picked up",
      "location": "Los Angeles, CA"
    }
  ]
}

curl https://api.shipagent360.com/api/v1/public/track/794835001234 \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"

{
  "shipmentId": "shp_abc123",
  "status": "DELIVERED",
  "events": [ ... ]
}

curl -X POST https://api.shipagent360.com/api/v1/webhooks \
  -H "Authorization: Bearer YOUR_JWT" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.yourcompany.com/shipagent","events":["shipment.delivered"]}'

POST https://hooks.yourcompany.com/shipagent
X-ShipAgent360-Event: shipment.delivered
X-ShipAgent360-Delivery: 4c1e...
X-ShipAgent360-Timestamp: 1787900000
X-ShipAgent360-Signature: 9f86d0818...

{
  "event": "shipment.delivered",
  "createdAt": "2026-08-28T18:04:00.000Z",
  "data": {
    "shipmentId": "shp_abc123",
    "status": "DELIVERED",
    "previousStatus": "OUT_FOR_DELIVERY",
    "trackingNumber": "794835001234",
    "trackingNumbers": ["794835001234"],
    "carrier": "FEDEX",
    "reference": "ORDER-12345",
    "recipient": { "name": "Jane Smith", "city": "New York", "state": "NY", "zip": "10001" },
    "deliveredAt": "2026-08-28T18:03:58.000Z"
  }
}

const crypto = require('crypto')

app.post('/shipagent', express.raw({ type: 'application/json' }), (req, res) => {
  const timestamp = req.get('X-ShipAgent360-Timestamp')
  const signature = req.get('X-ShipAgent360-Signature')
  const expected = crypto
    .createHmac('sha256', process.env.SHIPAGENT_WEBHOOK_SECRET)
    .update(`${timestamp}.${req.body}`)
    .digest('hex')

  const ok = signature.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))
  if (!ok) return res.sendStatus(401)

  // Reject a timestamp far from now to stop replay of a captured payload.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return res.sendStatus(401)

  const event = JSON.parse(req.body)
  // Respond fast; do the work afterwards. We time out after 10 seconds.
  res.sendStatus(200)
})

curl https://api.shipagent360.com/api/v1/public/me \
  -H "Authorization: Bearer sa_live_YOUR_API_KEY"

{
  "orgId": "e96cc419-ddbf-4f59-bc0b-ea2856bfbe65",
  "requestsThisHour": 42,
  "rateLimit": 1000,
  "defaultLabelFormat": "PDF",
  "creditLimitApplies": true,
  "creditLimit": 5000.00,
  "balance": 2000.00,
  "availableCredit": 3000.00
}

{
  "statusCode": 401,
  "message": "Invalid or expired API key",
  "error": "Unauthorized"
}

{
  "statusCode": 429,
  "message": "Rate limit exceeded",
  "limit": 1000,
  "windowSeconds": 3600,
  "retryAfterSeconds": 1423
}

{
  "statusCode": 402,
  "error": "Credit limit reached",
  "message": "This shipment would put your account over its $5000.00 credit limit ($4900.00 outstanding, $100.00 available). Pay down your balance to continue shipping.",
  "balance": 4900.00,
  "limit": 5000.00,
  "available": 100.00,
  "statementInvoiceNumber": "SA-2026-00042"
}

{
  "statusCode": 400,
  "message": "This rate quote has expired. Request fresh rates and book again.",
  "error": "Bad Request"
}