Ozon Orders History CLI

A CLI utility that exports Ozon order history from a browser session where the user is already logged in.

The tool opens order pages by template: https://www.ozon.ru/my/orderdetails/?order=<userId>-<orderNumber>&selectedTab=archive and iterates order numbers in ascending order until it hits a missing or in-progress order.

Installation & Run

Using npx (recommended)

You can run the tool without local installation:

npx ozon-grabber start --user-id <userId> --start-order 0001

Local installation

cd cli
npm install
npm run build
node dist/index.js start --user-id <userId> --start-order 0001

Requirements

• Node.js 20+
• Chrome/Chromium running with the remote debugging port 9222 enabled
• The user is already authenticated in Ozon in that browser

Example Chrome launch (macOS):

/Applications/Google\ Chrome\ Beta.app/Contents/MacOS/Google\ Chrome\ Beta \
  --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-beta-mcp

Publication to npm

1. Login to npm (if not already):

   npm login

2. Verify build:

   npm run build

3. Publish:

   npm publish --access public

Run examples

# Start from order 0001
npx ozon-grabber start --user-id 30588125 --start-order 0001

Or with a limited number of orders:

npx ozon-grabber start --user-id 30588125 --start-order 0001 --max-orders 5

Enable backend upload and start from the backend-provided order id:

npx ozon-grabber start --user-id 30588125 --backend

When backend upload is enabled, each order is submitted immediately after parsing (fail-fast on upload errors).

Fetch the next order id from the backend:

npx ozon-grabber backend-next

This command uses the backend configuration options listed below.

Parameters

Required:

• --user-id <string>: user identifier (e.g., 30588125) Optional:
• --start-order <string>: starting order number (e.g., 0001); required when backend is disabled
• --backend: enable backend upload and backend-based start order resolution

Options:

• --verbose: verbose navigation and parsing logs
• --max-orders <n>: limit the number of orders to scan (debugging)
• --page-load-timeout-ms <ms>: how long to wait for order page widgets before declaring a missing order (default: 20000)
• --output <path>: output file path; if the extension is .csv, CSV is used, otherwise JSON
• --backend-url <url>: backend base URL (env: BACKEND_URL, default: http://localhost:3015)
• --backend-api-key <token>: backend API key (env: BACKEND_API_KEY, default: local-dev)

Output format (JSON)

{
  "userId": "30588125",
  "startOrder": "0001",
  "scannedOrders": 3,
  "stopReason": "in-progress",
  "stopOrderNumber": "0004",
  "orders": [
    {
      "orderId": "30588125-0001",
      "orderNumber": "0001",
      "orderDate": "2026-01-09",
      "items": [
        {
          "title": "...",
          "price": "...",
          "imageUrl": "..."
        }
      ]
    }
  ]
}

stopReason can be:

• in-progress - shipment widget text indicates the order is still in progress
• missing - neither the shipment widget nor the order title appeared after the load wait
• max-orders - --max-orders limit reached

How it works

• Connects to an already-open browser via chrome-devtools-mcp.
• Reuses a single tab and navigates to each order URL.
• Parses items inside data-widget="shipmentWidget".
• Reads the order header from data-widget="titleWithTimer" and parses orderDate in YYYY-MM-DD (UTC).
• Waits for shipmentWidget or titleWithTimer before declaring a missing order (logs show wait duration in verbose mode).
• Stops at the first in-progress or missing order.
• When backend upload is enabled, submits items per order using orderNumber as the backend orderId plus the userId field.
• The backend also downloads each item's imageUrl, stores it under backend/photos/, and replaces the stored value with that relative path; use POST /photos/download to refresh older rows that still reference remote URLs.

Common issues

• No data / empty results: make sure you're logged in to Ozon in the same browser.
• DevTools connection error: ensure Chrome is started with --remote-debugging-port=9222.