1. 接口
Help for ShipSage
  • 中文版 V2.0
    • 接口集成
      • OMS API
        • 入门指南
        • 接口
          • 店铺
          • 仓库
          • 产品
          • 库存
          • 订单
          • 包裹
          • 物流跟踪
          • 发货计划
          • 转运
          • 增值服务
          • 退货
          • 文件上传
  • English V2.0
    • API Integration
      • OMS API
        • Getting Started
        • APIs
          • Account
          • Warehouse
          • Product
          • Inventory
          • Order
          • Shipping
          • Tracking
          • ASN
          • Transfer
          • VAS
          • Return
          • File Upload
  1. 接口

库存

端点#

方法端点描述
GET/api/v202206/inventory/products获取产品库存列表
GET/api/v202608/lot-inventories获取实时批次库存
GET/api/v202608/inventory-snapshots获取 SKU 级库存快照（指定日期）
GET/api/v202608/lot-inventory-snapshots获取 Lot 级库存快照（指定日期）
[新增] v202608 补丁（2026-09 新增）：
现有 GET /api/v202206/inventory/products 参数中新增 condition（该改动已合并到下方参数表）
新增 GET /api/v202608/lot-inventories：批次库存实时查询
新增 GET /api/v202608/inventory-snapshots：SKU 级历史快照
新增 GET /api/v202608/lot-inventory-snapshots：Lot 级历史快照
3 个新增接口均为只读，用于查询实时批次库存 + 历史对账重放。

头部#

键值
AuthorizationBearer eyJ0eXAiOiJKV1QiLCJhbGciOi ...

GET /api/v202206/inventory/products#

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
index.by-default		必填enum
querycustomer_sku客户的 sku 编码选填string
querywarehouse_id仓库 id选填integer
querycondition库存状态

可用值:
New, Open Box, Used, Customized, Parts, Damaged		选填enum
querynext_token下一页数据的秘钥选填string

返回#

KeyValue
errcode0/4000
errmsgok/Error Info
dataData Properties
Data Properties#
名称描述数据结构
product_id产品 idinteger
skusku 编码integer
customer_sku客户的 sku 编码string
bundled是否为套件产品（由多个子产品组装而成的产品），如果值为 1，则需要“qty_bundle_available”

可用值:
0: 否, 1: 是		enum
warehouse_id仓库 idinteger
warehouse_name仓库名称string
condition库存状态，例如全新、二手、损坏等。
同一 SKU 可能在同一个仓库中对应多个库存状态。当多个库存状态有库存时，它们会分别显示在不同的行中。

可用值:
New, Open Box,Used,Customized,Parts,Damaged		enum
qty_allocated被占用的库存数量integer
qty_hold等待上架的库存数量integer
qty_bundle_available套件产品的可用库存数量，是否有值取决于 bundled 的值是否为 1integer
qty_on_hand库存总数integer
qty_available可用库存数量integer
qty_receibing_area收货区的库存数量 （此字段已弃用）integer
qty_frozen被冻结的库存数量integer
qty_conditioned非全新库存总数量（此字段已弃用）integer
qty_in_transit在途库存数量integer
返回示例#
 [
     {
         "warehouse_id": 101,
         "warehouse_name": "SG-SMF1",
         "product_id": 136251,
         "sku": 230924,
         "customer_sku": "0905",
         "bundled": 0,
         "condition": "New",
         "qty_on_hand": 23,
         "qty_hold": 5,
         "qty_frozen": 0,
         "qty_allocated": 0,
         "qty_receiving_area": 0,
         "qty_in_transit": 0,
         "qty_available": 18,
         "qty_bundle_available": 0,
         "qty_conditioned": 0
     },
     {
         "warehouse_id": 101,
         "warehouse_name": "SG-SMF1",
         "product_id": 136251,
         "sku": 230924,
         "customer_sku": "0905",
         "bundled": 0,
         "condition": "Open Box",
         "qty_on_hand": 1,
         "qty_hold": 0,
         "qty_frozen": 0,
         "qty_allocated": 0,
         "qty_receiving_area": 0,
         "qty_in_transit": 0,
         "qty_available": 1,
         "qty_bundle_available": 0,
         "qty_conditioned": 0
     }
 ]
以下 3 个 v202608 端点均为只读。用于查询实时批次库存 + 历史对账重放。

GET /api/v202608/lot-inventories （获取实时批次库存）#

按批次维度返回当前库存状态。

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
index.by-default		必填enum
querywarehouse_id仓库 id选填integer
querycustomer_sku客户 sku 编码（精确匹配）选填string
querysku系统 sku 编码（精确匹配）选填integer
querylot_idShipSage 内部批次号选填integer
querycondition库存状态
可用值:
New, Open Box, Used, Customized, Parts, Damaged, Disposal, Stored, Unclaimed		选填enum
querylot_rule产品级 Lot 规则
可用值:
fifo（按入库日期先出，库位物理隔离）,
fefo（按过期日期先出，库位物理隔离）,
none（SKU 未启用 lot 管理）		选填string
queryreceive_date_from入库日期 起选填date
queryreceive_date_to入库日期 止选填date
queryexpiration_date_from过期日期 起选填date
queryexpiration_date_to过期日期 止选填date
queryaged_days_minAged 天数最小值选填integer
queryaged_days_maxAged 天数最大值选填integer
queryupdated_at_from更新时间 起（用于增量拉取）
时区：太平洋标准时间		选填datetime
queryupdated_at_to更新时间 止
时区：太平洋标准时间		选填datetime
queryhas_available_qty是否只返回可用数 > 0 的行（默认 1）
可用值:
0：全部, 1：只返回可用		选填enum
querysort_by排序字段（默认 receive_date）
可用值:
receive_date, expiration_date, aged_days		选填enum
querysort_order排序方向（默认 asc）
可用值:
asc, desc		选填enum
querynext_token下一页数据的秘钥选填string
请求示例#
GET /api/v202608/lot-inventories?api=index.by-default&warehouse_id=100&customer_sku=CUS-SKU-001&condition=New&lot_rule=fefo&expiration_date_from=2027-01-01&has_available_qty=1&sort_by=expiration_date&sort_order=asc

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
lot_idShipSage 内部批次号integer
warehouse_id仓库 idinteger
warehouse_name仓库名string
condition库存状态，可用值：New / Open Box / Used / Customized / Parts / Damaged / Disposal / Stored / Unclaimedstring
sku系统 sku 编码integer
customer_sku客户 sku 编码string
bundled是否为套件产品
可用值:
0：否, 1：是		integer
lot_rule产品级 Lot 规则（fifo / fefo / null）string
receive_date入库日期date
expiration_date过期日期date
aged_dateAged 起始日date
aged_daysAged 天数（从 aged_date 到今日）integer
qty_on_hand库存总数integer
qty_allocated被占用的库存数量integer
qty_hold等待上架的库存数量integer
qty_frozen被冻结的库存数量integer
qty_available可用库存数量integer
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "lot_id": 5511,
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "condition": "New",
                "sku": 3001,
                "customer_sku": "CUS-SKU-001",
                "bundled": 0,
                "lot_rule": "fefo",
                "receive_date": "2026-06-15",
                "expiration_date": "2027-06-15",
                "aged_date": "2026-06-15",
                "aged_days": 60,
                "qty_on_hand": 500,
                "qty_allocated": 120,
                "qty_hold": 0,
                "qty_frozen": 0,
                "qty_available": 380
            }
        ],
        "next_token": null
    }
}

GET /api/v202608/inventory-snapshots （获取 SKU 级库存快照）#

按指定日期返回 SKU 级库存快照。字段与实时库存查询接口 GET /api/v202206/inventory/products 保持一致（除快照专属字段外）。
snapshot_date 必填。历史快照仅在快照数据实际存在的日期返回结果；无数据时返回空数组。

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
index.by-default		必填enum
querysnapshot_date快照日期（YYYY-MM-DD 格式）必填date
querywarehouse_id仓库 id选填integer
querycustomer_sku客户 sku 编码（精确匹配）选填string
querycondition库存状态
可用值:
New, Open Box, Used, Customized, Parts, Damaged, Disposal, Stored, Unclaimed		选填enum
queryhas_available_qty是否只返回可用数 > 0 的行（默认 1）
可用值:
0：全部, 1：只返回可用		选填enum
querynext_token下一页数据的秘钥选填string
请求示例#
GET /api/v202608/inventory-snapshots?api=index.by-default&snapshot_date=2026-08-11&warehouse_id=100&customer_sku=CUS-SKU-001&condition=New&has_available_qty=1

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
snapshot_date快照对应的业务日期。表示这份数据代表哪一天结束时的库存状态。例如 2026-08-11 表示 2026 年 8 月 11 日结束时的库存date
snapshot_at快照数据实际生成的时间点。系统每天在午夜前后（snapshot_date 当日 23:50 至次日 00:10 之间）自动运行快照任务，将当天结束时的库存"定格"下来。所以 snapshot_date = 2026-08-11 时，snapshot_at 通常在 2026-08-11 23:50 到 2026-08-12 00:10 之间
时区：太平洋标准时间		datetime
warehouse_id仓库 idinteger
warehouse_name仓库名string
condition库存状态，可用值：New / Open Box / Used / Customized / Parts / Damaged / Disposal / Stored / Unclaimedstring
sku系统 sku 编码integer
customer_sku客户 sku 编码string
bundled是否为套件产品
可用值:
0：否, 1：是		integer
qty_on_hand库存总数integer
qty_hold等待上架的库存数量integer
qty_frozen被冻结的库存数量integer
qty_allocated被占用的库存数量integer
qty_in_transit在途库存数量integer
qty_available可用库存数量integer
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "snapshot_date": "2026-08-11",
                "snapshot_at": "2026-08-12 00:00:00",
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "condition": "New",
                "sku": 3001,
                "customer_sku": "CUS-SKU-001",
                "bundled": 0,
                "qty_on_hand": 500,
                "qty_hold": 5,
                "qty_frozen": 0,
                "qty_allocated": 120,
                "qty_in_transit": 200,
                "qty_available": 380
            }
        ],
        "next_token": null
    }
}

GET /api/v202608/lot-inventory-snapshots （获取 Lot 级库存快照）#

按指定日期返回批次级库存快照。snapshot_date 必填。

请求#

参数#
类型名称描述必填/选填数据结构
queryapiAPI 类型

可用值:
index.by-default		必填enum
querysnapshot_date快照日期（YYYY-MM-DD 格式）必填date
querywarehouse_id仓库 id选填integer
querycustomer_sku客户 sku 编码选填string
querysku系统 sku 编码选填integer
querylot_idShipSage 内部批次号选填integer
querycondition库存状态
可用值:
New, Open Box, Used, Customized, Parts, Damaged, Disposal, Stored, Unclaimed		选填enum
querylot_rule产品级 Lot 规则
可用值:
fifo, fefo, none		选填enum
queryreceive_date_from入库日期 起选填date
queryreceive_date_to入库日期 止选填date
queryexpiration_date_from过期日期 起选填date
queryexpiration_date_to过期日期 止选填date
queryhas_available_qty是否只返回可用数 > 0 的行（默认 1）
可用值:
0：全部, 1：只返回可用		选填enum
querysort_by排序字段（默认 receive_date）
可用值:
receive_date, expiration_date		选填enum
querysort_order排序方向（默认 asc）选填enum
querynext_token下一页数据的秘钥选填string
请求示例#
GET /api/v202608/lot-inventory-snapshots?api=index.by-default&snapshot_date=2026-08-11&warehouse_id=100&customer_sku=CUS-SKU-001&condition=New&lot_rule=fefo&has_available_qty=1&sort_by=expiration_date

返回#

键值
errcode0/4000
errmsgok/Error Info
dataData Properties
Data properties#
名称描述数据结构
snapshot_date快照对应的业务日期。表示这份数据代表哪一天结束时的库存状态。例如 2026-08-11 表示 2026 年 8 月 11 日结束时的库存date
snapshot_at该批次在快照业务日内最晚一条动作的时间戳（对应仓库历史动作表 action_date 在快照日内的 MAX 值），代表这份批次快照所定格的时刻；snapshot_date 为该值的日期部分
时区：太平洋标准时间		datetime
lot_idShipSage 内部批次号integer
warehouse_id仓库 idinteger
warehouse_name仓库名string
condition库存状态，可用值：New / Open Box / Used / Customized / Parts / Damaged / Disposal / Stored / Unclaimedstring
sku系统 sku 编码integer
customer_sku客户 sku 编码string
bundled是否为套件产品（0/1）integer
lot_rule产品级 Lot 规则（fifo / fefo / null）string
receive_date入库日期date
expiration_date过期日期date
aged_dateAged 起始日date
aged_daysAged 天数（从 aged_date 到快照日期）integer
qty_on_hand库存总数integer
qty_allocated被占用的库存数量integer
qty_hold等待上架的库存数量integer
qty_frozen被冻结的库存数量integer
qty_available可用库存数量integer
返回示例#
{
    "errcode": 0,
    "errmsg": "ok",
    "data": {
        "items": [
            {
                "snapshot_date": "2026-08-11",
                "snapshot_at": "2026-08-12 00:00:00",
                "lot_id": 5511,
                "warehouse_id": 100,
                "warehouse_name": "SG-MDW1",
                "condition": "New",
                "sku": 3001,
                "customer_sku": "CUS-SKU-001",
                "bundled": 0,
                "lot_rule": "fefo",
                "receive_date": "2026-06-15",
                "expiration_date": "2027-06-15",
                "aged_date": "2026-06-15",
                "aged_days": 57,
                "qty_on_hand": 500,
                "qty_allocated": 120,
                "qty_hold": 0,
                "qty_frozen": 0,
                "qty_available": 380
            }
        ],
        "next_token": null
    }
}
Modified at 2026-09-23 07:23:35
Previous
产品
Next
订单
Built with