Use RouteIQ’s API to create secure keys, validate access, sync inventory, route one order in real time, or route a moderate batch of orders in one request.
Create a sandbox key in Account → API Access, then send it in the Authorization header.
Authorization: Bearer riq_test_YOUR_API_KEYTypical API flow:
1. POST /api/v1/inventory
2. POST /api/v1/orders/route
or
POST /api/v1/orders/batch-routeCurrent local QA base URL:
https://api.routeiq.appMost integrations use one of these patterns. RouteIQ can run as an inventory-aware routing engine or as a routing-only recommendation engine depending on the client’s Routing Settings.
If Use Inventory Availability is enabled, send current available quantity with POST /api/v1/inventory.
Call POST /api/v1/orders/route as each order is ready.
Use selected_warehouse for single-origin routes, or lines[].allocations[] for item-level shipment instructions.
Send up to 250 orders in one synchronous request.
Call POST /api/v1/orders/batch-route. RouteIQ returns one routing_run_id and one result per order.
Use each result’s selected_warehouse, selected_warehouses, and lines[].allocations[] to update the customer system.
Customer API endpoints use API-key authentication. Do not send client_id in customer API requests. RouteIQ resolves the client from the API key.
$apiKey = "riq_test_YOUR_API_KEY"
$headers = @{ Authorization = "Bearer $apiKey" }cURL example:
curl -H "Authorization: Bearer riq_test_YOUR_API_KEY" \
https://api.routeiq.app/api/v1/meUse riq_test_... keys while validating payloads, response handling, and integration behavior.
Use riq_live_... keys for production traffic after your workflow is ready.
In customer-facing API payloads, external_warehouse_id means the Warehouse ID configured on the Warehouses page. This is normally the customer’s own warehouse/location ID, such as PF3, 01, or any ID the customer entered during setup.
The Warehouse ID customers should normally send in inventory payloads and consume in route responses.
RouteIQ?s warehouse code for that client. It may appear in responses for traceability, but customer systems should generally rely on external_warehouse_id.
RouteIQ responses use the same warehouse and allocation language across one-order routing, batch routing, and future exports.
| Field | Meaning | Use this when... |
|---|---|---|
external_warehouse_id |
The customer-facing warehouse ID entered on Warehouse Setup. | Customer systems need to identify the selected warehouse. |
warehouse_code |
RouteIQ?s warehouse code for that client. | Support workflows and operational traceability. |
warehouse_name |
Readable warehouse name from Warehouse Setup. | Showing decisions to users. |
preferred_warehouse |
The top-ranked warehouse based on the current routing strategy and data. | Explaining what RouteIQ considered best before fulfillment constraints. |
selected_warehouse |
The selected warehouse when the route is single-origin. | Simple FULL/PARTIAL routes from one warehouse. |
selected_warehouses |
All selected warehouses used by the decision. | Split or multi-origin routing. |
lines[].allocations[] |
Item-level ship-from allocation detail. | Best field for fulfillment Creating shipment instructions. |
routing_quality |
Customer-facing quality label such as Optimal, Split, Suboptimal, or Unroutable. |
Reporting and decision summaries. |
decision_driver |
The primary reason RouteIQ chose or could not choose a route. | Explaining exceptions, suboptimal routes, and unroutable orders. |
unroutable_reason_code |
Stable machine-readable code for NONE results, such as invalid_destination_zip or no_inventory_available. |
Automating exception queues and customer-service workflows. |
unroutable_category |
High-level bucket for the issue, such as invalid order data, inventory, or routing rules. | Dashboarding and issue triage. |
unroutable_reason |
Customer-facing explanation for why RouteIQ could not produce a shippable allocation. | Showing operators what needs attention. |
recommended_action |
Suggested next step, such as correcting a ZIP, adding inventory, or changing routing rules. | Turning exceptions into clear follow-up work. |
lines[].allocations[] over top-level fields. Top-level fields are useful summaries, but allocations are the source of truth for line-level ship-from decisions.Use this endpoint to confirm that an API key is active and scoped to the expected client.
Invoke-RestMethod `
-Uri "https://api.routeiq.app/api/v1/me" `
-Method GET `
-Headers $headers | ConvertTo-Json -Depth 5{
"status": "ok",
"api_key_id": 5,
"client_id": 9,
"environment": "test",
"key_prefix": "riq_test_bda75e17e",
"name": "Pre-commit test key",
"subscription_status": "trialing",
"subscription_tier": "starter"
}Upserts current available inventory by SKU and warehouse. This endpoint updates inventory only; it does not count against routed-order usage.
RouteIQ is not your WMS, ERP, or inventory system of record. Inventory synced to RouteIQ is treated as a routing snapshot. RouteIQ uses the inventory totals you provide when a batch is run; it does not permanently maintain or decrement inventory after the batch completes.
Recommended integration pattern: sync fresh inventory immediately before routing orders. Customers should configure their WMS, ERP, inventory platform, or integration process to refresh inventory before each order batch is submitted to RouteIQ.
external_warehouse_id means the Warehouse ID configured on the Warehouses page. Each warehouse in the payload must already exist and be enabled for that client.{
"source_name": "nightly inventory sync",
"inventory": [
{
"sku": "SKU-A",
"external_warehouse_id": "PF3",
"quantity_available": 50,
"unit_value": 12.50,
"sku_description": "Sample item"
},
{
"sku": "SKU-A",
"external_warehouse_id": "PF4",
"quantity_available": 10
}
]
}PowerShell example:
$body = @{
source_name = "nightly inventory sync"
inventory = @(
@{ sku = "SKU-A"; external_warehouse_id = "PF3"; quantity_available = 50; unit_value = 12.50 },
@{ sku = "SKU-A"; external_warehouse_id = "PF4"; quantity_available = 10 }
)
} | ConvertTo-Json -Depth 8
Invoke-RestMethod `
-Uri "https://api.routeiq.app/api/v1/inventory" `
-Method POST `
-Headers $headers `
-ContentType "application/json" `
-Body $bodyAlso accepted:
available_qty instead of quantity_availablewarehouse_code instead of external_warehouse_id, for warehouse setup and support traceabilityRules and limits:
quantity_available: 0.{
"client_id": 9,
"ingest_run_id": 123,
"rows_received": 2,
"rows_upserted": 2,
"rows_inserted": 1,
"rows_updated": 1,
"rows_unchanged": 0,
"rows_deleted": 0
}Routes one customer order. The order may contain one line or many lines. A successful request increments routed-order usage by 1.
{
"external_order_id": "API-1001",
"destination_zip": "08825",
"lines": [
{ "sku": "SKU-A", "quantity": 1, "unit_value": 12.50 }
]
}Also accepted: order_id instead of external_order_id, and items instead of lines.
RouteIQ ranks enabled warehouses using customer routing settings and available transit data.
Routes 1 to 250 orders synchronously and returns one shared routing_run_id. A successful request increments routed-order usage by the number of orders processed, including orders that return NONE.
{
"orders": [
{
"external_order_id": "API-BATCH-1001",
"destination_zip": "08825",
"lines": [
{ "sku": "SKU-A", "quantity": 1, "unit_value": 12.50 }
]
},
{
"external_order_id": "API-BATCH-1002",
"destination_zip": "48837",
"lines": [
{ "sku": "SKU-B", "quantity": 1, "unit_value": 12.50 }
]
}
]
}Each external_order_id/order_id must be unique within a batch request.
If Consume Inventory During Batch Routing is enabled, each order in the batch consumes the in-memory inventory pool before the next order is routed. If disabled, each order routes independently against the same starting inventory snapshot.
Batch inventory consumption is temporary. It is limited to the current batch/run and resets on the next batch based on the latest inventory totals supplied to RouteIQ. It prevents later orders in the same batch from reusing inventory already allocated to earlier orders, but it does not permanently decrement saved inventory after routing.
Both order-routing endpoints return customer-facing warehouse identifiers and routing explanations.
{
"order_id": "API-1001",
"routing_decision_id": 3519,
"status": "FULL",
"routing_quality": "Optimal",
"reason": "Full shipment allowed",
"preferred_warehouse": {
"warehouse_code": "WH1",
"external_warehouse_id": "01",
"warehouse_name": "Buckhill"
},
"selected_warehouse": {
"warehouse_code": "WH1",
"external_warehouse_id": "01",
"warehouse_name": "Buckhill"
},
"selected_warehouses": [],
"lines": [
{
"sku": "SKU-A",
"ordered_qty": 1,
"ship_qty": 1,
"unfulfilled_qty": 0,
"allocations": [
{
"warehouse_code": "WH1",
"external_warehouse_id": "01",
"warehouse_name": "Buckhill",
"ship_qty": 1
}
]
}
]
}external_warehouse_id: the customer-facing warehouse ID from Warehouse Setup, such as PF3, 01, or whatever ID the customer uses.warehouse_code: RouteIQ?s warehouse code for that client.preferred_warehouse: RouteIQ’s top-ranked warehouse based on current settings.selected_warehouse: populated for single-origin routes.selected_warehouses: use this for split/multi-origin routes.lines[].allocations[]: the safest source of item-level ship-from detail.FULL: all requested units can ship from one warehouse.SPLIT: all requested units can ship, but more than one warehouse is required.PARTIAL: some units can ship from one warehouse, but not all requested units.PARTIAL_SPLIT: some units can ship across multiple warehouses, but not all requested units.NONE: no route is available under current order data, inventory, and routing rules. Use the unroutable fields to determine whether the issue is bad order data, inventory availability, or rule settings.RouteIQ enforces customer plan limits before routing work begins.
POST /api/v1/orders/route counts as 1 routed order after a successful decision is saved.POST /api/v1/orders/batch-route counts each order in the batch after successful decisions are saved.POST /api/v1/inventory does not count as routed-order usage, but inventory row limits still apply.order_id or external_order_id, destination_zip, sku, and quantity. Recommended optional fields: unit_value, is_vip, priority_level, and order_created_at.is_vip=true orders first, then lower priority_level values, then older order_created_at timestamps, then the original API request order.is_vip is a boolean. Send true or false in API JSON. priority_level is an integer where lower numbers route first.destination_zip must be a valid 5-digit ZIP. Invalid ZIPs return status: NONE with unroutable_reason_code: invalid_destination_zip.warehouse_code, sku, and available_qty. Optional: unit_value.402 and does not increment usage.401: missing, invalid, or revoked API key.402: account/subscription is not active, a trial/plan routed-order limit was reached, or an upload exceeds a plan limit.400: invalid payload, missing order ID, missing lines, unknown Warehouse ID, disabled Warehouse ID, duplicate inventory rows, or duplicate order IDs in a batch.422: request body fails validation.500: unexpected server error.Example invalid key response:
{
"detail": "Invalid or revoked API key"
}Example usage-limit response:
{
"detail": "Your free trial includes up to 15 routed orders total. You have 0 remaining, and this run contains 1. Choose a plan on the Billing page or contact RouteIQ for a larger test."
}Example Warehouse ID response:
{
"detail": "Unknown Warehouse ID: Warehouse ID must be setup and enabled in the Warehouses page. Your enabled Warehouse ID's are: PF3, PF4, PF5"
}Use Inventory Availability is controlled in Routing Settings.