Route warehouse decisions through your own systems.

Quick Start

1. Create an API key

Create a test or live API key from Account → API Access.

Test keys write to your test environment. Live keys write to your live environment and count toward routed-order usage.

2. Set your base URL

Production:

https://gorouteiq.com

Sandbox:

Use the sandbox host provided by RouteIQ.

3. Send your API key

Include your key in the Authorization header with each request.

Authorization: Bearer riq_test_YOUR_API_KEY

4. Validate the key

GET /api/v1/me

5. Sync inventory

POST /api/v1/inventory

6. Route orders

Single order:

POST /api/v1/orders/route

Batch orders:

POST /api/v1/orders/batch-route

Recommended integration flows

Most 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 control settings.

Real-time routing

Wave or batch routing

Authentication

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://gorouteiq.com/api/v1/me

Test vs live keys

Warehouse identifiers

In customer-facing API payloads, warehouse_id means the Warehouse ID configured on the Warehouses page. This is normally the customer’s own warehouse/location ID, such as 001, 002, 003, or any ID the customer entered during setup.

API field contract

RouteIQ routing responses are designed around one execution rule: create downstream shipment or work records from shipments[].

Routing Profiles

Routing Profiles let you apply different routing rules for specific partners, channels, marketplaces, or customer groups without changing your default routing control settings.

To use a Routing Profile through the API, include the optional partner_id field on the order. RouteIQ compares that value to enabled Routing Profiles for the client.

{
  "external_order_id": "AMZ-1001",
  "destination_zip": "90210",
  "partner_id": "871",
  "lines": [
    {
      "sku": "SKU-123",
      "quantity": 2,
      "unit_value": 24.99
    }
  ]
}

New API integrations and CSV templates should use partner_id as the standard field name.

Item Control

Item Control rules are configured inside RouteIQ and apply by SKU during API and CSV routing. API callers do not send Item Control rules in the order payload. Instead, send normal order lines, and RouteIQ automatically applies any active rules for those SKUs.

Item Control can affect warehouse eligibility, warehouse ranking, split behavior, partial fulfillment behavior, max transit limits, external-fulfillment handling, and do-not-route/manual-review outcomes.

When Item Control applies, API responses include Item Control details inside the order result explanation object. Report exports also expose Item Control audit fields in the Latest Order Routing Detail report.

"explanation": {
  "item_control_applied": true,
  "item_control_skus": ["21763"],
  "item_control_flags": ["warehouse_restricted", "do_not_split", "do_not_partial"],
  "item_control_notes": ["SKU must ship from Lansing"],
  "item_control_rules": [
    {
      "sku": "21763",
      "summary": "SKU 21763: Restrict to selected warehouses | restricted warehouses: Lansing MI; do not split SKU; do not partial SKU"
    }
  ]
}

Order request fields

These fields are accepted by POST /api/v1/orders/route and inside each object in POST /api/v1/orders/batch-route.

Inventory request fields

These fields are accepted by POST /api/v1/inventory. Inventory is synced by SKU and warehouse.

Priority Allocation

Priority Allocation determines which queued orders get first access to scarce inventory inside the current routing run. It is separate from Use Inventory Availability.

When Use Inventory Availability is enabled, RouteIQ checks available inventory and persists routed allocations as reservations. When Priority Allocation is also enabled, RouteIQ sorts the current run before allocating inventory:

1. VIP first: is_vip=true orders route before non-VIP orders.
2. Priority level next: orders with priority_level route before blank priority levels. Among populated values, lower numbers route first. Example: 1 before 2, and 2 before 10.
3. Oldest order next: order_created_at is used as the next tie-breaker. Older orders route first.
4. Stable final tie-breaker: RouteIQ uses request/database order to keep results deterministic when all other priority fields are tied.

Example

{
  "orders": [
    {
      "external_order_id": "STANDARD-1001",
      "destination_zip": "08825",
      "is_vip": false,
      "priority_level": 2,
      "order_created_at": "2026-05-21T10:00:00Z",
      "lines": [{ "sku": "SKU-A", "quantity": 5 }]
    },
    {
      "external_order_id": "VIP-1002",
      "destination_zip": "08825",
      "is_vip": true,
      "priority_level": 10,
      "order_created_at": "2026-05-21T10:05:00Z",
      "lines": [{ "sku": "SKU-A", "quantity": 5 }]
    }
  ]
}

In this example, the VIP order routes first even though its numeric priority_level is higher. VIP status is evaluated before numeric priority.

Response field reference

RouteIQ responses provide a decision summary plus executable shipment instructions. Integrations should create downstream shipment/work records from shipments[].

Order result fields

Routing run response wrapper fields

Policy behavior: Allow, Warn, Block

RouteIQ routing control settings can allow a route, allow it with a warning, or block it. The customer API exposes that result through the policy_* fields on each order response.

Common policy codes

• split_shipment_warned / split_shipment_blocked
• partial_shipment_warned / partial_shipment_blocked
• max_transit_days_warned / max_transit_days_blocked
• minimum_shipment_value_warned / minimum_shipment_value_blocked

Validate an API key

Use this endpoint to confirm that an API key is active and scoped to the expected client.

Invoke-RestMethod `
  -Uri "https://gorouteiq.com/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": "Integration test key",
  "subscription_status": "trialing",
  "subscription_tier": "starter"
}

Sync inventory

Upserts current available inventory by SKU and warehouse. This endpoint feeds the same inventory snapshot RouteIQ uses for API and CSV routing. It 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 the client’s latest routing snapshot. When Use Inventory Availability is enabled, RouteIQ uses that snapshot to determine what can still be allocated to new orders.

Recommended integration pattern: sync inventory on the customer’s preferred schedule, then route orders. Between inventory syncs, RouteIQ protects against double-promising the same units by reducing available inventory as orders are routed.

{
  "source_name": "nightly inventory sync",
  "inventory": [
    {
      "sku": "SKU-A",
      "warehouse_id": "001",
      "quantity_available": 50,
      "unit_value": 12.50,
      "sku_description": "Sample item"
    },
    {
      "sku": "SKU-A",
      "warehouse_id": "002",
      "quantity_available": 10
    }
  ]
}

PowerShell example:

$body = @{
  source_name = "nightly inventory sync"
  inventory = @(
    @{ sku = "SKU-A"; warehouse_id = "001"; quantity_available = 50; unit_value = 12.50 },
    @{ sku = "SKU-A"; warehouse_id = "002"; quantity_available = 10 }
  )
} | ConvertTo-Json -Depth 8

Invoke-RestMethod `
  -Uri "https://gorouteiq.com/api/v1/inventory" `
  -Method POST `
  -Headers $headers `
  -ContentType "application/json" `
  -Body $body

Also accepted:

• available_qty instead of quantity_available
• external_warehouse_id instead of warehouse_id, for older integrations

Rules and limits:

• Maximum inventory API request body: up to 10,000 inventory rows per request.
• Plan-level inventory upload limits are also enforced: Trial 50,000 rows/upload, Starter 150,000 rows/upload, Pro 500,000 rows/upload, and Enterprise custom.
• Each SKU can appear once per warehouse in a single inventory sync request.
• Missing rows are not deleted. To mark a SKU/location out of stock, send 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
}

Route one order

Routes one customer order. The order may contain one line or many lines. A successful request creates a one-order routing run, writes the API order into canonical order history, returns the standard routing-run response shape, and 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 control settings and available transit data. The response uses the same wrapper as /orders/batch-route; read the single decision from results[0]. The routing run and order decision appear in Dashboard history, Files page routing runs, run-level exports, and report exports for the API key environment.

Route a batch of orders

Routes a synchronous batch of up to 5,000 orders and returns the standard routing-run response shape with one shared routing_run_id. A successful request writes the API orders into canonical order history and 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.

Priority Allocation controls how RouteIQ orders queued work before inventory is allocated. When Use Inventory Availability is enabled, RouteIQ reduces available inventory as orders are routed so the same units are not promised to multiple orders between inventory syncs. If Priority Allocation is disabled, RouteIQ still protects available inventory but follows upload/API order instead of VIP, priority level, and order timestamp fields.

When inventory is enabled, RouteIQ routes visible queued orders in this priority order:

• is_vip=true orders route first.
• priority_level routes next. Lower numbers route first, so priority 1 routes before 2, and 2 routes before 10.
• order_created_at routes next. Older timestamps route first when VIP and priority are tied or blank.
• Request/database order is used as a deterministic final tie-breaker.

Inventory sync behavior: client_inventory remains the latest inventory snapshot from the client. RouteIQ uses effective availability while routing, meaning the synced snapshot is reduced by inventory already allocated to prior routed orders. A successful new inventory sync refreshes the source snapshot.

Response fields

/api/v1/orders/route and /api/v1/orders/batch-route both return a routing-run wrapper. For single-order routing, results[] contains exactly one order result. For fulfillment automation, use shipments[] inside each result. Each item in shipments[] is one selected warehouse shipment.

{
  "routing_run_id": 205,
  "client_run_number": 40,
  "client_id": 21,
  "status": "completed",
  "orders_considered": 1,
  "orders_routed": 1,
  "full_count": 1,
  "split_count": 0,
  "partial_count": 0,
  "partial_split_count": 0,
  "none_count": 0,
  "results": [
    {
      "order_id": "API-1001",
      "routing_decision_id": 3519,
      "status": "FULL",
      "routing_quality": "Optimal",
      "reason": "Full shipment allowed",
      "policy_outcome": "clear",
      "policy_warning_count": 0,
      "policy_warning_codes": [],
      "policy_blocked_code": null,
      "policy_messages": [],
      "unroutable_reason_code": null,
      "unroutable_category": null,
      "unroutable_reason": null,
      "recommended_action": null,
      "total_shipment_value": 12.5,
      "preferred_warehouse": {
        "warehouse_id": "001",
        "warehouse_name": "NYC"
      },
      "selected_warehouse": {
        "warehouse_id": "001",
        "warehouse_name": "NYC"
      },
      "selected_warehouses": [
        {
          "warehouse_id": "001",
          "warehouse_name": "NYC"
        }
      ],
      "shipment_count": 1,
      "shipments": [
        {
          "selected_warehouse": {
            "warehouse_id": "001",
            "warehouse_name": "NYC"
          },
          "lines": [
            {
              "sku": "SKU-A",
              "ship_qty": 1
            }
          ]
        }
      ],
      "unfulfilled_lines": [],
      "explanation": {
        "selected_path": "FULL",
        "ranked_warehouses": [
          { "rank": 1, "warehouse_id": "001", "warehouse_name": "NYC" },
          { "rank": 2, "warehouse_id": "002", "warehouse_name": "Austin" },
          { "rank": 3, "warehouse_id": "003", "warehouse_name": "Los Angeles" }
        ],
        "decision_driver": {
          "code": "optimal_preferred_full",
          "message": "All items were available in the preferred warehouse NYC.",
          "sku": null,
          "required_qty": null,
          "available_qty": null,
          "short_qty": null,
          "warehouse": {
            "warehouse_id": "001",
            "warehouse_name": "NYC"
          }
        }
      }
    }
  ]
}

• shipments[]: primary execution field. Create one downstream shipment/work record per object.
• shipments[].selected_warehouse.warehouse_id: ship-from Warehouse ID.
• shipments[].lines[].ship_qty: quantity to ship from that warehouse.
• shipment_count: number of shipment objects returned.
• preferred_warehouse: top-ranked warehouse for reporting and diagnostics. It is not necessarily the ship-from warehouse.
• selected_warehouse: populated only when exactly one warehouse was selected; null for split decisions.
• selected_warehouses[]: compact summary of all warehouses selected for the order.
• policy_outcome and related policy_* fields: whether the route was clear, warned, or blocked by routing control settings.
• unfulfilled_lines[]: quantities that could not be allocated.

Split route with policy warnings

When a route uses multiple warehouses, selected_warehouse is null, selected_warehouses[] lists every selected origin, and shipments[] remains the execution payload.

{
  "order_id": "API-SPLIT-1001",
  "status": "SPLIT",
  "routing_quality": "Split",
  "reason": "Split shipment allowed",
  "policy_outcome": "warned",
  "policy_warning_count": 2,
  "policy_warning_codes": [
    "max_transit_days_warned",
    "split_shipment_warned"
  ],
  "policy_blocked_code": null,
  "policy_messages": [
    "Maximum transit days is set to Warn, so RouteIQ allowed this split shipment and flagged it for review.",
    "Split shipments are set to Warn, so RouteIQ allowed this split route and flagged it for review."
  ],
  "preferred_warehouse": {
    "warehouse_id": "001",
    "warehouse_name": "NYC"
  },
  "selected_warehouse": null,
  "selected_warehouses": [
    { "warehouse_id": "001", "warehouse_name": "NYC" },
    { "warehouse_id": "002", "warehouse_name": "Austin" }
  ],
  "shipment_count": 2,
  "shipments": [
    {
      "selected_warehouse": { "warehouse_id": "001", "warehouse_name": "NYC" },
      "lines": [{ "sku": "API-SPLIT-NYC", "ship_qty": 2 }]
    },
    {
      "selected_warehouse": { "warehouse_id": "002", "warehouse_name": "Austin" },
      "lines": [{ "sku": "API-SPLIT-AUSTIN", "ship_qty": 2 }]
    }
  ],
  "unfulfilled_lines": []
}

Status values

status describes the fulfillment result. routing_quality describes whether the selected route was ideal, suboptimal, split, or unroutable under the current settings.

• FULL: all requested units can ship from one warehouse. shipments[] has one object.
• SPLIT: all requested units can ship, but more than one warehouse is required. shipments[] has multiple objects.
• PARTIAL: some units can ship from one warehouse, but not all requested units. unfulfilled_lines[] identifies the shortage.
• PARTIAL_SPLIT: some units can ship across multiple warehouses, but not all requested units. shipments[] and unfulfilled_lines[] are both populated.
• NONE: no route is available. shipment_count is 0, shipments[] is empty, and unfulfilled_lines[] identifies the affected SKU quantities.

Routing quality values

• Optimal: RouteIQ selected the best available route under the active routing control settings.
• Suboptimal: RouteIQ found a shippable route, but had to fall back from the top preferred or ideal route because of inventory, rules, or another constraint.
• Split: RouteIQ used more than one warehouse or a split/partial-split path.
• Unroutable: RouteIQ could not create a shippable allocation.

Demo and regression CSVs

RouteIQ includes demo CSVs that can be used to validate routing behavior in a safe test client.

• data/demo/routeiq_demo_inventory.csv: inventory snapshot designed to show full, split, no-stock, and preference-control behavior.
• data/demo/routeiq_demo_orders.csv: primary demo order set for settings walkthroughs.
• data/demo/routeiq_demo_orders_test2.csv: same demo orders with different order IDs. Use this after the primary order file to regression-test inventory protection across separate routing runs.

Limits and usage

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 and written to routing history.
• POST /api/v1/orders/batch-route counts each order in the batch after successful decisions are saved and written to routing history.
• POST /api/v1/inventory does not count as routed-order usage, but inventory row limits still apply.
• Inventory is snapshot-based when Use Inventory Availability is enabled. RouteIQ reduces effective availability as orders are routed so the same units are not promised twice between inventory syncs.
• Batch route requests are limited to 5,000 orders per synchronous request for platform reliability. Async or managed batch processing is available upon request for larger scheduled bulk files.
• Required order fields: order_id or external_order_id, destination_zip, sku, and quantity. Recommended optional fields: unit_value, is_vip, priority_level, and order_created_at.
• When Priority Allocation is enabled, RouteIQ routes is_vip=true orders first, then orders with a priority_level value before blank priority levels. Among populated priority levels, lower numbers route first. RouteIQ then uses older order_created_at timestamps, then stable request/database order.
• is_vip is a boolean. Send true or false in API JSON. priority_level is an integer where lower numbers route first. RouteIQ does not normalize the scale; it simply sorts ascending.
• Priority Allocation only applies to orders in the current routing run. If orders are sent individually, RouteIQ cannot hold inventory for future priority orders it has not received.
• destination_zip must be a valid 5-digit ZIP. Invalid ZIPs return status: NONE with unroutable_reason_code: invalid_destination_zip.
• Inventory sync requests allow up to 10,000 rows per API request. Plan-level inventory upload limits are Trial 50,000 rows/upload, Starter 150,000 rows/upload, Pro 500,000 rows/upload, and Enterprise custom.
• Required inventory fields: warehouse_id, sku, and an available quantity field such as quantity_available. Optional: unit_value.
• When a routing request exceeds the client’s plan usage, RouteIQ returns 402 and does not increment usage.

Errors

• 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.
• 413: synchronous order batch exceeds the 5,000-order platform safety cap.
• 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: 001, 002, 003"
}

Inventory-aware vs routing-only mode

Use Inventory Availability is controlled in Routing Control.

• Enabled: RouteIQ checks SKU inventory, subtracts active RouteIQ reservations, and only selects warehouses with effective available quantity. Routed allocations are saved as active reservations until the next inventory sync or same-order reroute releases them.
• Inventory timing: Inventory availability is based on the latest inventory snapshot synced to RouteIQ minus active reservations created by prior routing decisions.
• Disabled: RouteIQ ignores SKU inventory and does not apply or create inventory reservations. RouteIQ recommends the best enabled warehouse using transit and configured warehouse rules. Transit ranking considers all enabled warehouses.
• When disabled, route responses are routing recommendations, not inventory‑confirmed fulfillment decisions.

Security notes

• Store API keys only in server‑side systems or secure integration tools.
• Do not place API keys in public repos, browser JavaScript, or shared spreadsheets.
• RouteIQ stores only hashed API keys and shows the secret only once at creation.
• Revoke unused keys from Account → API Access.