Shippo API中reference字段未显示在USPS面单上的问题咨询

我之前对接Shippo API生成USPS面单时，也踩过一模一样的坑——extra.reference_1和extra.reference_2确实不会显示在USPS实体面单上。这俩字段的定位其实是Shippo内部的跟踪参考字段，只会在Shippo后台管理界面或API返回的运单详情里可见，并不会映射到USPS的面单打印模板中。

如果你需要把订单号、RMA编号这类信息显示在USPS面单上，应该用以下两个字段：

1. 主参考字段：shipment.reference #

这个是Shippo为所有承运商通用的面单参考字段，USPS会把它打印在面单的「Reference」区域，非常适合填订单号。示例参数：

{
  "shipment": {
    "reference": "Order #20240501-001",
    // 其他必填字段（寄件人、收件人、包裹信息等）...
    "extra": {
      // 这里的reference_1/2可以继续存内部跟踪信息，比如RMA的后台编号
      "reference_1": "Internal RMA #999"
    }
  }
}

2. USPS专属额外文本：extra.usps_label_message #

如果需要添加第二个自定义文本（比如RMA编号），可以用这个USPS专属字段，它会显示在面单的额外备注区域。示例参数：

{
  "shipment": {
    "reference": "Order #20240501-001",
    // 其他必填字段...
    "extra": {
      "usps_label_message": "RMA #888"
    }
  }
}

额外提醒 #

• 不同承运商对参考字段的支持逻辑不同，USPS只认上述两个字段作为面单显示的自定义文本；
• 如果你的面单是自定义模板，需要确认模板是否预留了这些字段的显示位置；
• extra.reference_1/2依然有用，可以用来存储不需要打印但需要内部跟踪的信息，比如内部系统订单ID、客服备注等。

内容的提问来源于stack exchange，提问作者sineo