API Reference - Fulfillbot API

Products

GET/products/searchproducts:read

Search products in the local catalog.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search keyword
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 20, max: 100)
categoryId	integer	No	Filter by category ID
sort	string	No	Sort field: price, sales, created (default: relevance)
order	string	No	Sort order: asc, desc

Request

GET /products/search?q=nike+shoes&page=1&limit=10
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "id": 12345,
        "title": "Nike Air Max 90 Sneakers",
        "price": 299.00,
        "originalPrice": 499.00,
        "currency": "CNY",
        "platform": "taobao",
        "imageUrl": "https://img.example.com/...",
        "shopName": "Nike Official",
        "sales": 1580,
        "categoryId": 23
      }
    ],
    "total": 256,
    "page": 1,
    "limit": 10
  }
}

GET/products/:idproducts:read

Get detailed product information including SKU variants.

Path Parameters

Parameter	Type	Description
id	integer	Product ID

Request

GET /products/12345
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "id": 12345,
    "title": "Nike Air Max 90",
    "description": "Classic sneaker...",
    "price": 299.00,
    "originalPrice": 499.00,
    "currency": "CNY",
    "platform": "taobao",
    "platformItemId": "6789012345",
    "imageUrl": "https://...",
    "images": ["https://..."],
    "shopName": "Nike Official",
    "shopUrl": "https://...",
    "sales": 1580,
    "stock": 200,
    "categoryId": 23,
    "skus": [
      {
        "skuId": "s001",
        "name": "Black / US 9",
        "price": 299.00,
        "stock": 50,
        "image": "https://..."
      },
      {
        "skuId": "s002",
        "name": "White / US 9",
        "price": 319.00,
        "stock": 30,
        "image": "https://..."
      }
    ],
    "attributes": [
      { "name": "Material", "value": "Leather" },
      { "name": "Origin", "value": "Vietnam" }
    ]
  }
}

GET/products/platform/taobao/searchproducts:read

Search products directly on Taobao. Also available for /platform/1688/search and /platform/weidian/search.

Query Parameters

Parameter	Type	Required	Description
q	string	Yes	Search keyword (Chinese keywords recommended)
page	integer	No	Page number (default: 1)

Request

GET /products/platform/taobao/search?q=运动鞋&page=1
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "itemId": "6789012345",
        "title": "2024新款运动鞋男...",
        "price": "139.00",
        "imageUrl": "https://...",
        "shopName": "某运动专营店",
        "sales": "3000+",
        "location": "福建 莆田"
      }
    ],
    "page": 1,
    "hasMore": true
  }
}

POST/products/import/1688products:read

Import/fetch product details from 1688.com by providing the product URL or ID.

Request Body

Field	Type	Required	Description
url	string	Yes*	Product URL from 1688.com
offerId	string	Yes*	1688 offer ID (*either url or offerId required)

Request

POST /products/import/1688
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "url": "https://detail.1688.com/offer/xxx.html"
}

Response 200

{
  "data": {
    "id": 12346,
    "title": "Wholesale Sports Shoes",
    "price": 89.00,
    "platform": "1688",
    "skus": [...],
    "minOrder": 2,
    "images": [...]
  }
}

Shopping Cart

GET/cartcart:read

Get the current user's shopping cart with all items.

Request

GET /cart
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "id": 501,
        "productId": 12345,
        "title": "Nike Air Max 90",
        "skuId": "s001",
        "skuName": "Black / US 9",
        "price": 299.00,
        "quantity": 2,
        "imageUrl": "https://...",
        "selected": true,
        "stock": 50,
        "remark": ""
      }
    ],
    "totalItems": 1,
    "totalAmount": 598.00
  }
}

POST/cart/itemscart:write

Add a single item to the shopping cart.

Request Body

Field	Type	Required	Description
productId	string	Yes	Product ID
skuId	string	Yes	SKU variant ID
quantity	integer	Yes	Quantity (min: 1)
remark	string	No	Special instructions

Request

POST /cart/items
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "productId": "12345",
  "skuId": "s001",
  "quantity": 2,
  "remark": "Size US 9"
}

Response 201

{
  "data": {
    "id": 502,
    "productId": 12345,
    "skuId": "s001",
    "quantity": 2,
    "message": "Item added to cart"
  }
}

POST/cart/items/batchcart:write

Add multiple items to the cart in a single request.

Request

POST /cart/items/batch
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "items": [
    { "productId": "12345", "skuId": "s001", "quantity": 2 },
    { "productId": "67890", "skuId": "s010", "quantity": 1 }
  ]
}

Response 201

{
  "data": {
    "added": 2,
    "items": [
      { "id": 502, "productId": "12345" },
      { "id": 503, "productId": "67890" }
    ]
  }
}

PATCH/cart/items/:itemIdcart:write

Update a cart item's quantity or selection status.

Request Body

Field	Type	Required	Description
quantity	integer	No	New quantity
selected	boolean	No	Selection state for checkout

Request

PATCH /cart/items/502
Authorization: Bearer sk-xxx

{ "quantity": 3, "selected": true }

Response 200

{
  "data": {
    "id": 502,
    "quantity": 3,
    "selected": true,
    "message": "Cart item updated"
  }
}

DELETE/cart/items/:itemIdcart:write

Remove a single item from the cart. Use DELETE /cart to clear the entire cart.

Request

DELETE /cart/items/502
Authorization: Bearer sk-xxx

Response 200

{
  "data": { "message": "Item removed" }
}

Purchase Orders

POST/ordersorders:write

Create a purchase order. The product cost is deducted from your wallet balance.

Request Body

Field	Type	Required	Description
items	array	Yes	Array of order items
items[].productId	string	Yes	Product ID
items[].skuId	string	Yes	SKU variant ID
items[].quantity	integer	Yes	Quantity
items[].remark	string	No	Item-level notes
remark	string	No	Order-level notes
couponId	integer	No	Coupon ID to apply

Request

POST /orders
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "items": [
    {
      "productId": "12345",
      "skuId": "s001",
      "quantity": 2,
      "remark": "Check quality"
    }
  ],
  "remark": "Handle with care"
}

Response 201

{
  "data": {
    "orderNo": "ORD-20240115-001",
    "status": "pending",
    "totalAmount": 598.00,
    "serviceFee": 30.00,
    "currency": "CNY",
    "items": [
      {
        "productId": 12345,
        "title": "Nike Air Max 90",
        "skuName": "Black / US 9",
        "price": 299.00,
        "quantity": 2
      }
    ],
    "createdAt": "2024-01-15T08:30:00Z"
  }
}

GET/ordersorders:read

Get paginated list of purchase orders.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 20)
status	string	No	Filter by status: pending, paid, purchased, shipped_to_warehouse, in_warehouse, completed, cancelled

Request

GET /orders?page=1&limit=10&status=in_warehouse
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "orderNo": "ORD-20240115-001",
        "status": "in_warehouse",
        "totalAmount": 598.00,
        "itemCount": 1,
        "createdAt": "2024-01-15T08:30:00Z"
      }
    ],
    "total": 25,
    "page": 1,
    "limit": 10
  }
}

GET/orders/:idorders:read

Get full detail of a purchase order. Also supports GET /orders/:id/status for just the status, GET /orders/:id/logistics for tracking, and GET /orders/:id/inspection for QC results.

Request

GET /orders/ORD-20240115-001
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "orderNo": "ORD-20240115-001",
    "status": "in_warehouse",
    "totalAmount": 598.00,
    "serviceFee": 30.00,
    "currency": "CNY",
    "platform": "taobao",
    "items": [...],
    "logistics": {
      "trackingNo": "SF1234567890",
      "carrier": "SF Express"
    },
    "inspection": {
      "result": "passed",
      "weight": 850,
      "photos": ["https://..."]
    },
    "createdAt": "2024-01-15T08:30:00Z",
    "updatedAt": "2024-01-18T10:00:00Z"
  }
}

POST/orders/:id/cancelorders:write

Request cancellation of a purchase order. Only available for orders in pending/paid status.

Request

POST /orders/ORD-20240115-002/cancel
Authorization: Bearer sk-xxx
Content-Type: application/json

{ "reason": "Changed my mind" }

Response 200

{
  "data": {
    "orderNo": "ORD-20240115-002",
    "status": "cancelled",
    "refundAmount": 299.00,
    "message": "Order cancelled"
  }
}

Logistics

GET/logistics/countrieslogistics:read

Get list of supported destination countries for international shipping.

Request

GET /logistics/countries
Authorization: Bearer sk-xxx

Response 200

{
  "data": [
    { "code": "US", "name": "United States" },
    { "code": "GB", "name": "United Kingdom" },
    { "code": "JP", "name": "Japan" },
    { "code": "AU", "name": "Australia" }
  ]
}

GET/logistics/shipping-methodslogistics:read

Get available shipping channels filtered by destination and package weight.

Query Parameters

Parameter	Type	Required	Description
country	string	No	Country code (e.g. US, GB)
weight	integer	No	Package weight in grams
cargoType	string	No	Cargo type: general, sensitive, battery, liquid

Request

GET /logistics/shipping-methods?country=US&weight=1500
Authorization: Bearer sk-xxx

Response 200

{
  "data": [
    {
      "channelId": "ch-001",
      "name": "EMS Express",
      "carrier": "EMS",
      "deliveryDays": "7-15",
      "supportedCargo": ["general"],
      "weightRange": { "min": 100, "max": 30000 }
    },
    {
      "channelId": "ch-002",
      "name": "DHL Economy",
      "carrier": "DHL",
      "deliveryDays": "10-20",
      "supportedCargo": ["general", "sensitive"],
      "weightRange": { "min": 100, "max": 50000 }
    }
  ]
}

POST/logistics/calculate-freight-batchlogistics:read

Calculate shipping cost for all available channels at once. Use POST /logistics/calculate-freight for a specific channel.

Request Body

Field	Type	Required	Description
country	string	Yes	Destination country code
weight	integer	Yes	Total weight in grams
length	number	No	Length in cm (for volumetric weight)
width	number	No	Width in cm
height	number	No	Height in cm

Request

POST /logistics/calculate-freight-batch
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "country": "US",
  "weight": 1500,
  "length": 30,
  "width": 20,
  "height": 15
}

Response 200

{
  "data": {
    "channels": [
      {
        "channelId": "ch-001",
        "name": "EMS Express",
        "actualWeight": 1500,
        "volumetricWeight": 1800,
        "chargeWeight": 1800,
        "totalPrice": 185.00,
        "currency": "CNY",
        "deliveryDays": "7-15"
      },
      {
        "channelId": "ch-002",
        "name": "DHL Economy",
        "actualWeight": 1500,
        "volumetricWeight": 1800,
        "chargeWeight": 1800,
        "totalPrice": 210.00,
        "currency": "CNY",
        "deliveryDays": "10-20"
      }
    ]
  }
}

Shipping Orders

POST/shipping/createshipping:write

Create an outbound/shipping order to send warehouse packages to your address internationally.

Request Body

Field	Type	Required	Description
items	array	Yes	Inventory items to ship
items[].inventoryId	integer	Yes	Inventory/package ID
items[].quantity	integer	Yes	Quantity
logisticsChannelId	string	Yes	Selected shipping channel ID
recipientName	string	Yes	Recipient full name
recipientPhone	string	Yes	Recipient phone number
recipientCountry	string	Yes	Country code (e.g. US)
recipientState	string	No	State/province
recipientCity	string	Yes	City
recipientAddress	string	Yes	Street address
recipientZipCode	string	Yes	Postal/ZIP code
remark	string	No	Shipping instructions

Request

POST /shipping/create
Authorization: Bearer sk-xxx
Content-Type: application/json

{
  "items": [
    { "inventoryId": 101, "quantity": 1 },
    { "inventoryId": 102, "quantity": 1 }
  ],
  "logisticsChannelId": "ch-001",
  "recipientName": "John Doe",
  "recipientPhone": "+1-555-0123",
  "recipientCountry": "US",
  "recipientState": "California",
  "recipientCity": "Los Angeles",
  "recipientAddress": "123 Main St",
  "recipientZipCode": "90001"
}

Response 201

{
  "data": {
    "orderNo": "SHP-20240120-001",
    "status": "pending",
    "channelName": "EMS Express",
    "totalWeight": 1650,
    "shippingFee": 185.00,
    "currency": "CNY",
    "items": [
      { "inventoryId": 101, "name": "Nike Air Max 90" },
      { "inventoryId": 102, "name": "Adidas Backpack" }
    ],
    "createdAt": "2024-01-20T09:00:00Z"
  }
}

GET/shipping/ordersshipping:read

Get paginated list of shipping/outbound orders. Also supports GET /shipping/orders/:id for detail, POST /shipping/orders/:id/cancel to cancel, and POST /shipping/orders/:id/confirm-delivery to confirm receipt.

Request

GET /shipping/orders?page=1&limit=10
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "orderNo": "SHP-20240120-001",
        "status": "shipped",
        "channelName": "EMS Express",
        "trackingNo": "EMS1234567890CN",
        "totalWeight": 1650,
        "shippingFee": 185.00,
        "createdAt": "2024-01-20T09:00:00Z"
      }
    ],
    "total": 8,
    "page": 1,
    "limit": 10
  }
}

Warehouse

GET/warehouse/packageswarehouse:read

Get all warehouse packages. Also supports /packages/stats, /packages/shippable, and /packages/:id.

Request

GET /warehouse/packages?page=1&limit=20
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "id": 101,
        "productName": "Nike Air Max 90",
        "weight": 850,
        "status": "in_warehouse",
        "orderId": "ORD-20240115-001",
        "inspectionPhotos": ["https://..."],
        "arrivedAt": "2024-01-18T10:00:00Z",
        "storageDays": 5
      }
    ],
    "total": 3,
    "page": 1,
    "limit": 20
  }
}

User Profile & Wallet

GET/user/profileprofile:read

Get the authenticated user's profile. Also supports PUT /user/profile to update (scope: profile:write).

Request

GET /user/profile
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "id": 1001,
    "username": "john_doe",
    "email": "john@example.com",
    "avatar": "https://...",
    "language": "en",
    "createdAt": "2024-01-01T00:00:00Z"
  }
}

GET/user/wallet/balancewallet:read

Get wallet balance. Also supports GET /user/wallet/transactions for transaction history.

Request

GET /user/wallet/balance
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "balance": 2000.00,
    "frozenBalance": 598.00,
    "availableBalance": 1402.00,
    "currency": "CNY"
  }
}

GET/user/addressesprofile:read

Get saved addresses. Also supports POST /user/addresses (create), PUT /user/addresses/:id (update), DELETE /user/addresses/:id (delete) with scope profile:write.

Request

GET /user/addresses
Authorization: Bearer sk-xxx

Response 200

{
  "data": [
    {
      "id": 10,
      "name": "John Doe",
      "phone": "+1-555-0123",
      "country": "US",
      "state": "California",
      "city": "Los Angeles",
      "address": "123 Main St",
      "zipCode": "90001",
      "isDefault": true
    }
  ]
}

GET/user/favoritesfavorites:read

Get favorite products. Also supports POST /user/favorites (add, scope: favorites:write) and DELETE /user/favorites/:id (remove, scope: favorites:write).

Request

GET /user/favorites
Authorization: Bearer sk-xxx

Response 200

{
  "data": {
    "items": [
      {
        "id": 5,
        "productId": 12345,
        "title": "Nike Air Max 90",
        "price": 299.00,
        "imageUrl": "https://...",
        "addedAt": "2024-01-10T12:00:00Z"
      }
    ],
    "total": 1
  }
}

GET/user/coupons/availablecoupons:read

Get coupons available to claim. Also supports GET /user/coupons/my for claimed coupons.

Request

GET /user/coupons/available
Authorization: Bearer sk-xxx

Response 200

{
  "data": [
    {
      "id": 50,
      "name": "New User Discount",
      "type": "percentage",
      "value": 10,
      "minOrderAmount": 200.00,
      "expiresAt": "2024-03-01T00:00:00Z"
    }
  ]
}

Error Responses

All error responses follow a consistent format:

{
  "statusCode": 403,
  "message": "Insufficient scope. Required: orders:write. Your key has: products:read, cart:read",
  "error": "Forbidden"
}

401 Unauthorized

{
  "statusCode": 401,
  "message": "Invalid API Key",
  "error": "Unauthorized"
}

429 Rate Limited

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Try again in 45s",
  "error": "Too Many Requests"
}