Skip to content
Build 8b0b16e

Cirro B2B API — Proposed Field Adjustments (v2 — 2026-06-01)

Cirro sent an updated B2B API Adjustment doc on 2026-06-01, superseding the 2026-05-26 version. Nothing here is wired yet. This page captures what they're asking us to send and what they intend to send us, so we can sequence the work when we're ready. Prior version preserved in git history.

Out of scope today

We are not generating or pushing 856/945 EDI to Amazon yet. CI-397 is scoped to mark-as-shipped on edi_docs only — no downstream EDI output.

Changes from v1 (2026-05-26 → 2026-06-01)

Outbound:

  • carton_list[] — new top-level array (sibling of label_template) for label attachments and label-application metadata
  • packing_slip_label — restructured: now has dc, dept, shipment_id (plus name/company_name in their JSON sample, not in their field table). v1 had dc + phone.

Inbound (SendOrder):

  • Order_type — now documented as enum: 0=B2C, 10=FBA, 20=disposal, 30=self-pickup, 50=VC, 60=WFS, 70=B2B
  • dispatch_info[] — new array replacing the v1 flat top-level fields. Contains pro_number, arn, load_id, Carrier, carrier_scac, bol. v1 had these as separate top-level keys on message.
  • customer_po_code and product_carrier (v1 top-level) appear dropped — Carrier now lives inside dispatch_info[]; PO mapping needs clarification.
  • order_box_info[] — gains sscc_code

1. Outbound — v1/order/create-b2b

We already POST request_data to Cirro. They're proposing two new top-level keys inside it — and the same shape applies to v1/order/update-b2b.

At a glance — po_number, the label_template object, and the new carton_list[] all live inside the request_data we already send:

request_data
├── po_number
├── label_template
│   ├── ucc_label          { dept, dc, store, type, items[]{ upc, product_sku, platform_sku, style, color, size } }
│   ├── pallet_label       { dept, dc, store, type, items[]{ upc, product_sku, … } }
│   ├── packing_slip_label { dc, dept, name, company_name, shipment_id, items[]{ upc, product_sku, gtin14 } }
│   └── gtin14_label       { items[]{ product_sku, color, size_style, gtin14 } }   // Walmart only
└── carton_list[].label_list[] { file_id, label_type (1=UCC, 2=Gtin14), box_mark_num (1/2/4), label_source (always 2) }

1.1 po_number

Field Type Required Notes
po_number string optional Purchase Order Number — we already have this in edi_docs from the 940.

1.2 label_template (object)

Wrapper for four sub-templates Cirro will print on our behalf. Each sub-template is itself optional.

Not yet final

Cirro's source doc flags label_template as "still being double-confirmed internally." Treat the shape below as proposed, not locked — confirm before we build to it.

1.2.1 ucc_label

UCC-128 carton labels.

Field Type Notes
dept string Department number
dc string DC#
store string STORE#
type string TYPE
items[] object[] per-SKU detail (see below)

items[] shape: upc, product_sku (Customer SKU), style, color, size, platform_sku.

1.2.2 pallet_label

Same shape as ucc_label (dept / dc / store / type / items[]).

1.2.3 packing_slip_label

Field Type Notes
dc string DC#
dept string Department number
shipment_id string Shipment ID
items[] object[] upc, product_sku, gtin14

Sample-vs-table discrepancy

The v2 source-doc JSON sample also shows name and company_name on packing_slip_label, but their field-definition table only lists dc/dept/shipment_id/items[]. Confirm with Cirro whether name/company_name are required, optional, or sample-only filler.

1.2.4 gtin14_label (Walmart only)

Flagged in source as "Walmart Gtin Label".

items[] shape: product_sku, color, size_style, gtin14.

1.3 carton_list[] (new in v2)

Top-level array, sibling of label_template. Each entry has a label_list[] describing labels Cirro should apply per carton.

label_list[] fields:

Field Type Notes
file_id string ID from Cirro Attachment API. Required only if we upload our own UCC or Gtin14 label artwork.
label_type int 1 = UCC label, 2 = Gtin14 label
box_mark_num int Total labels to apply on the order. Values: 1, 2, or 4.
label_source int 1 = manual upload, 2 = system-generated. Cirro instructs PopSockets to always send 2.

1.4 platform_sku mapping

Platform platform_sku source
Walmart WMIT
Best Buy platform sku
Target Target SKU

1.5 Sample outbound payload (from Cirro v2 doc)

The new keys live inside request_data alongside everything we already send:

{
  "po_number": "PO-2024-06201",
  "label_template": {
    "ucc_label": {
      "dept": "DEPT-01",
      "dc": "DC-001",
      "store": "STORE-01",
      "type": "STANDARD",
      "items": [
        {
          "upc": "012345678905",
          "product_sku": "SKU-001",
          "style": "Classic",
          "color": "Red",
          "size": "M",
          "platform_sku": "WM-SKU-001"
        }
      ]
    },
    "pallet_label": {
      "dept": "DEPT-01",
      "dc": "DC-001",
      "store": "STORE-01",
      "type": "STANDARD",
      "items": [
        {
          "upc": "012345678905",
          "product_sku": "SKU-001"
        }
      ]
    },
    "packing_slip_label": {
      "dc": "DC-001",
      "name": "Packing Slip Q1",
      "company_name": "Example Corp",
      "dept": "DEPT-01",
      "items": [
        {
          "upc": "012345678905",
          "product_sku": "SKU-001",
          "gtin14": "10012345678905"
        }
      ]
    },
    "gtin14_label": {
      "items": [
        {
          "product_sku": "SKU-001",
          "color": "Red",
          "size_style": "M/Classic",
          "gtin14": "10012345678905"
        }
      ]
    }
  },
  "carton_list": [
    {
      "label_list": [
        {
          "file_id": 12345,
          "label_type": 1,
          "box_mark_num": 2,
          "label_source": 1
        }
      ]
    }
  ]
}

2. Inbound — SendOrder ship event

Cirro already sends us SendOrder events. They're proposing additions inside message, a new dispatch_info[] array, and an enriched order_box_info[].

2.1 New / changed top-level fields on message

Field Notes
Order_type Order type. Enum (per v2 doc): 0 = standard B2C, 10 = FBA, 20 = disposal, 30 = self-pickup, 50 = VC, 60 = WFS, 70 = standard B2B. Note capital O in source.
dispatch_info[] New array. See 2.2.

2.2 dispatch_info[] (new in v2)

Array of dispatches per shipment. v1 had these as flat top-level fields on message; v2 wraps them in an array — implying potentially multiple dispatches per order.

Field Notes
pro_number Pro Number
arn ARN / ASN
load_id Load ID
Carrier Carrier name. Note capital C in source.
carrier_scac SCAC code
bol BOL Number

2.3 Enriched order_box_info[]

Field Example
box_no "1"
box_mark "prepack order number"
fn_box_no "reference box number"
sscc_code SSCC barcode (new in v2)
ob_qty 1
ob_length "50.00"
ob_width "40.00"
ob_height "30.00"
ob_weight "30.00"
tracking_number "MO201017498MO"
product_barcode "EL122-F5846293533"

2.4 Sample payload (from Cirro v2 doc)

{
  "app_token": "abc123",
  "sign": "md5string",
  "message_type": "StockChangeRecord",
  "message_id": "6daf1a43-283b-42a2",
  "send_time": 1727712000,
  "message": {
    "Order_type": "70",
    "dispatch_info": [
      {
        "pro_number": "Pro Number",
        "arn": "",
        "load_id": "",
        "Carrier": "carrier name",
        "carrier_scac": "",
        "bol": ""
      }
    ],
    "order_code": "EL1038-250529-0037",
    "reference_no": "112-8525766-8344247",
    "order_status": 0,
    "tracking_number": "1234567890",
    "sm_code": "",
    "add_time": "2000-01-02T13:48:19-05:00",
    "sc_id": "21",
    "warehouse_id": "1",
    "outStock_time": "2000-01-02T13:48:19-05:00",
    "so_weight": "1166.667",
    "order_weight": "1166.667",
    "so_shipping_fee": "2571.870",
    "property_label": "",
    "item": [{
      "product_barcode": "G1038-H3166419678",
      "product_sku": "GR580010",
      "qty": 1,
      "fba_product_code": "",
      "transaction_id": ""
    }],
    "fee_details": {
      "totalFee": "5618.340",
      "SHIPPING": "2571.870",
      "OPF": "8.100",
      "FSC": "8.100",
      "DT": "3038.370",
      "RSF": "3038.370",
      "OTF": "3038.370",
      "currency_code": "USD"
    },
    "order_box_info": [{
      "box_no": "1",
      "box_mark": "prepack order number",
      "fn_box_no": "reference box number",
      "sscc_code": "SSCC",
      "ob_qty": 1,
      "ob_length": "50.00",
      "ob_width": "40.00",
      "ob_height": "30.00",
      "ob_weight": "30.00",
      "tracking_number": "MO201017498MO",
      "product_barcode": "EL122-F5846293533"
    }]
  }
}

3. PopSockets-side open questions

  • Outbound label fields (dept / dc / store / type / style / color / size) — are these already on the parsed 940, or do we need a customer/SKU master lookup?
  • platform_sku — confirm where WMIT / Best Buy / Target values live (OMS product master? Arena? per-customer mapping table?)
  • carton_list[].label_list[].file_id (v2) — label_source: 2 (system-generated) is what Cirro tells us to send, so when do we ever populate file_id? Confirm the Attachment-API upload path is optional.
  • packing_slip_label.name / company_name (v2) — appear in JSON sample but not the field-definition table. Required or optional?
  • dispatch_info[] as array (v2) — confirm semantic. Multiple dispatches per order (split shipments)? Or always single-entry?
  • PO mapping inbound (v2) — v1 had customer_po_code top-level; v2 sample doesn't include it. Where does PO number land on inbound now?
  • Inbound persistence — do we want to land dispatch_info[] fields (carrier_scac / bol / arn / load_id) on fulfillment_tracking now (even before 856 push) so the data is ready when we are?
  • Inbound order_box_info dims/weight/tracking/sscc_code — same question: persist now for future 856, or wait?
  • fee_details sub-codes (OPF, FSC, DT, RSF, OTF) — source doc lists them without definitions. Ask Cirro what each represents.
  • Source-doc wording quirks to clarify with Cirro:
    • Order_type capital O and Carrier capital C in dispatch_info — typos in source doc, or are they sending mixed-case keys?
    • pallet_label.items.product_sku is labeled "Popsockets SKU" while the same field on ucc_label is "Customer SKU" — likely a typo, confirm.
    • gtin14_label.items.size_style is described as "Customer SKU" in their column — confusing given the field name. Confirm intent.
    • They call label_template a "Waybill Template" (面单模板) — confirm that's the intended naming for our docs/code.