Skip to main content

Get Shared Shipping Events

Method: GET
/internal/events/shipping/shared

Retrieve shipping events that have been shared with a customer account via network location sharing. Success returns 200 OK with a paged list of shared shipping events. Default page size is 20. Default sort is eventDate descending, then id descending.

info

This endpoint is being refined and thus subject to change. The query parameters below describe the filters currently applied by shared shipping search. These docs will update when changes are made.

What “shared” means​

An event is returned when:

  • It is a shipping event
  • Its primary ship-to location is shared with the requested accountId
  • The event is not owned by that account (the owner’s own shipments are excluded)

If the ship-to is not in-network / not shared with the account, the event does not appear.

Authentication​

This is an internal service API. Callers must present a valid internal API key. Contact your iFoodDS representative for key provisioning.

Internal-Api-Keys: <your-api-key>

Request​

Type: application/json

Retrieving shared ship events via the API is done through paging. Supply query parameters in the request URL to select a page and filter the events returned. Multiple filters are AND-ed. Within a multi-value filter, values are OR-ed.

Query Parameters​

The event type is implied as shipping; no type parameter is needed.

Required​

  • accountId (integer): Account that received the share. Required. Missing → 400 Bad Request.

Pagination​

  • page (integer): Zero-based page index. Default value is 0.
  • size (integer): Page size. Default value is 20.
  • sort (string): Spring Pageable sort expression. Default sort is eventDate,desc then id,desc.

Date Ranges​

Format: yyyy-MM-ddTHH:mm:ss (e.g. 2024-06-14T00:00:00).

  • eventStartDateTime / eventEndDateTime (datetime): Filter by shipment/event date.
  • submitStartDateTime / submitEndDateTime (datetime): Filter by submit/transaction time.
  • sharedStartDateTime / sharedEndDateTime (datetime): Filter by when the event was shared.
  • shipmentStartDate / shipmentEndDate (datetime): Legacy shipment date range filters.

Canonical Filters (exact match)​

Values are trimmed and compared case-insensitively as exact matches. Pass as comma-separated values or repeated query parameters.

  • purchaseOrderNumber (string): Purchase order number(s).
  • referenceDocumentNumber (string): Reference / PO document number(s).
  • caseLotNumber (string): Case lot / TLC number(s).
  • caseGtin (string): Case GTIN(s).
  • vendorItemCode (string): Vendor item code(s).
  • shipFromLocationCode (string): Ship-from location code(s).
  • shipToCompanyName (string): Ship-to company name(s).
  • countryOfOrigin (string): Country of origin value(s).
  • tlcSourceReferenceGln (string): TLC source reference GLN(s).

Example: caseLotNumber=LOT123 matches LOT123 but not LOT.
purchaseOrderNumber=PO-1,PO-2 matches either PO.

Legacy Trace App Filters (contains / partial match)​

These remain for compatibility with Trace App-style queries. Prefer canonical filters for integrations.

  • poNumber (string): Contains match on purchase order number (e.g. 9876 matches PO-9876).
  • billOfLading (string): Contains match on bill of lading.
  • lotCode (string): Contains match on lot code (e.g. LOT matches LOT123).
  • sscc (string): Contains match on SSCC.
  • lpn (string): Contains match on LPN.
  • productDescription (string): Contains match on product description.
  • shipTo (string): Contains match on ship-to location name.
  • shipFrom (string): Contains match on ship-from location name.
  • statusLogShareStatus (string): Exact status filter.
  • autoReceived (boolean): true = already auto-received; false = not; omit = either.

Matching Behavior​

  • Returns only shipping events whose primary ship-to location is shared with the given accountId.
  • Excludes events owned by that account.
  • Multiple filters are AND-ed. Within a multi-value filter, values are OR-ed.
  • Canonical filters use exact match after trim and lowercase. Pass multiple values as a comma-separated list or by repeating the query parameter.
  • Legacy Trace App filters mostly use contains/partial matching. Prefer canonical filters for deterministic integrations.
  • Event date bounds apply to shipment/event date. Submit bounds apply to submit/transaction time. Shared bounds apply to when the event was shared.
  • shipFromId, shipToId, and productId are stored master IDs only. There is no fallback from GLN or location/product codes. Older events ingested before those IDs were persisted may return null.

Data Constraints​

  • strings allow a maximum of 100 characters.
  • datetimes use the format yyyy-MM-ddTHH:mm:ss.

Request Examples​

Minimal request​

Shared shipments for an account
/internal/events/shipping/shared?accountId=222&page=0&size=20
Internal-Api-Keys: <your-api-key>

Filtered request​

Filter by PO, lot, and event date range
/internal/events/shipping/shared?accountId=222&purchaseOrderNumber=PO-9876&caseLotNumber=LOT123&eventStartDateTime=2024-06-14T00:00:00&eventEndDateTime=2024-06-16T23:59:59
Internal-Api-Keys: <your-api-key>

Find events by shared date range​

Shared date range
/internal/events/shipping/shared?accountId=222&sharedStartDateTime=2024-06-14T00:00:00&sharedEndDateTime=2024-06-16T23:59:59

Find shared shipments from a supplier location​

Match a ship-from location code
/internal/events/shipping/shared?accountId=222&shipFromLocationCode=FROM-DC

Find shared shipments tied to one or more purchase orders​

Multi-value filters accept a comma-separated list or repeated parameters.

Match purchase order numbers
/internal/events/shipping/shared?accountId=222&purchaseOrderNumber=PO-1,PO-2
Match purchase order numbers (repeated params)
/internal/events/shipping/shared?accountId=222&purchaseOrderNumber=PO-1&purchaseOrderNumber=PO-2

Find shared shipments by case GTIN and lot​

Match case GTIN and lot
/internal/events/shipping/shared?accountId=222&caseGtin=00012345678905&caseLotNumber=LOT123

Response​

Return result for the shared shipping event data queried.

{
    "content": [
        {
            "id": "11111111-1111-1111-1111-111111111111",
            "eventId": "SHIP-001",
            "eventDateTime": "2024-06-15T12:00:00Z",
            "eventTransactionTime": "2024-06-15T12:05:00Z",
            "purchaseOrderDate": "2024-06-01",
            "purchaseOrderNumber": "PO-9876",
            "billOfLadingNumber": "<bol number>",
            "asnNumber": "ASN-100",
            "expectedDeliveryDate": "2024-06-16",
            "businessUnit": "<business unit>",
            "shipFromId": "aaaaaaaa-aaaa-aaaa-aaaa-aaaaaaaaaaaa",
            "shipFromLocationCode": "FROM-DC",
            "shipFromLocationName": "Supplier DC",
            "shipFromLocationPhoneNumber": "<ship from phone>",
            "shipFromLocationAddress1": "<ship from address 1>",
            "shipFromLocationAddress2": "<ship from address 2>",
            "shipFromLocationCity": "<ship from city>",
            "shipFromLocationState": "<ship from state>",
            "shipFromLocationPostalCode": "<ship from postal code>",
            "shipFromLocationCountry": "<ship from country>",
            "shipToId": "bbbbbbbb-bbbb-bbbb-bbbb-bbbbbbbbbbbb",
            "shipToLocationCode": "TO-DC",
            "shipToCompanyName": "Customer DC",
            "shipToLocationName": "<ship to location name>",
            "shipToLocationPhoneNumber": "<ship to phone>",
            "shipToLocationAddress1": "<ship to address 1>",
            "shipToLocationAddress2": "<ship to address 2>",
            "shipToLocationCity": "<ship to city>",
            "shipToLocationState": "<ship to state>",
            "shipToLocationPostalCode": "<ship to postal code>",
            "shipToLocationCountry": "<ship to country>",
            "standardCarrierAlphaCode": "<SCAC>",
            "carrierShipmentMethod": "<carrier shipment method>",
            "equipmentDescription": "<equipment description>",
            "equipmentNumber": "<equipment number>",
            "appointmentNumber": "<appointment number>",
            "carrierTrackingNumber": "<carrier tracking number>",
            "loadPlanningNumber": "<load planning number>",
            "methodOfPayment": "<method of payment>",
            "shipmentLadingQuantity": 10,
            "shipmentLadingUom": "CA",
            "sharedByCompanyName": "Supplier Account Name",
            "sharedDateTime": "2024-06-15T14:40:00Z",
            "productList": [
                {
                    "productId": "cccccccc-cccc-cccc-cccc-cccccccccccc",
                    "tlcSourceLocationId": "<tlc source location id>",
                    "palletId": "<SSCC>",
                    "palletLpn": "<pallet LPN>",
                    "palletPackagingDescriptionCode": "<pallet packaging description code>",
                    "palletHigh": "<pallet high>",
                    "palletTie": "<pallet tie>",
                    "iotDevice": "<iot device>",
                    "poLineNumber": "<purchase order line number>",
                    "vendorItemCode": "VITEM-1",
                    "vendorItemDescription": "<vendor item description>",
                    "purchaserItemCode": "<purchaser item code>",
                    "caseGtin": "00012345678905",
                    "caseLotNumber": "LOT123",
                    "shipQuantity": 10.0,
                    "shipQuantityUom": "CA",
                    "brandName": "<brand name>",
                    "productCommodity": "<product commodity>",
                    "productVariety": "<product variety>",
                    "packSize": "<pack size>",
                    "packStyle": "<pack style>",
                    "expirationDate": "<expiration date>",
                    "productionDate": "<production date>",
                    "packagingDate": "<packaging date>",
                    "bestBeforeDate": "<best before date>",
                    "harvestDate": "<harvest date>",
                    "countryOfOrigin": "US",
                    "itemUpc": "<item UPC>",
                    "itemPlu": "<item PLU>",
                    "itemDateCode": "<item date code>",
                    "itemDateCodeType": "<item date code type>",
                    "weightType": "<weight type>",
                    "weightUnit": "<weight unit>",
                    "weightValue": "<weight value>",
                    "tlcSourceReferenceGln": "<TLC source reference GLN>",
                    "tlcSourceReferenceDuns": "<TLC source reference DUNS>",
                    "tlcSourceReferenceFfrn": "<TLC source reference FFRN>",
                    "tlcSourceReferenceFei": "<TLC source reference FEI>",
                    "tlcSourceReferenceUrl": "<TLC source reference URL>",
                    "tlcSourceReferenceOther": "<TLC source reference other>",
                    "tlcSourceName": "<TLC source name>",
                    "tlcSourceAddress1": "<TLC source address 1>",
                    "tlcSourceAddress2": "<TLC source address 2>",
                    "tlcSourceCity": "<TLC source city>",
                    "tlcSourceState": "<TLC source state>",
                    "tlcSourcePostalCode": "<TLC source postal code>",
                    "tlcSourceCountry": "<TLC source country>",
                    "tlcSourcePhoneNumber": "<TLC source phone number>",
                    "referenceDocumentType": "<reference document type>",
                    "referenceDocumentNumber": "<reference document number>"
                }
            ]
        }
    ],
    "pageable": {
        "pageNumber": 0,
        "pageSize": 20,
        "sort": {
            "unsorted": false,
            "sorted": true,
            "empty": false
        },
        "offset": 0,
        "unpaged": false,
        "paged": true
    },
    "totalPages": 1,
    "totalElements": 1,
    "last": true,
    "numberOfElements": 1,
    "size": 20,
    "number": 0,
    "sort": {
        "unsorted": false,
        "sorted": true,
        "empty": false
    },
    "first": true,
    "empty": false
}

Content​

  • id (uuid): Event header ID
  • eventId (string): Business event identifier
  • eventDateTime (datetime, UTC): Event/ship date
  • eventTransactionTime (datetime, UTC): Transaction time
  • purchaseOrderDate (date): Purchase order date
  • purchaseOrderNumber (string): Mapped from reference document number
  • billOfLadingNumber (string): Bill of lading number
  • asnNumber (string): ASN (advanced shipping notice) number
  • expectedDeliveryDate (date): Expected delivery date
  • businessUnit (string): Business unit
  • shipFromId (uuid): Master location ID only; null on legacy rows without location_id
  • shipFromLocationCode (string): Ship-from location code
  • shipFromLocationName (string): Ship-from location name
  • shipFromLocationPhoneNumber (string): Ship-from phone number
  • shipFromLocationAddress1 (string): Ship-from address line 1
  • shipFromLocationAddress2 (string): Ship-from address line 2
  • shipFromLocationCity (string): Ship-from city
  • shipFromLocationState (string): Ship-from state
  • shipFromLocationPostalCode (string): Ship-from postal code
  • shipFromLocationCountry (string): Ship-from country
  • shipToId (uuid): Master location ID only; null on legacy rows without location_id
  • shipToLocationCode (string): Ship-to location code
  • shipToCompanyName (string): Ship-to company name
  • shipToLocationName (string): Ship-to location name
  • shipToLocationPhoneNumber (string): Ship-to phone number
  • shipToLocationAddress1 (string): Ship-to address line 1
  • shipToLocationAddress2 (string): Ship-to address line 2
  • shipToLocationCity (string): Ship-to city
  • shipToLocationState (string): Ship-to state
  • shipToLocationPostalCode (string): Ship-to postal code
  • shipToLocationCountry (string): Ship-to country
  • standardCarrierAlphaCode (string): Standard Carrier Alpha Code (SCAC)
  • carrierShipmentMethod (string): Carrier shipment method
  • equipmentDescription (string): Equipment description
  • equipmentNumber (string): Equipment number
  • appointmentNumber (string): Appointment number
  • carrierTrackingNumber (string): Carrier tracking number
  • loadPlanningNumber (string): Load planning number
  • methodOfPayment (string): Method of payment
  • shipmentLadingQuantity (integer): Shipment lading quantity
  • shipmentLadingUom (string): Shipment lading unit of measure
  • sharedByCompanyName (string): Sharing supplier company name
  • sharedDateTime (datetime, UTC): When the share occurred
  • productList (object[]): Products on the shipment
    • productId (uuid): Master product ID; null if not stored
    • tlcSourceLocationId (uuid): TLC source location ID
    • palletId (string): SSCC
    • palletLpn (string): Pallet LPN
    • palletPackagingDescriptionCode (string): Pallet packaging description code
    • palletHigh (integer): Pallet high
    • palletTie (integer): Pallet tie
    • iotDevice (string): IoT device identifier
    • poLineNumber (string): Purchase order line number
    • vendorItemCode (string): Vendor item code
    • vendorItemDescription (string): Vendor item description
    • purchaserItemCode (string): Purchaser item code
    • caseGtin (string): Case GTIN
    • caseLotNumber (string): Case lot / TLC number
    • shipQuantity (number): Ship quantity
    • shipQuantityUom (string): Ship quantity unit of measure
    • brandName (string): Brand name
    • productCommodity (string): Product commodity
    • productVariety (string): Product variety
    • packSize (string): Pack size
    • packStyle (string): Pack style
    • expirationDate (date): Expiration date
    • productionDate (date): Production date
    • packagingDate (date): Packaging date
    • bestBeforeDate (date): Best before date
    • harvestDate (date): Harvest date
    • countryOfOrigin (string): Country of origin
    • itemUpc (string): Item UPC
    • itemPlu (string): Item PLU
    • itemDateCode (string): Item date code
    • itemDateCodeType (string): Item date code type
    • weightType (string): Weight type
    • weightUnit (string): Weight unit
    • weightValue (number): Weight value
    • tlcSourceReferenceGln (string): TLC source reference GLN (populated from TLC source type)
    • tlcSourceReferenceDuns (string): TLC source reference DUNS (populated from TLC source type)
    • tlcSourceReferenceFfrn (string): TLC source reference FFRN (populated from TLC source type)
    • tlcSourceReferenceFei (string): TLC source reference FEI (populated from TLC source type)
    • tlcSourceReferenceUrl (string): TLC source reference URL (populated from TLC source type)
    • tlcSourceReferenceOther (string): TLC source reference other (populated from TLC source type)
    • tlcSourceName (string): TLC source name
    • tlcSourceAddress1 (string): TLC source address line 1
    • tlcSourceAddress2 (string): TLC source address line 2
    • tlcSourceCity (string): TLC source city
    • tlcSourceState (string): TLC source state
    • tlcSourcePostalCode (string): TLC source postal code
    • tlcSourceCountry (string): TLC source country
    • tlcSourcePhoneNumber (string): TLC source phone number
    • referenceDocumentType (string): Reference document type
    • referenceDocumentNumber (string): Reference document number
note

shipFromId, shipToId, and productId are stored master IDs only. There is no fallback from GLN or location/product codes. Older events ingested before those IDs were persisted may return null. Treat these fields as optional and fall back to codes/names when null.

Pageable​

  • pageable (object)
    • pageNumber (number): The current page number in the page series. Index 0 is first page
    • pageSize (number): The number of events contained in the page
    • offset (number): If there is an offset specified on there return results this will be populates. Default is 0
    • unpaged (boolean): If the record set is unpaged then true else false
    • paged (boolean): If the record set is paged then true else false
    • sort (object)
      • unsorted (boolean): If the record set is unsorted then true else false
      • sorted (boolean): If the record set is sorted then true else false
      • empty (boolean): If the record set is empty then true else false
  • totalPages (number): The total amount of pages that contain all events in the query
  • totalElements (number): The total amount of events in the query
  • last (boolean): If the page is the last in the series then true else false
  • numberOfElements (number): The total amount of events in the table
  • size (number): The number of events contained in the page
  • number (number): The current page number in the page series
  • sort (object)
    • unsorted (boolean): If the record set is unsorted then true else false
    • sorted (boolean): If the record set is sorted then true else false
    • empty (boolean): If the record set is empty then true else false
  • first (boolean): If the page is the first in the series then true else false
  • empty (boolean): If the page is empty then true else false

No matching events​

When no events match the request, the API still returns 200 OK with an empty page:

{
    "content": [],
    "number": 0,
    "size": 20,
    "numberOfElements": 0,
    "totalElements": 0,
    "totalPages": 0
}

Integration Notes​

  • Prefer canonical filters (purchaseOrderNumber, caseLotNumber, etc.) over legacy contains filters for deterministic integrations.
  • Treat shipFromId / shipToId / productId as optional; fall back to codes/names when null.
  • Page through results until number + 1 >= totalPages.
  • Sharing depends on network/location configuration for the ship-to; if nothing is returned, verify the account is shared on that location before debugging filters.
  • GET /critical-tracking-events/shared-with-me: User-facing Trace App “shared with me” (user auth + permissions)
  • POST /auto-receive: Queue eligible shared shipments for receiving event creation
  • POST /auto-receive/{shippingEventId}: Auto-receive a single shared shipping event