Routely API Reference

The Routely API provides programmatic access to our intelligent carrier allocation engine. Send shipment details via a simple REST API and receive real-time, fully-itemized cost breakdowns, the optimal winning carrier, and a complete list of eligible alternatives in milliseconds.

Authentication

The API uses Bearer tokens to authenticate requests. You can generate API keys from the Settings panel in the Routely dashboard.

Authorization: Bearer routely_live_a1b2c3d4...

API access is exclusively available on the Pro Plan. View pricing details.

Create Allocation

POSThttps://routely.in/api/v1/allocate

Evaluates all configured carrier services against the shipment payload and returns the optimal routing decision.

Request Payload

Field	Type	Description
origin_country	string	Required. 2-letter ISO code (e.g., "IN").
origin_zip	string	Required. Origin postal code.
destination_country	string	Required. 2-letter ISO code (e.g., "US").
destination_zip	string	Required. Destination postal code.
weight_lb	number	Required. Shipment actual weight in pounds.
destination_state	string	Optional. Target state code (e.g., "NY").
is_po_box	boolean	Optional. Set true if delivering to a PO Box.
length_in	number	Optional. Length in inches.
width_in	number	Optional. Width in inches.
height_in	number	Optional. Height in inches.
packaging	string	Optional. e.g., "box" or "flyer".

Request Example

curl -X POST https://routely.in/api/v1/allocate \
  -H "Authorization: Bearer routely_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_country": "IN",
    "origin_zip": "380015",
    "destination_country": "US",
    "destination_zip": "10001",
    "destination_state": "NY",
    "is_po_box": false,
    "packaging": "box",
    "length_in": 16,
    "width_in": 12,
    "height_in": 10,
    "weight_lb": 18
  }'

Response Example

{
  "status": "success",
  "allocation": {
    "winner": {
      "forwarder": "UBI",
      "carrier": "USPS",
      "service": "Priority Mail",
      "total_cost_usd": 16.31,
      "cost_breakdown": {
        "base_rate_usd": 16.31,
        "base_rate_label": "Zone 1, 18 lb CW",
        "surcharges_usd": 0,
        "total_cost_usd": 16.31
      },
      "recommendation_reason": "Lowest total landed cost"
    },
    "alternatives": [
      {
        "forwarder": "UBI",
        "carrier": "FedEx",
        "service": "International Priority",
        "base_rate_usd": 19.44,
        "surcharges_usd": 0,
        "total_cost_usd": 19.44
      }
    ],
    "ineligible_carriers": [
      {
        "carrier": "DHL",
        "reason": "No contracted rate for this lane"
      }
    ]
  },
  "usage": {
    "allocations_used": 43,
    "allocations_limit": 5000,
    "resets_at": "2026-06-01"
  }
}

Rate Limits

The Routely API enforces two concurrent rate limits to ensure stability:

Concurrency Limit: Maximum of 10 requests per second per company. Returns 429 RATE_LIMITED if exceeded.
Monthly Quota: Based on your Pro plan limit (e.g., 5,000 requests/month). Returns 429 LIMIT_REACHED if exhausted.

Error Codes

Status	Error Code	Description
401	UNAUTHORIZED	Invalid or missing API key
403	FORBIDDEN	API access requires Pro plan
429	RATE_LIMITED	Exceeded 10 requests per second
429	LIMIT_REACHED	Monthly allocation limit reached
400	INVALID_REQUEST	Missing or invalid request fields
500	SERVER_ERROR	Internal server error