Fulfillbot API Documentation

v1
OverviewAPI ReferenceWebhooksGuideManage API Keys →

Getting Started

The Fulfillbot Open API allows you to programmatically access our cross-border shopping services. You can search products from Chinese e-commerce platforms, manage shopping carts, place orders, track shipments, and more — all through a simple REST API.

Perfect for building custom integrations, automated purchasing agents, or connecting with AI assistants.

Authentication

All API requests require an API Key for authentication. Include your key in the Authorization header: 

Authorization: Bearer sk-your-api-key-here

To create an API Key, go to your API Keys page. Each key can be configured with specific permissions (scopes), IP whitelist, and rate limits.

Base URL

https://api.fulfillbot.com/api/v1/open

All endpoints are relative to this base URL.

Rate Limiting

Each API Key has its own rate limit (configurable, default 60 requests/minute). Rate limit info is included in response headers: 

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1712150400

When rate limited, the API returns 429 Too Many Requests.

Permission Scopes

ScopeDescription
products:readSearch and view products from Taobao, 1688, Weidian
cart:readView shopping cart items
cart:writeAdd, update, and remove cart items
orders:readView purchase orders and order details
orders:writeCreate purchase orders
warehouse:readView warehouse inventory
shipping:readView shipping/outbound orders
shipping:writeCreate shipping orders, cancel, confirm delivery, pay shipping fee
logistics:readQuery shipping channels, calculate freight, view supported countries
wallet:readView wallet balance and transaction history
profile:readView user profile and addresses
profile:writeUpdate user profile and addresses
favorites:readView favorite products
favorites:writeAdd and remove favorites
coupons:readView available coupons

Error Codes

StatusMeaning
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API Key
403Forbidden - Insufficient scope permissions or IP not whitelisted
404Not Found - Resource does not exist
429Too Many Requests - Rate limit exceeded
500Internal Server Error

Products

GET/products/searchproducts:read

Search products in the local catalog

GET/products/:idproducts:read

Get product detail by ID

POST/products/import/1688products:read

Import/fetch product details from 1688.com

GET/products/platform/taobao/searchproducts:read

Search products on Taobao

GET/products/platform/taobao/:itemIdproducts:read

Get Taobao product detail

GET/products/platform/1688/searchproducts:read

Search products on 1688

GET/products/platform/weidian/searchproducts:read

Search products on Weidian

GET/products/platform/weidian/:itemIdproducts:read

Get Weidian product detail

Shopping Cart

GET/cartcart:read

Get current shopping cart

POST/cart/itemscart:write

Add item to cart

POST/cart/items/batchcart:write

Batch add items to cart

PATCH/cart/items/:itemIdcart:write

Update cart item (quantity, selection)

PATCH/cart/items/batchcart:write

Batch update cart items

DELETE/cart/items/:itemIdcart:write

Remove item from cart

DELETE/cart/items/batchcart:write

Batch remove cart items

DELETE/cartcart:write

Clear entire cart

Purchase Orders

GET/ordersorders:read

Get purchase order list (paginated)

GET/orders/statsorders:read

Get order statistics

GET/orders/:idorders:read

Get purchase order detail

GET/orders/:id/statusorders:read

Get order status

GET/orders/:id/logisticsorders:read

Get order logistics info

GET/orders/:id/inspectionorders:read

Get order inspection result

POST/ordersorders:write

Create a purchase order

POST/orders/:id/cancelorders:write

Request order cancellation

Logistics

GET/logistics/countrieslogistics:read

Get supported destination countries

GET/logistics/shipping-methodslogistics:read

Get available shipping channels (filter by country, weight, cargo type)

POST/logistics/calculate-freightlogistics:read

Calculate shipping fee for a specific channel

POST/logistics/calculate-freight-batchlogistics:read

Calculate shipping fee for all available channels at once

GET/logistics/shipping-methods/:channelId/pricinglogistics:read

Get pricing rules for a specific channel

Shipping Orders

POST/shipping/createshipping:write

Create a shipping/outbound order

GET/shipping/ordersshipping:read

Get shipping order list

GET/shipping/orders/:idshipping:read

Get shipping order detail

POST/shipping/orders/:id/cancelshipping:write

Cancel a shipping order

POST/shipping/orders/:id/confirm-deliveryshipping:write

Confirm delivery received

Warehouse

GET/warehouse/packageswarehouse:read

Get warehouse packages/inventory

GET/warehouse/packages/statswarehouse:read

Get warehouse package statistics

GET/warehouse/packages/shippablewarehouse:read

Get packages ready to ship

GET/warehouse/packages/:idwarehouse:read

Get package detail

User Profile & Wallet

GET/user/profileprofile:read

Get user profile

PUT/user/profileprofile:write

Update user profile

GET/user/addressesprofile:read

Get saved addresses

POST/user/addressesprofile:write

Create a new address

PUT/user/addresses/:idprofile:write

Update an address

DELETE/user/addresses/:idprofile:write

Delete an address

GET/user/wallet/balancewallet:read

Get wallet balance

GET/user/wallet/transactionswallet:read

Get balance transaction history

Favorites & Coupons

GET/user/favoritesfavorites:read

Get favorite products

POST/user/favoritesfavorites:write

Add product to favorites

DELETE/user/favorites/:idfavorites:write

Remove from favorites

GET/user/coupons/availablecoupons:read

Get available coupons

GET/user/coupons/mycoupons:read

Get claimed coupons

Code Examples

cURL
curl -X GET "https://api.fulfillbot.com/api/v1/open/products/search?q=shoes&page=1" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json"
Python
import requests

API_KEY = "sk-your-api-key"
BASE_URL = "https://api.fulfillbot.com/api/v1/open"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Search products
resp = requests.get(f"{BASE_URL}/products/search",
    params={"q": "shoes", "page": 1},
    headers=headers)
products = resp.json()

# Add to cart
resp = requests.post(f"{BASE_URL}/cart/items",
    json={"productId": "xxx", "quantity": 2, "skuId": "yyy"},
    headers=headers)

# Get wallet balance
resp = requests.get(f"{BASE_URL}/user/wallet/balance", headers=headers)
balance = resp.json()
Node.js
const API_KEY = "sk-your-api-key";
const BASE = "https://api.fulfillbot.com/api/v1/open";

const headers = {
  "Authorization": `Bearer ${API_KEY}`,
  "Content-Type": "application/json"
};

// Search products
const res = await fetch(`${BASE}/products/search?q=shoes`, { headers });
const products = await res.json();

// Create shipping order
const shipRes = await fetch(`${BASE}/shipping/create`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    items: [{ inventoryId: "xxx", quantity: 1 }],
    recipientName: "John Doe",
    recipientCountry: "US",
    logisticsChannelId: "channel-id"
  })
});