# US Import Shipment Monitor (Bill of Lading) — No Login (`flamboyant_liner/shipment-monitor`) Actor

Watch importers, suppliers or HS codes and get only NEW US customs bills of lading since the last run: shipper, consignee, product, HS code, containers, weight, arrival date. Data current to within days. Daily schedule. No login. MCP-ready. $20 per 1,000 alerts.

- **URL**: https://apify.com/flamboyant\_liner/shipment-monitor.md
- **Developed by:** [Khrystyna Skotte](https://apify.com/flamboyant_liner) (community)
- **Categories:** Lead generation, Automation, Developer tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $20.00 / 1,000 shipments

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## US Import Shipment Monitor — New Bills of Lading by Importer, Supplier or HS Code

Schedule this actor daily and it tells you **only what is new**: US customs bills of lading that arrived since the last run for the importers, overseas suppliers, HS codes and product keywords on your watchlist. It remembers every shipment it has already reported, so a daily run costs cents and never repeats itself.

Data comes from public US Customs and Border Protection (CBP) ocean manifest records as republished on ImportYeti (no login, no API key). Records are typically available 5 to 10 days after arrival.

### What you get per shipment

| Field | Example |
|---|---|
| `bolNumber`, `masterBolNumber`, `houseBolNumber`, `billType` | `CMDUCHN3760614`, `regular` |
| `arrivalDate` | `2026-09-22` |
| `shipper`, `shipperAddress`, `shipperCountry`, `shipperUrl` | `Hongkong Sun Rise Trade`, China |
| `consignee`, `consigneeAddress`, `consigneeCountry`, `consigneeUrl` | `Walmart Inc`, Bentonville AR |
| `productDescription` | `Trimmer Blower ... Lithium Ion Batteries Packed Equipment` |
| `hsCode` (HS-code watches only) | `8507` |
| `containerCount`, `weightKg`, `quantity`, `quantityUnit` | 1, 5374, 417, CTN |
| `shippingRoute`, `estimatedFreightUsd` | `Asia,Transatlantic`, 3377.42 |
| `sourceUrl` | link to the bill of lading page |
| `watchType`, `matchedWatch`, `matchedKeywords` | `consignee`, `Walmart`, `["battery"]` |
| `changeType`, `firstSeenAt`, `monitorId` | `new`, ISO timestamp, `default` |

Rows from HS-code watches carry the shipper but no consignee, because the source hides the importer on product pages. Vessel, voyage, ports and notify party are not exposed without a paid login and are therefore not included.

### Use cases

- **Find who imports what.** Watch an HS code (`8507` batteries, `9403` furniture, `0804.30` pineapples) and see every new overseas shipper of that product, with weight and container counts.
- **Monitor your competitors' suppliers.** Watch a competitor as a consignee: each new bill of lading names the factory that shipped to them, what it contained and how much.
- **Track a supplier's other customers.** Watch a factory as a shipper and learn which US companies receive its goods.
- **Lead generation.** Combine an HS code with `productKeywords` to build a daily list of active importers in your niche and hand it to sales.
- **Supply-chain risk.** Get alerted when a watched supplier starts shipping to a new US customer, or when a customer's volume from a region changes.

### Input

| Field | Default | Notes |
|---|---|---|
| `watchConsignees` | `["Walmart", "Home Depot"]` | US importers: company name, ImportYeti slug or `/company/...` URL |
| `watchShippers` | `[]` | Overseas suppliers: name, slug or `/supplier/...` URL |
| `watchHsCodes` | `[]` | 2 to 6 digit HS codes, dots allowed |
| `productKeywords` | `[]` | Keep only shipments whose cargo description contains one of these words |
| `lookbackDays` | 30 | Arrival-date window; keep at 14 or more because of the publishing lag |
| `maxNewPerWatch` | 5 | Cap per watched company / supplier / HS code |
| `maxItems` | 10 | Cap per run |
| `firstRunMode` | `emitAll` | or `baseline` |
| `webhookUrl` | `""` | POST target for the run summary |
| `monitorId` | `default` | Separate state per watchlist |
| `proxyConfiguration` | Apify residential | Keep it on: the source hides data after 25 company/supplier pageviews per IP, so every page is fetched through a fresh IP |

Names are resolved to the matching company with the most shipments and the match is cached in the monitor's state, so the search runs once per name. Pass a slug or URL to pin an exact page.

Each source page lists the 50 most recent shipments of that company, supplier or HS code. For very large importers (thousands of shipments per week) this is a sample of recent activity, not a complete feed; for most companies and suppliers it is complete.

### Scheduling

1. Create a task with your watchlist.
2. Run it once with `firstRunMode: "baseline"` to record the current state without emitting anything (or leave `emitAll` to get the current shipments right away).
3. Schedule the task daily. Every run emits only shipments that were not seen before and posts the summary to your webhook.

Shipments beyond `maxNewPerWatch` or `maxItems` are left unseen and appear on the next run, so nothing is lost when a watch spikes.

### Webhook payload

```json
{
  "monitorId": "default",
  "runAt": "2026-09-28T20:00:00.000Z",
  "newCount": 7,
  "scanned": 62,
  "seenTotal": 913,
  "baseline": false,
  "watches": [
    { "watch": "Walmart", "type": "company", "url": "https://www.importyeti.com/company/wal-mart", "title": "Wal Mart", "recent": 28, "newCount": 5 }
  ],
  "shipments": [ { "bolNumber": "...", "arrivalDate": "2026-09-22", "shipper": "...", "consignee": "...", "productDescription": "..." } ]
}
```

`shipments` holds the first 50 new records; the full list is in the run's dataset.

### Pricing

$0.005 per run plus $0.02 per new shipment. A daily monitor on ten companies that surfaces 20 new shipments a day costs about $12 a month.

# Actor input Schema

## `watchConsignees` (type: `array`):

US importers to watch for new inbound shipments. Give a company name ("Home Depot"), an ImportYeti slug ("home-depot-usa") or a full importyeti.com/company/... URL. Names are resolved to the importer with the most shipments and the match is cached per monitor ID.

## `watchShippers` (type: `array`):

Foreign suppliers to watch, e.g. "Foxconn Technology", a slug ("foxconn-technology") or an importyeti.com/supplier/... URL. Each new shipment shows which US company received it.

## `watchHsCodes` (type: `array`):

Harmonized System codes to watch for new shipments of a product category, 2 to 6 digits, e.g. 8507 (batteries), 0804.30 (pineapples), 9403 (furniture). Rows from HS watches carry the shipper but no consignee (the source hides it on product pages).

## `productKeywords` (type: `array`):

Case-insensitive words matched against the cargo description of every shipment found by the watches above. A shipment is emitted only if it contains at least one keyword. Empty = no filter.

## `lookbackDays` (type: `integer`):

Only consider shipments that arrived within this many days. US customs data is published with a lag of about one week, so keep this at 14 or more; the seen-state prevents duplicates across runs.

## `maxNewPerWatch` (type: `integer`):

Stop after emitting this many new shipments for each watched company, supplier or HS code. Shipments beyond the cap stay unseen and are emitted on the next run.

## `maxItems` (type: `integer`):

Overall cap on shipments emitted in one run.

## `firstRunMode` (type: `string`):

What to do when the monitor has no saved state yet. emitAll: treat every current shipment in the lookback window as new and emit it (good for a one-off pull or a first test). baseline: silently record every current shipment as seen and emit nothing, so the next scheduled run reports only what arrived since.

## `webhookUrl` (type: `string`):

Optional. After each run a JSON summary {monitorId, runAt, newCount, watches\[], shipments\[first 50]} is POSTed here (Slack/Zapier/Make/your API).

## `monitorId` (type: `string`):

Name of this watchlist. Each monitor ID keeps its own seen-state in a key-value store named shipment-monitor-<hash>, so you can run several profiles (e.g. "competitor-suppliers", "battery-imports") side by side.

## `proxyConfiguration` (type: `object`):

The source hides shipment data after 25 company/supplier pageviews per IP address, so keep Apify residential proxy on (a fresh IP is used for every page). HS-code pages are not limited.

## Actor input object example

```json
{
  "watchConsignees": [
    "Walmart",
    "Home Depot"
  ],
  "watchShippers": [],
  "watchHsCodes": [],
  "productKeywords": [],
  "lookbackDays": 30,
  "maxNewPerWatch": 5,
  "maxItems": 10,
  "firstRunMode": "emitAll",
  "webhookUrl": "",
  "monitorId": "default",
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}
```

# Actor output Schema

## `records` (type: `string`):

Dataset of new US import shipments (bills of lading) found in this run (JSON).

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "watchConsignees": [
        "Walmart",
        "Home Depot"
    ],
    "proxyConfiguration": {
        "useApifyProxy": true,
        "apifyProxyGroups": [
            "RESIDENTIAL"
        ]
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("flamboyant_liner/shipment-monitor").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "watchConsignees": [
        "Walmart",
        "Home Depot",
    ],
    "proxyConfiguration": {
        "useApifyProxy": True,
        "apifyProxyGroups": ["RESIDENTIAL"],
    },
}

# Run the Actor and wait for it to finish
run = client.actor("flamboyant_liner/shipment-monitor").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "watchConsignees": [
    "Walmart",
    "Home Depot"
  ],
  "proxyConfiguration": {
    "useApifyProxy": true,
    "apifyProxyGroups": [
      "RESIDENTIAL"
    ]
  }
}' |
apify call flamboyant_liner/shipment-monitor --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,flamboyant_liner/shipment-monitor"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/1aoVzi2Zsth7ylkfN/builds/Usbn7TSyyKEL4Tavs/openapi.json