Skip to main content

Replace Warehouse Provider Routing Rules

PUT 
/api/warehouses/:warehouse/provider-routing-rules

Replaces the warehouse's full set of shipping-method routing rules in one atomic operation. Rules not included in the request are removed; send "rules": [] to clear every rule. Returns the refreshed rule set in the same shape as Get Warehouse Provider Routing Rules, plus a message. The change is recorded on the warehouse's activity log. It affects fulfillment orders dispatched after the save; orders already submitted to a provider are not re-routed.

Required scope: warehouses:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Body fields:

  • rules (array, required — must be present, may be empty) — the complete rule set.
  • rules.*.shipping_method_id (integer, required) — an existing shipping method. Each method may appear only once; pickup (Click & Collect) methods are not allowed.
  • rules.*.integration_instance_id (integer|null, required key) — the target shipping-provider integration instance, or null to route the method to Manual. Must be an active, connected shipping provider that is mapped to this warehouse.

How a fulfillment order's shipping provider is resolved (first match wins):

  1. Amazon FBA / Walmart WFS warehouse, or a Click & Collect (pickup) shipping method — fixed; never routed.
  2. Per-order override on the fulfillment order (requested_integration_instance_id, or requested_fulfillment_type: "manual") — set via PATCH /api/fulfillment-orders/{fulfillmentOrder}/shipping.
  3. Routing rule for the order's shipping method at this warehouse (the fulfillment order's requested shipping method, else the sales order's).
  4. The warehouse's default provider (order_fulfillment).
  5. Otherwise Manual.

A rule whose integration_instance_id is null routes the method to Manual. A rule pointing at a provider that is no longer usable (disconnected, inactive, or no longer mapped to this warehouse) is skipped at dispatch and the order falls through to the warehouse default.

Returns 422 when:

  • rules is missing (send an empty array to clear).
  • A rule has no shipping_method_id, or the method does not exist.
  • A shipping method appears in more than one rule ("<method> already has a rule on this warehouse").
  • A shipping method is a pickup method.
  • integration_instance_id is omitted, does not exist, or is not an active shipping provider.
  • The provider is not mapped to this warehouse ("<provider> is not mapped to this warehouse").
  • The warehouse is an Amazon FBA or Walmart WFS warehouse — the marketplace fulfills every order from those, so they cannot carry rules.

Returns 403 without the warehouses.update permission and 404 when the warehouse does not exist.

Requires permission: warehouses.update

Authentication: Requires Bearer token.

Request​

Responses​

OK

Response Headers
    Content-Type