Salla order auto-assignment: reliable employee routing

Salla's Order Assignment API can store automatic employee-assignment rules based on country, city, order status and branch. That is useful, but a rule write is not proof that every eligible order reached the intended person. A production integration should manage rules as versioned desired state, read them back after each change, observe the employees actually assigned to real orders, and reconcile unassigned or ambiguous cases before they become orphan orders.

This is a practical engineering explainer, not a product announcement. The documented endpoints and scopes below are facts from Salla's official Merchant API documentation, verified on October 27, 2026. The control plane, overlap checks, rollout process and operational metrics are application-side recommendations. Salla's public pages reviewed for this guide do not define rule precedence when several employees can match, so this article does not invent one.

The answer first

Keep one declarative assignment policy per store. Resolve every referenced Salla ID before publishing, normalize rules into a stable order, compare the desired policy with the rules returned by Salla, and apply only the required create or update operations. Then inspect selected orders through the assigned-employees endpoint and run a continuous orphan-order query.

The important distinction is between configured rules and observed assignments. The first expresses intent; the second shows the platform state that operations can act on.

Start with the documented contract

Salla documents four Order Assignment operations. List Auto Assignment Rules uses GET /orders/assignment/rules and requires the orders.read scope. Create Auto Assignment Rules uses POST /orders/assignment/rules with orders.read_write. Update Auto Assignment Rule uses PUT /orders/assignment/rules/{rule_id}, also with orders.read_write. Order Assigned Employees Details uses GET /orders/assignment/{order_id} to return the employees attached to one order.

The create example associates a user_id with a rules array. The documented rule entities include country, city, status and branch, each with a value identifier. The update example replaces the rule's entity/value collection at a known rule ID. These facts make a read-compare-write workflow possible.

The documentation reviewed for this guide does not state:

• whether overlapping rules are evaluated in a particular order;
• whether one match stops evaluation or multiple employees may be assigned;
• whether publishing a rule retroactively reassigns existing orders;
• whether changing a branch rule changes inventory ownership, fulfilment allocation or courier selection.

Treat those points as unknown until a documented answer or controlled store test proves them. Design rules to be mutually exclusive where practical, and never promise deterministic selection from undocumented precedence.

Separate employee routing from fulfilment routing

An employee assignment answers, “Which staff member is responsible for this order?” It does not answer, “Which branch owns stock?” or “Which courier will collect the parcel?” Salla exposes branch data and separate branch-allocation capabilities. Keep these domains distinct:

This separation prevents a support-routing change from silently becoming a fulfilment change. It also gives each integration permission only for the job it performs.

Model assignment as desired state

Store the policy in a provider-neutral form and compile it into Salla's entity/value payload. A hypothetical policy might look like this:

policy_version: 17
store_key: merchant-42
routes:
  - route_key: riyadh-ready
    employee_ref: ops-riyadh-a
    match:
      country: SA
      city: riyadh
      status: ready
      branch: riyadh-main
  - route_key: jeddah-ready
    employee_ref: ops-jeddah-a
    match:
      country: SA
      city: jeddah
      status: ready
      branch: jeddah-main

The human-readable references above are application aliases, not values to send to Salla. Resolve them to current platform IDs, keep the mapping with the policy version, and fail closed when an alias is missing or points to an inactive object. Never use employee names as stable identity.

Normalize entity names and values before hashing. Sort the rule elements, remove duplicates, and compute a digest from employee ID plus the normalized rule set. This makes equivalent configurations compare equal even if their input order differs.

Detect overlap before publishing

Overlap is a policy problem before it is an API problem. Two routes overlap when one order could satisfy both sets of conditions. Run a static check on every change:

1. Expand each route into a normalized tuple of country, city, status and branch constraints.
2. Compare every active route pair for the same store.
3. Mark disjoint values as safe.
4. Flag missing constraints and identical or intersecting values for review.
5. Require an explicit exception record if the business truly wants multiple eligible employees.

A broad country=SA rule can overlap every city-specific Saudi rule. A city rule without a branch can overlap several branch-specific routes. Because precedence is not documented in the pages reviewed here, do not treat rule order as the fix. Narrow the policy or accept the overlap as an observable, tested business decision.

Publish with read-back, not blind writes

Use a staged plan:

load desired policy
  -> resolve platform IDs
  -> reject invalid or overlapping routes
  -> GET current rules
  -> calculate create/update/no-op actions
  -> snapshot current state
  -> apply one bounded change set
  -> GET rules again
  -> compare normalized state
  -> sample real order assignments

Use orders.read for inventory and audit jobs that only list configuration or inspect assignments. Reserve orders.read_write for the publisher. Do not copy merchant access tokens into configuration, logs, metrics or dead-letter payloads.

If a write times out, the outcome is uncertain. Read current rules before retrying. A local idempotency key can deduplicate your jobs, but it cannot prove that an upstream write did not already succeed. Store the request digest, start time, HTTP outcome and read-back result under one change ID.

Rollback should replay the previous known-good desired-state snapshot. Do not generate a blind “inverse” request from memory: the remote state might have changed between failure and recovery.

Observe assignments on orders

Configuration read-back proves only that rules exist. The assigned-employees endpoint lets the integration check the employees attached to a specific order. Build three verification levels:

• Canary: after a policy change, inspect a small set of known, non-sensitive test or newly eligible orders.
• Sample: periodically inspect a bounded sample from every active route.
• Exception: inspect every order that becomes old enough to violate the unassigned-order service target.

Store only the employee IDs and minimum display data needed for the operational task. Keep customer and order details out of assignment logs. An assignment is workflow metadata, not an authorization boundary: the application must still enforce its own access controls.

Reconcile orphan and ambiguous orders

Create an explicit state machine:

Reconciliation should be bounded by a recent time window and business-critical statuses. It should not rescan an entire merchant history on every run. Use the sequential-order-backfill pattern for historical discovery and the per-store API budget for fair scheduling.

Useful metrics are the age of the oldest eligible unassigned order, orphan rate, ambiguous-assignment count, policy-to-remote drift, change verification latency, and reconciliation failures. Avoid unbounded labels such as raw order or employee IDs in shared metrics; keep those in access-controlled diagnostics.

Failure-safe rollout

1. Export and normalize the current rules.
2. Resolve all desired employee, status, city and branch IDs.
3. Run overlap and inactive-reference checks.
4. Dry-run the change plan and review the exact diff.
5. Apply one store or one route group first.
6. Read back the rules and compare their normalized digest.
7. Inspect real assignments for representative orders.
8. Watch the orphan and ambiguous queues for a full operating cycle.
9. Expand gradually; restore the previous snapshot if verification fails.

Do not switch every store at once. A syntactically valid rule can still encode the wrong operational boundary.

Best practices

• Keep policy, platform identifiers and observed assignments as separate records.
• Make route conditions mutually exclusive when the business expects one owner.
• Validate referenced branches, statuses and employees before each publish.
• Use least-privilege tokens and a single publisher per store.
• Read after every uncertain or successful write.
• Reconcile assignments from real orders, not configuration alone.
• Preserve the previous desired-state snapshot and a complete change trail.

Anti-patterns

• Creating one broad rule for every employee and assuming Salla will choose fairly.
• Depending on rule array order as undocumented priority.
• Rewriting every rule when only one normalized route changed.
• Treating employee names as stable identifiers.
• Assuming a new rule retroactively repairs historical orders.
• Using assignment as proof of inventory, shipping or authorization state.
• Retrying a timed-out write without first reading current state.

Implementation checklist

1. Define a provider-neutral routing policy and version it.
2. Resolve Salla IDs and reject inactive or missing references.
3. Add a static overlap detector.
4. Fetch and normalize current remote rules.
5. Produce a deterministic change plan.
6. Publish through a least-privilege worker.
7. Read back and verify the normalized digest.
8. Inspect assigned employees on canary orders.
9. Run orphan, ambiguous and drift reconciliation.
10. Alert on age and impact, not merely raw queue length.

Related reading: Salla light-order hydration, Salla sequential order backfills, Salla API budgets and fair queues, and the E-commerce Engineering hub.

Primary references

• Salla — Order Assignment API collection
• Salla — List Auto Assignment Rules
• Salla — Create Auto Assignment Rules
• Salla — Update Auto Assignment Rule
• Salla — Order Assigned Employees Details
• Salla — List Branches
• Wikimedia Commons — Honeywell 4600g barcode scanner
• Creative Commons Attribution-ShareAlike 4.0

Prepared by: Noor Yasser