Delivery dates are a data problem: 62 lanes, 385k SKUs and a calendar that zeroes production

We run a wholesale catalogue of 385,315 listings from 5,233 Chinese factories, and we ship to 62 countries. Every product page has to answer one question a buyer actually cares about: when will this be on my shelf?

For a long time we treated that answer as a field. It is not a field. It is a pipeline with three independent inputs, and one of those inputs drops to zero for six weeks every year. This post is about how we model it, with the real numbers from our own data.

The naive version, and why it breaks

The obvious model is a lookup:

const dni = srokiPoStrane[strana];   // "18-40"

That is wrong in three separate ways, and each one shows up as an angry email.

1. It assumes one transport mode. Air, rail and sea to the same country differ by a factor of five.
2. It assumes the goods exist. Half a catalogue is stock, half is made to order.
3. It assumes a factory is working today. For roughly six weeks a year, it is not.

Input one: the transit matrix

Our matrix is 62 destinations × 3 modes. Not every cell is filled — and the empty cells carry as much information as the full ones.

Region	Countries	Air	Rail	Sea
Europe	28	5–9 d	12–22 d (all 28)	22–38 d
Asia-Pacific	11	1–9 d	—	2–30 d
Middle East	9	4–8 d	18–25 d (1 of 9)	14–32 d
Africa	7	6–12 d	—	22–40 d
South America	4	11–15 d	—	30–45 d
North America	3	8–15 d	—	18–40 d

Rail exists for 29 of 62 destinations and for exactly one reason: continuous track from China. Every European destination has a rail figure; the Middle East has one (Iran); the Americas, Africa and the island parts of Asia-Pacific have none and never will. A null in that column is not missing data — it is geography, and the code should say so:

// null в колонке rail — это НЕ «данных нет», это «рельсов нет».
// Их нельзя дозаполнить позже и нельзя подставить среднее по региону.
const dostupno = ['air', 'sea', ...(lane.rail ? ['rail'] : [])];

If you let a null fall through to "unknown" your UI will eventually offer a train to Brazil.

The widest spread is Asia-Pacific: sea from 2 days to 30. A single regional average would be useless for both ends of it. Aggregate for display, never for a promise.

Input two: does the thing exist yet

Across a 6,000-item sample of our live catalogue:

• median price ¥11.04
• 47% of items under ¥10, 90% under ¥50
• median MOQ 72 pieces, with the common cartons at 24 / 36 / 48 / 72 / 96 / 120

Those carton sizes matter to the date calculation more than the price does. A stocked carton ships this week. Anything below a carton does not ship at all — we do not break cartons — and anything above available stock becomes a production order with its own lead time of 15–30 days, stretching to 45 in peak season.

So the second input is not a number, it is a branch:

function proizvodstvo(poziciya, kolichestvo) {
  if (kolichestvo % poziciya.moq !== 0) return { otkaz: 'ниже коробки' };
  if (kolichestvo <= poziciya.ostatok) return { dney: 0 };          // со склада
  return { dney: poziciya.pik ? [30, 45] : [15, 30] };              // под заказ
}

Input three: the calendar that zeroes everything

This is the one that generic logistics models miss, and it is the largest single term in the equation.

Chinese New Year 2027 falls on 6 February. The official holiday is about a week. The real shutdown is roughly six weeks: factories wind down two to three weeks ahead as workers leave for their home provinces, and take three to four weeks afterwards to get back to full output, because a meaningful share of workers do not return to the same employer.

There is a second, smaller one: Golden Week, 1–7 October. Only a week, but it lands inside the run-up to the Western fourth quarter, when every hour of capacity is already booked. A week lost there cannot be made up.

In code, the calendar is not an offset you add. It is a function that can make a date impossible:

// Календарь не «сдвигает» срок — он может сделать срок недостижимым.
// Это разные вещи, и ответ клиенту тоже разный: «позже» или «в этом сезоне никак».
function skvozKalendar(startDate, dney) {
  const okna = prostoi(startDate.getFullYear());   // CNY ± wind-down, Golden Week
  let ostalos = dney, d = new Date(startDate);
  while (ostalos > 0) {
    d.setDate(d.getDate() + 1);
    if (!vOkne(d, okna)) ostalos--;                // в простое счётчик не идёт
  }
  return d;
}

The practical consequence, and the thing almost nobody acts on: for a small importer the cheapest available improvement is not a better price, it is ordering six weeks earlier. It costs nothing and it moves you out of the queue. We wrote the full year-by-year breakdown up as a production calendar page, because it turned out to be the single question buyers asked most.

Putting it together, backwards

The only direction that works is backwards, from the shelf date to the order date. Four blocks, counted separately:

shelf date
  − marketplace check-in      up to 14 d
  − freight (mode, lane)       2–45 d
  − consolidation + QC          3–5 d
  − production                  0–45 d
  − calendar blackout           0–42 d
= order date

Run that for November 2026 and you get cut-offs that look absurdly early but are simply arithmetic: sea to the US had to leave by early September, rail and road to Europe by mid-September, air holds until mid-October at peak-season rates.

What we changed in the code

Three rules came out of this, and all three were bought with support tickets:

1. Never store a delivery date. Store the inputs and compute on read. A stored date is a promise that silently rots.
2. Distinguish "no data" from "not possible". Empty rail is not a gap in the dataset.
3. Let the calendar veto. The function that returns a date must be allowed to return "not this season" instead of a later date, because those are different answers to the buyer.

The full transit table by country is public on our shipping and transit times page, and the live catalogue with prices and carton sizes is at opttoyschina.com. If you model delivery dates for physical goods and you have solved the calendar-veto problem more elegantly, I would genuinely like to read it.