# JD.com Shop API (jd.shop)

- Canonical page: [https://everyinfra.com/en/jd-api/shop](https://everyinfra.com/en/jd-api/shop?utm_medium=ai_doc&utm_campaign=page_md)
- Endpoint: POST https://api.everyinfra.com/api/v1/social with {"platform": "jd", "action": "shop", "params": {...}}
- Price: $0.02881 per call ($28.81 per 1,000 requests); failed calls and empty results are not charged
- Billing unit: every 24 rows you ask for count as one call; blocks that come back with no rows are not charged
- Returns: list, default 24, max 60 per call
- Pagination: pass next_page_token back as page_token for the next page, other params unchanged; each page is billed by its row count, one call per 24 rows, tokens last 24 hours; up to 168 rows
- Mode: sync; add "mode": "async" for slow tasks

JD.com Shop lists the products of one JD store, given its `shop_id`. Each row carries the product's `item_id`, title, link, price and currency, main image and the store's name, ID and page link. It shows what a store sells and at what prices, so brands can audit authorized resellers, sellers can study a competitor's range, and analysts can follow a store's assortment and pricing over time.

`shop_id` is the numeric store ID, or the store page link https://mall.jd.com/index-<number>.html minus any query string or fragment; a product ID will not do. Every `item_id` is a numeric JD product ID that the other JD capabilities take without conversion. `price` comes without a currency symbol, so read it with `currency`, and keep `shop_name` and `shop_url` with the rows to label stores in reports.

## Health

- Live health (24h percent, hourly and daily trends): https://api.everyinfra.com/api/v1/social/availability?platform=jd&action=shop

## Parameters

| name | type | required | default | description |
|---|---|---|---|---|
| shop_id | not declared | yes | not declared | Identifies the shop used by the `shop` action. Pass a digit string or the canonical legacy URL `https://mall.jd.com/index-<digits>.html` without a query or fragment; cross-host URLs are rejected, and this selector does not accept a product `item_id`. |
| page | integer | no | not declared | Page number of the shop's products, an integer; leave it out or send 1 for the first page. It runs from 1 to 168 ÷ `limit`, rounded up: 1–7 at the default `limit` 24, 1–3 at `limit` 60. With `page`, the page size is the `limit` of this request (1–60). Every page is billed at the price of page 1, tiered by the rows on that page alone, one call per 24 rows: at `limit` 24 a page is 1 call; at `limit` 60 a page of 60 rows is 3 calls, and the last page (rows 121–168, 48 rows) is 2 calls. Asking for `page` N directly bills N pages, the same as paging from page 1 to page N (the N − 1 pages before it as full pages, plus page N itself): `limit` 24 with `page` 5 is 5 calls, and `limit` 60 with `page` 3 is 3 + 3 + 2 = 8 calls. Blocks for rows of page N that did not come back are refunded, and nothing is charged for the request if page N is empty (for example, the list is not that long). A `page` that is out of range, 0, negative, fractional, a string such as "2" or a boolean is rejected with 422 before charging. A sync call reaches the deepest page, row 168; you do not need `"mode": "async"`. The deepest page (page 7 at `limit` 24) has no `next_page_token` and `pagination.stop_reason` is `depth_limit`; a list that is simply shorter ends with `end_of_list`. Page 1 is fetched fresh on every request. From page 2 on, rows are cut in order from one saved full list (up to 168 rows), and when you first ask for page 2 or later that list is at most one hour old. A page requested with `page` is cut from that list by its original position (page N is the `limit` rows starting at row (N − 1) × `limit` + 1); it does not know what the page 1 you got earlier looked like, so between a separately fetched page 1 and it, or between pages requested across an hour boundary, a few products can repeat or be missing: dedupe by `item_id` when merging. To read the whole list with no repeats, start at page 1 and follow `next_page_token`. `pagination.page` is the page number of this page, and `pagination.has_more` true means there is a next page: ask for `page` + 1, or pass `next_page_token` back as `page_token`. When both `page` and `page_token` are sent, `page_token` wins. A page requested with `page` also returns a `next_page_token`; the next call can use it with or without `page`. |
| page_token | not declared | no | not declared | Page token. Leave it out for the first page. When the response has a `next_page_token`, pass it back as `page_token`, exactly as received, to get the next page, with the other parameters unchanged. Every page keeps the page size of the `limit` of the request that returned the token, and a later `limit` has no effect. You can also skip the token and ask for a page number with `page`; when both are sent, `page_token` wins. A token is valid for 24 hours and works only for the same shop and the same account; a token used with another shop is rejected with 422 and not charged. Every page is billed at the price of page 1, tiered by the rows on that page alone, one call per 24 rows: at `limit` 24 each page is 1 call, so paging to page 5 is 5 calls; at `limit` 60 a page of 60 rows is 3 calls, and the last page (rows 121–168, 48 rows) is 2 calls. Blocks for rows that did not come back are refunded, and an empty page (for example, past the end of a short list) is not charged. Paging stops at row 168 (7 pages at `limit` 24), and a sync call gets there: you do not need `"mode": "async"`. The page that holds row 168 has no `next_page_token` and `pagination.stop_reason` is `depth_limit`; a list that is simply shorter ends with `end_of_list`. Page 1 is fetched fresh on every request. From page 2 on, rows are cut in order from one saved full list (up to 168 rows), and when you first ask for page 2 or later that list is at most one hour old. When you page from page 1 with `page_token`, every later page is cut from that same list: products already given on page 1 do not come back and nothing is skipped in between, so there are no repeats between pages. Slow paging makes no difference: the token chain keeps using the list it had when it first reached page 2. `pagination.page` is the page number of this page, and `pagination.has_more` true means there is a next page: pass `next_page_token` back as `page_token`. A page requested with `page` also returns a `next_page_token`; the next call can use it with or without `page`. |
| limit | integer (1–60) | no | 24 | The most rows to return in this call, an integer from 1 to 60. The default applies when you leave it out, and a call can return fewer rows. Larger values return 422 before any charge. |

## Response fields (items in `results`)

| field | meaning |
|---|---|
| item_id | JD numeric product ID. From search results you can pass it straight to detail, reviews, or price calls. |
| url | Link to the record on the platform. |
| title | Title. null when the platform has no titles (for example text-only posts). |
| price | Price as a number without a currency symbol; see currency. |
| currency | Currency code of the price (for example CNY, USD). If price is present but currency is null, do not assume a currency. |
| shop_id | JD numeric shop ID. |
| shop_name | Public shop name. |
| shop_url | Public JD shop page. |
| image_url | Image URL: in search, product_detail, shop and skus it is the product's main (cover) image; in description_images it is the description image of that row (the full-size https image on JD's image host). |
| available | Whether the item could be bought when it was read (product_detail, product_price and shop rows); false when out of stock, null when the page did not say. |
| platform | Source platform identifier, the same as platform in the request (for example xiaohongshu, tiktok). |

## Example

```bash
curl -X POST 'https://api.everyinfra.com/api/v1/social' \
  -H "Authorization: Bearer $EVERYINFRA_API_KEY" \
  -H 'Content-Type: application/json' \
  --data-raw '{
  "platform": "jd",
  "action": "shop",
  "params": {
    "shop_id": "1000004259"
  }
}'
```

```python
import os
import requests

response = requests.post(
    "https://api.everyinfra.com/api/v1/social",
    headers={"Authorization": f"Bearer {os.environ['EVERYINFRA_API_KEY']}"},
    json={
        "platform": "jd",
        "action": "shop",
        "params": {
            "shop_id": "1000004259",
        },
    },
    timeout=120,
)
print(response.status_code)
print(response.json())
```

## Response example

Real response to the example request above, captured 2026-11-07T14:47:42Z. `results` and `count` are real with personal information (names, handles, avatars, profile links, contact details) removed; the list keeps the first 2 of 24. `id`, `billing` and `quota` differ on every call, so only their shape is shown.

```text
{
  "id": "req_…",
  "platform": "jd",
  "action": "shop",
  "results": [
    {
      "item_id": "100386940168",
      "url": "https://item.jd.com/100386940168.html",
      "title": "HUAWEIWATCH GT7Pro碳晶黑46mm钛合金&纳米微晶陶瓷户外进阶运动21天超长续航华为智能手表",
      "price": 2688,
      "currency": "CNY",
      "shop_id": "1000004259",
      "shop_name": "华为京东自营旗舰店",
      "shop_url": "https://mall.jd.com/index-1000004259.html",
      "image_url": "https://img14.360buyimg.com/n0/jfs/t1/550965/17/7947/140219/6ae2b424F7cc9d94c/00835a05a09af40b.jpg",
      "platform": "jd"
    },
    {
      "item_id": "100343412080",
      "url": "https://item.jd.com/100343412080.html",
      "title": "华为MateBook 14 鸿蒙版笔记本电脑 国家补贴 2.8K OLED触控屏 鸿蒙AI 24GB 1TB原野绿 圆键盘",
      "price": 7599,
      "currency": "CNY",
      "shop_id": "1000004259",
      "shop_name": "华为京东自营旗舰店",
      "shop_url": "https://mall.jd.com/index-1000004259.html",
      "image_url": "https://img14.360buyimg.com/n0/jfs/t1/537470/34/12588/89809/6acef399F2a2483a1/00835a05a01f9084.jpg",
      "platform": "jd"
    }
  ],
  "next_page_token": …,
  "pagination": { … },
  "count": 24,
  "billing": {
    "charged": …,
    "charged_usd": …,
    "balance_after_usd": …,
    …
  },
  "quota": { … }
}
```

## FAQ

### Where do I find a JD shop ID?

On the store's own page: in https://mall.jd.com/index-<number>.html, the number is the shop ID, and you can pass either the number or that link without a query string. Results from JD Search and Product details also carry a `shop_id` for the store selling each product.

### Can I start from a product link?

Not directly, since `shop_id` takes a store ID and a product ID is not a valid value. Read the product with JD Product details first; the `shop_id` in that result names the store, and you can pass it here to list the rest of the store's range.

### How do I check prices and availability for the listed products?

The rows carry `price` and `currency` as the store lists them. For the current price and whether a product can be bought right now, pass its `item_id` to JD Product price; for variants, stock state and the full product record, use JD Product details. Buyer feedback comes from JD Reviews.

## Also

- Capability catalog (no key): https://api.everyinfra.com/api/v1/social/catalog?platform=jd
- OpenAPI: https://everyinfra.com/openapi.json · Agents guide: https://everyinfra.com/agents.md
