A bulk order splitter for SellerCloud

The problem

Splitting orders by hand, record by record

The brand already had an internal sales management system that collected sales, inventory and advertising data from every marketplace. But splitting orders in SellerCloud still sat outside it and still ate hours of the team’s time.

• Splitting orders

  • Some orders needed part of their contents moved into a separate order so they could ship on their own.
  • In SellerCloud that meant opening each order, finding the right line item and quantity, and splitting it by hand.
  • Nobody kept a record of which new order came from which original.

How it works

From an uploaded sheet to a result on every row

The team downloads a sample sheet with four columns (Order ID, Requested SKU, SellerCloud SKU, Qty), fills it in and uploads it. After that, nobody has to watch it.

1. Save the upload as a jobThe system reads each row and saves it to the job table, tagged with a job ID made from the file name and date. The request finishes straight away, so the page never waits on SellerCloud.
2. Hand the job to the workerA background thread calls the Node worker’s split-orders endpoint with the job ID. The worker reads the job’s rows back from MySQL, so the database is the whole agreement between the two services.
3. Match every row to a real line itemFor each order, the worker fetches the order from the SellerCloud API. It matches line items on both the fulfilled SKU and the SKU the customer originally ordered, so substituted and alias SKUs go to the right line.
4. Split with guardrailsThe worker combines each order’s lines into one OrderItemId / QtyToMove request and skips any line that asks to move more than the order holds. The split call gets a fresh access token and one retry.
5. Record the result for every rowThe worker saves the new split order ID or the exact error message against every row in one bulk upsert, then marks the rows done.
6. Report back in the team’s formatA job counts as complete only when every row in it is done. The page lists running and finished jobs and blocks new uploads while one is running. Each finished job downloads as a sheet with the split order ID or error on every row.

A small helper sits next to it: upload a sheet of Order ID + SKU and get each line’s SellerCloud Order Item ID back. The team uses it to prepare other bulk edits.

Engineering decisions

Why it’s built this way

Known limits

The hardest boundary: remote success and local persistence

The external operation and the local database update cannot share a single transaction. A split may succeed remotely while its local acknowledgement fails to persist.

Bounded retries help with transient failures, but they do not establish that repeating a state-changing command is safe. The recovery path above can link split orders back to their requests; it does not guarantee exactly-once execution or automatic recovery from every ambiguous outcome.

A further iteration would make uncertain outcomes explicit, reconcile remote state before replaying commands, and use provider-supported idempotency where available.

Outcome

What changed for the team

• A whole batch of order splits is now one upload and a download, instead of an afternoon of clicking through SellerCloud.
• Every split order is traceable back to the original order and SKU, with the reason recorded when a split fails.