Skip to content

Importing grouped tracking

order_tracking_groups is an opt-in way to process a complete supplier-order tracking response. It matches the supplier's parts to saved product values on order items and builds shipment updates for those items. The response must cover all supplier orders needed to determine the shipped quantities; this mode cannot infer complete totals from an incremental response.

Use an order import with identifier: "oid", order_item_identifier: "itemid", update: true, payload_multi: false, a nonempty order_update_search, and field_map: {"oid": "oid"}. This mode does not support create or remove, vendor or SureDone actions, value mappings, field formatting or calculations, another parser, split_tracking_by_comma, or line-item payload mode.

The mapping names groups as a JSONPath and specifies member names for oid, group_id, tracking, carrier, items, part, and quantity. product_field identifies the saved product field containing the supplier's part number. Each group identifies one supplier order and the SureDone order. Parts must match one eligible order line; ambiguous or unmatched parts, conflicting duplicates, nonpositive quantities, and quantities above the ordered amount cause the affected order to be rejected for that run. Groups without tracking do not contribute shipped quantities.

For example, this file-configuration excerpt describes a response containing a list of packages per supplier order. The field names are illustrative; replace them with the names in your supplier's response and use a search that identifies the intended order items:

{
  "identifier": "oid",
  "order_item_identifier": "itemid",
  "update": true,
  "payload_multi": false,
  "search": "vendor:=example",
  "order_update_search": "vendor:=example",
  "field_map": {"oid": "oid"},
  "order_tracking_groups": {
    "groups": "$.*",
    "oid": "orderId",
    "group_id": "supplierOrderId",
    "packages": "packages",
    "tracking": "trackingNumber",
    "carrier": "carrier",
    "items": "items",
    "part": "partNumber",
    "quantity": "quantity",
    "product_field": "suppliersku"
  }
}

The file-level search selects the orders to request; order_update_search restricts which order items are eligible for updates. Set both to the scope appropriate for the integration. The full automation also needs its connection and other required settings. Validate the configuration and compare the mapping to an actual supplier response before using it.

Package quantities

If the supplier provides actual package contents, packages names the nested list containing package tracking and item quantities. Configure the other mapping names to match the supplier's response. Repeated identical package data does not create another shipment, while conflicting package data is rejected. Existing verified package IDs and dates are retained. This mode does not infer corrections for changed tracking numbers or adopt unknown historical shipments.

For a response without actual package contents, split_quantity_across_tracking: true distributes remaining group units among new tracking numbers. These assignments are estimates, not physical package contents; extra tracking numbers can have no assigned items. Do not combine this option with packages. Without it, each new tracking number receives the group's full item quantities.

Quantity and status depend on all relevant items. A partially shipped line remains incomplete; unrelated incomplete items can keep an order partially shipped. Existing completed and manually managed states are not automatically rewritten. Avoid running competing imports for the same orders at the same time.

Checking results

Test with representative orders, including multiple items, multiple packages, partial shipments, and repeated responses. Check saved quantities, tracking numbers, and statuses, then verify acceptance in the destination channel. A saved shipment or a successful request does not prove that the channel accepted it. If the source changes a previously recorded tracking number or an order has conflicting historical shipment data, review and correct it through the appropriate order workflow rather than assuming a replay will repair it.

split_tracking_by_comma is a separate option for ordinary order imports: it splits a comma-separated tracking value into individual shipment records. It is not a substitute for package-level quantities.