CatBuy Services — API Docs

Overview

The CatBuy Services — Product API gives you one consistent endpoint to fetch structured product data from supported marketplaces. Send a supported product URL and receive a normalized JSON response containing the most important information such as title, price, images, variants / SKUs, and attributes.

This API is designed for reliable integration: predictable request format, clear error codes, and a response structure that works well for pricing, catalog ingestion, and product preview UIs.

JSON responses POST requests Rate limits Free trial + Pay-as-you-go + Subscriptions

Allowed Domains

Requests are accepted only for supported marketplace domains.

taobao.com

2.taobao.com

tmall.com

weidian.com

1688.com

goofish.com

If the URL host is not in the allow-list, the API returns an invalid_url error.

Endpoint

Fetch item/product information from a supported product URL.

Method POST

POST https://services.catbuy.app/api/v1/item

Headers

X-API-Key: YOUR_API_KEY Content-Type: application/x-www-form-urlencoded

Your API key is generated in the portal. Keep it private and only use it on server-side code.

Body Parameters

Parameter	Required	Description
url	Yes	Product URL (must be an allowed domain)
searchlang	No	Language hint for some localized fields (default: en)
tid	No	Optional tracking identifier (string) to correlate requests in your logs

Marketplace type is detected automatically from the URL domain.

Downloadable Example Request & Response

Dump a full example request, and inspect a complete real-world response.

Examples

Copy-paste examples for common languages.

Browser Console (Fetch)

fetch("https://services.catbuy.app/api/v1/item", { method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded", "X-API-Key": "YOUR_API_KEY" }, body: new URLSearchParams({ url: "https://weidian.com/item.html?itemID=7266541641", searchlang: "en" }) }) .then(r => r.json()) .then(data => console.log("Response:", data)) .catch(err => console.error(err));

For production, do not expose your API key in client-side code. Use a backend proxy.

Response Format

Responses are JSON. On success you typically receive code: 1 and a data object. The exact fields can vary by marketplace and product type, but the structure stays consistent: a small top-level wrapper and a rich product payload inside data.

Example Success

{ "code": 1, "msg": "return success", "data": { "title": "Product Name", "price": "41.0", "item_imgs": ["..."], "props": ["..."], "skus": { "...": "..." }, "sales_data": { "weight": 256.11, "size": 1805.74, "delivery_time": "2.5", "sales": 49 } } }

Tip: treat numeric-looking values as strings unless your integration explicitly converts them.

Field guide (common keys)

Below is a practical map of fields you will commonly see in real responses:

Path	Type	What it is
code	number	Success indicator (usually 1)
msg	string	Human-readable status text
data.api_source	string	Detected marketplace source
data.num_iid	string	Marketplace item identifier
data.title	string	Product title
data.price	string	Primary price value
data.pic_url	string	Main image URL
data.item_imgs	array	Image gallery
data.props	array	Attributes list
data.props_list	object	Variant option dictionary for mapping SKU properties to labels
data.skus.sku	array	SKU list: each entry combines options + price + quantity
data.skus.sku[].properties	string	Option keys, e.g. 0:0;1:3

Your integration should ignore unknown keys and only extract what you need.

Errors

Errors return JSON with an error code and often a message.

HTTP	error	Meaning
400	missing_parameter	Required parameter missing (e.g. url)
400	invalid_url	URL not allowed / unsafe / invalid host
401	missing_api_key	X-API-Key header not provided
401	invalid_api_key	API key not found / invalid format
402	insufficient_balance	Balance too low (top up required)
429	rate_limited	Too many requests (RPS limit)
500	server_error	Unexpected server-side error

Example: Invalid URL

{ "error": "invalid_url", "message": "URL not allowed or unsafe" }

Example: Rate limited

{ "error": "rate_limited", "message": "Max 2 requests/sec" }

Usage, Rate Limits & Billing

Free Trial

10 requests per month are free when you do not have an active subscription. After the free trial is used, requests are billed pay-as-you-go.

Pay-as-you-go

Costs $4 per 1000 requests (i.e. $0.004 per request). You need sufficient balance to continue.

Rate limit (RPS)

Default speed limit is 2 requests/second. High Speed add-on increases this limit (plan dependent).

Subscriptions

Subscriptions provide a daily request allowance. If you exceed your daily allowance, you can still continue by switching to pay-as-you-go (requires balance). Bandwidth is tracked monthly and may incur overage costs depending on plan and add-ons.

Manage plan & add-ons in Portal →

Best Practices

Keep your API key secret

Never embed the key in public websites or mobile apps. Use a backend proxy and store the key in environment variables.

Handle errors, retries, and timeouts

For 429 rate_limited, retry after a short delay and reduce request rate. For 402 insufficient_balance, top up in the portal. Always set a request timeout and log the response for debugging.

Blacklist / Risk Checker API

Check usernames, emails, phone numbers, addresses, IPs, and device fingerprints against the CatBuy risk database. Powered by 500+ confirmed chargeback users and 5,000+ risky identifiers.

Endpoint

POST /api/v1/blacklist/check

Authentication

Same as Product API: send X-API-Key: cbk_... header, or token (Firebase ID token) in POST body.

Parameters (POST body)

Param	Type	Required	Description
type	string	Yes	One of: email, username, phone, address, ip, device
value	string	Yes	The identifier to check (e.g. email address, IP, phone number)

Pricing

Pay-as-you-go

$0.03

per check

Risk Shield ($19/mo)

$0.02

500 included, then per extra

Risk Shield Pro ($49/mo)

$0.015

2,000 included, then per extra

Example Request

POST https://services.catbuy.app/api/v1/blacklist/check X-API-Key: cbk_... Content-Type: application/x-www-form-urlencoded type=email&[email protected]

Example Response (match found)

{ "ok": true, "result": { "blacklisted": true, "riskScore": 85, "category": "chargeback_user", "matchType": "email", "firstSeen": "2024-03-15", "reason": "Chargeback on order #ORD-8842", "details": { "orderId": "ORD-8842", "amount": "$520.00", "chargebackDate": "2024-03-15" } }, "checked": { "type": "email", "value": "[email protected]" }, "cost": 0.03, "timestamp": 1713168000 }

Example Response (no match)

{ "ok": true, "result": { "blacklisted": false, "riskScore": 0, "category": "none", "matchType": null, "firstSeen": null, "reason": null, "details": [] }, "checked": { "type": "email", "value": "[email protected]" }, "cost": 0.03, "timestamp": 1713168000 }

Response Fields

Field	Type	Description
blacklisted	boolean	Whether the identifier is in the blacklist
riskScore	integer	Risk score from 0 (clean) to 100 (highest risk)
category	string	Category: chargeback_user, risky_ip, risky_email, risky_phone, risky_address, risky_device, risky_username, or none
matchType	string\|null	The check type that matched (email, username, phone, address, ip, device)
firstSeen	string\|null	Date when this entry was first added (YYYY-MM-DD)
reason	string\|null	Human-readable reason for the blacklist entry
details	object	Additional metadata (order IDs, amounts, dates, etc.)

Error Codes

HTTP	Meaning
200	Check completed successfully
400	Missing or invalid type/value
401	Authentication required
402	Insufficient balance
405	Method not allowed (use POST)