# Coupang Best Sellers & Rocket Delivery Flags (`nimbryxo-studio/coupang-product-finder-with-rocket-delivery-flags`) Actor

Collect Coupang best sellers by category (30 per page, optional child fan-out), keyword suggestions, or the category tree. Products include price, unit price, coupon, rating, Rocket delivery, and category breadcrumb. No user proxy, cookies, or login required.

- **URL**: https://apify.com/nimbryxo-studio/coupang-product-finder-with-rocket-delivery-flags.md
- **Developed by:** [Nimbryxo-studio](https://apify.com/nimbryxo-studio) (community)
- **Categories:** E-commerce, Automation, Developer tools
- **Security:** Limited permissions
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.49 / 1,000 results

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

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

## Coupang Best Sellers & Rocket Delivery Flags

Collect Coupang best sellers by category, Coupang's own keyword suggestions, or the Coupang category tree. The best-seller surface returns product identity, Korean-won pricing, discount, rating, review count, Rocket delivery, delivery promise, cashback, unit price, coupon and category breadcrumb data. No user proxy, cookie, or login is required; the actor selects its own Apify proxy route when Coupang blocks direct access.

Coupang's Akamai edge blocks keyword search, product-detail pages and review pages from non-Korean and datacenter IPs. Those modes are kept in the Mode dropdown for older saved tasks but are marked unavailable; they stop with a clear status message instead of returning an empty dataset. The actor ships the best-seller, keyword-suggestion and category-tree surfaces that work without user credentials.

### What this actor does

- Ranks the products on a Coupang best100 page from 1 to 30, with current price, original price, discount, rating, review count, Rocket delivery, delivery promise, cashback, unit price and coupon when Coupang publishes them.
- Walks all 15 top-level categories with `category=all` for up to 450 unique products from the top-level pages.
- Optionally walks a category's child best100 pages when `includeSubcategories=true`, stopping as soon as `maxItems` is reached.
- Deduplicates variants by `vendorItemId`, then `itemId`, then `productId` plus price.
- Returns Coupang's search-box suggestions for a list of keywords.
- Returns the Coupang category tree with category IDs, names, levels, parent IDs, paths and URLs.
- Keeps products tied to `productId`, `itemId` and `vendorItemId`, so variants are not merged by product ID alone.
- Omits fields Coupang does not publish for a product rather than writing nulls or placeholders.

### Output per best-seller product

| Field | Description |
|---|---|
| `productId` | Coupang product ID |
| `itemId` | Coupang item ID for the exact listing |
| `vendorItemId` | Coupang vendor-item ID for the exact seller option |
| `productName` | Product name as shown on Coupang |
| `price` | Current price in KRW |
| `originalPrice` | Original price in KRW, when higher than the current price |
| `discountRate` | Discount percentage, when greater than zero |
| `unitPrice` | Unit-price text, when Coupang shows one |
| `coupon` | Coupon object or text, when Coupang shows one |
| `rating` | Average star rating, when shown |
| `reviewCount` | Number of reviews, when shown |
| `imageUrl` | Product image URL |
| `productUrl` | Direct Coupang product URL, preserving item and vendor-item IDs |
| `isRocket` | `true` when the card carries Coupang's Rocket badge |
| `isRocketFresh` | `true` only when the card's Rocket image is the Rocket Fresh badge |
| `isFreeShipping` | `true` only when the card carries Coupang's free-shipping badge |
| `deliveryPromise` | Coupang's delivery promise text, when shown |
| `cashbackText` | Coupang's cashback text, when shown |
| `cashback` | Cashback amount in KRW parsed from `cashbackText` |
| `isSponsored` | Whether the card is marked as sponsored |
| `isSoldOut` | Whether the card is marked as sold out |
| `rank` | Position on the best100 page, starting at 1 |
| `categoryId` | Coupang best100 category ID that produced the row |
| `categoryName` | Human-readable category name |
| `categories` | Category breadcrumb path from the Coupang category tree, when available |
| `currency` | `KRW` |
| `source` | `bestSellers` |
| `recordType` | `product` |
| `scrapedAt` | UTC timestamp when the record was scraped |

Existing compatibility fields `brand`, `seller`, `description` and `categories` remain in the output schema. `brand`, `seller` and `description` are not published on the best100 page, so they are omitted from best-seller records rather than fabricated.

### Input

| Field | Type | Default | Description |
|---|---|---|---|
| `mode` | select | `bestSellers` | Best sellers, keyword suggestions, category tree, or a legacy mode. Search, product details and reviews are marked unavailable and stop with a clear status. |
| `category` | select | `electronics` | Best-seller category. Includes all 15 top-level categories plus All categories. Each page returns up to 30 products. |
| `categoryId` | string | – | Optional numeric Coupang best100 category ID or `/np/categories/` URL. Overrides the category dropdown. |
| `includeSubcategories` | boolean | `false` | Continue into child best100 pages until Maximum products is reached. Small `maxItems` values usually need no child pages. |
| `minPrice` | integer | – | Minimum price in KRW. |
| `maxPrice` | integer | – | Maximum price in KRW. |
| `rocketOnly` | boolean | `false` | Keep only products with Coupang's Rocket delivery badge. |
| `minRating` | number | – | Keep only products rated at least this many stars. Products without a rating are skipped. |
| `maxItems` | integer | `20` | Maximum products to return. One best100 page has at most 30. |
| `searchQueries` | string list | `[]` | Keywords for keyword suggestions. Korean or English. |
| `maxSuggestions` | integer | `10` | Maximum suggestions per keyword (1-10). |
| `maxCategories` | integer | `1000` | Maximum category nodes to return (1-5000). The full tree currently has about 2,740 nodes. |

#### Example: best sellers in electronics

```json
{
  "mode": "bestSellers",
  "category": "electronics",
  "maxItems": 30
}
```

#### Example: more than 30 rows with child categories

```json
{
  "mode": "bestSellers",
  "category": "electronics",
  "includeSubcategories": true,
  "maxItems": 100
}
```

#### Example: keyword suggestions

```json
{
  "mode": "keywordSuggestions",
  "searchQueries": ["laptop", "무선 이어폰"],
  "maxSuggestions": 10
}
```

#### Example: category tree

```json
{
  "mode": "categories",
  "maxCategories": 5000
}
```

#### Example: legacy mode alias

```json
{
  "mode": "categoryProducts",
  "category": "electronics",
  "maxItems": 30
}
```

`categoryProducts` is a visible legacy alias that returns best sellers. Legacy `keyword`, `sortBy` and `productIds` keys are tolerated and mapped or ignored as appropriate; they are not shown as separate current inputs.

### Use cases

- **Best-seller tracking** — see which products Coupang ranks highest in a category and how their prices and ratings change.
- **Price monitoring** — track current price, original price, discount, unit price and coupon availability.
- **Delivery analysis** — compare Rocket, Rocket Fresh, free-shipping and delivery-promise coverage.
- **Assortment research** — inspect brand and category composition across Coupang's top-level departments.
- **Search-box research** — collect Coupang's own keyword suggestions for content, SEO and merchandising work.
- **Category mapping** — export the live category tree with IDs, parent IDs, paths and URLs.

### Limits and behavior

- One Coupang best100 page exposes at most **30 products**. The actor pages into child categories only when `includeSubcategories=true` and `maxItems` is still unmet.
- `category=all` walks the 15 top-level pages and returns at most **450 unique products**; enable child fan-out to go deeper.
- Keyword search, product-detail pages and reviews are blocked without a Korean residential proxy. They are not claimed as working and fail with a clear status message.
- Keyword suggestions are capped at 10 per query by Coupang. Multiple queries can be supplied for broader coverage.
- The category tree currently contains about 2,740 nodes. Raise `maxCategories` to 5000 to export all of them.
- The actor uses its own hardcoded Apify proxy route when Coupang's edge blocks a request. Users do not configure a proxy.
- A blocked or parse-failed run fails honestly; it never exits successfully with an empty dataset.

### FAQ

**Do I need a Coupang account, cookie or proxy?**
No. The best-seller, keyword-suggestion and category-tree modes work without user credentials or proxy setup. The actor handles any required proxy route itself.

**Why can't I search Coupang by keyword?**
Coupang's search page is protected by Akamai and refuses non-Korean and datacenter traffic. This deployment ships the working best-seller, keyword-suggestion and category-tree surfaces instead of claiming a search path it cannot fill.

**How do I get more than 30 products from one category?**
Set `includeSubcategories=true` and raise `maxItems`. The actor reads child best100 pages in order until the limit is met.

**Why are some fields like `brand` or `seller` missing?**
Those fields are not published on Coupang's best100 cards. The actor omits them rather than inventing values. Product-detail enrichment is unavailable without the blocked detail page.

**Why is `categories` empty sometimes?**
The breadcrumb comes from Coupang's category tree. If the tree cannot be fetched on a run, products are still returned and the run status says the breadcrumb was unavailable.

**What currency are prices in?**
Korean Won (KRW), matching Coupang.

**How do I find a category ID?**
Category IDs are the numeric value in a Coupang category URL, e.g. `178155` in `https://www.coupang.com/np/categories/178155`.

**Is this affiliated with Coupang?**
No. This actor reads Coupang's public pages and is not affiliated with, endorsed by, or sponsored by Coupang.

### Data source

Coupang's public best100 category pages, keyword suggestion endpoint and category tree. No private API, partner API, user login or user-supplied credentials are used.

# Actor input Schema

## `mode` (type: `string`):

What to collect. Best sellers returns products with price, unit price, coupon, rating, Rocket delivery, and category breadcrumb; keyword suggestions and the category tree return discovery data. Search, product details, and reviews need a Korean residential proxy and are unavailable unless that connection is enabled.

## `category` (type: `string`):

Coupang best-seller category. Each category page returns up to 30 products; enable Include subcategories to continue into child pages until Maximum products is reached.

## `categoryId` (type: `string`):

Optional numeric Coupang best100 category ID or /np/categories/ URL. Overrides the category dropdown.

## `includeSubcategories` (type: `boolean`):

When true, after the selected category page is fetched, also fetch its child category best-seller pages until Maximum products is reached. Default false; small maxItems values usually need no child pages.

## `minPrice` (type: `integer`):

Only return products at or above this price in Korean won.

## `maxPrice` (type: `integer`):

Only return products at or below this price in Korean won.

## `rocketOnly` (type: `boolean`):

Keep only products with Coupang's Rocket delivery badge.

## `minRating` (type: `number`):

Keep only products rated at least this many stars. Products without a rating are skipped.

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

Maximum number of best-seller products to return. A single best100 page has at most 30; set includeSubcategories=true to continue into child pages, or use category=all.

## `searchQueries` (type: `array`):

Keywords for keyword suggestions (mode=keywordSuggestions). Korean or English.

## `maxSuggestions` (type: `integer`):

Maximum suggestions to return per keyword.

## `maxCategories` (type: `integer`):

Maximum category nodes to return from the Coupang category tree.

## Actor input object example

```json
{
  "mode": "bestSellers",
  "category": "electronics",
  "includeSubcategories": false,
  "rocketOnly": false,
  "maxItems": 3,
  "searchQueries": [],
  "maxSuggestions": 10,
  "maxCategories": 50
}
```

# Actor output Schema

## `products` (type: `string`):

Product records from Coupang best100 (recordType=product), including price, unit price, coupon, rating, Rocket delivery, and categories breadcrumb.

## `prices` (type: `string`):

Product records with current price, original price, unit price, coupon, discount, rating, Rocket flag, and categories breadcrumb.

## `categories` (type: `string`):

Category records from the Coupang category tree (recordType=category).

## `keywordSuggestions` (type: `string`):

Keyword suggestion records (recordType=keywordSuggestion).

# 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 = {
    "mode": "bestSellers",
    "category": "electronics",
    "includeSubcategories": false,
    "rocketOnly": false,
    "maxItems": 3,
    "searchQueries": [],
    "maxSuggestions": 10,
    "maxCategories": 50
};

// Run the Actor and wait for it to finish
const run = await client.actor("nimbryxo-studio/coupang-product-finder-with-rocket-delivery-flags").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 = {
    "mode": "bestSellers",
    "category": "electronics",
    "includeSubcategories": False,
    "rocketOnly": False,
    "maxItems": 3,
    "searchQueries": [],
    "maxSuggestions": 10,
    "maxCategories": 50,
}

# Run the Actor and wait for it to finish
run = client.actor("nimbryxo-studio/coupang-product-finder-with-rocket-delivery-flags").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 '{
  "mode": "bestSellers",
  "category": "electronics",
  "includeSubcategories": false,
  "rocketOnly": false,
  "maxItems": 3,
  "searchQueries": [],
  "maxSuggestions": 10,
  "maxCategories": 50
}' |
apify call nimbryxo-studio/coupang-product-finder-with-rocket-delivery-flags --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,nimbryxo-studio/coupang-product-finder-with-rocket-delivery-flags"
        }
    }
}
```

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/L6MWvn6dWdGRRNalz/builds/MNYO7cbYtIvVMGilg/openapi.json