Skip to main content

Get Receiving Events

Method: GET
/data-provider/events/receiving

As a Data Provider of iFoodDS, you can use the Get Receiving Event API to retrieve receiving event data from the iFoodDS Trace Exchange platform.

info

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

Request​

Type: application/json

Retrieving receiving events via the API is done through paging. Supply optional query parameters in the request URL to select a page and filter the events returned.

Query Parameters​

All query parameters are optional. The event type is implied as receiving; no type parameter is needed.

Pagination & Dates​

  • page (number): The page index of the events to return. The first page is index 0.
  • size (number): The number of results to return per page. Default value is 20.
  • sort (string): Spring Pageable sort expression.
  • submitStartDateTime (datetime): Includes events whose date created is on or after the specified date and time (inclusive).
  • submitEndDateTime (datetime): Includes events whose date created is on or before the specified date and time (inclusive).
  • eventStartDateTime (datetime): Includes events whose receive date is on or after the specified date and time (inclusive).
  • eventEndDateTime (datetime): Includes events whose receive date is on or before the specified date and time (inclusive).

Event Identification​

These filters support multiple values via a comma-separated list or by repeating the parameter. Matching is exact and case-sensitive.

  • eventId (string): Exact, case-sensitive match on the submitted event identifier.
  • id (uuid): Exact match on the raw KDE row UUID.

Shipment & Location Identification​

These filters support multiple values via a comma-separated list or by repeating the parameter. Matching is exact and case-sensitive.

  • purchaseOrderNumber (string): Exact, case-sensitive match on purchase order number.
  • asnNumber (string): Exact, case-sensitive match on ASN (advanced shipping notice) number.
  • shipFromLocationCode (string): Exact, case-sensitive match on ship-from location code.
  • shipToLocationCode (string): Exact, case-sensitive match on ship-to location code.
  • caseLotNumber (string): Exact, case-sensitive match on case lot number.
  • caseGtin (string): Exact, case-sensitive match on case GTIN.
  • vendorItemCode (string): Exact, case-sensitive match on vendor item code.
  • countryOfOrigin (string): Exact, case-sensitive match on country of origin.
  • tlcSourceReferenceGln (string): Exact, case-sensitive match on TLC source reference GLN.

Matching Behavior​

  • String filters use exact, case-sensitive matching.
  • Multi-value filters accept repeated query parameters or comma-separated values.
  • eventId matches the submitted event identifier; id matches the raw KDE row UUID.
  • Submission date bounds apply to date created. Event date bounds apply to receive date. All start and end bounds are inclusive.

Data Constraints​

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

Request Examples​

Find receipts during a specified period​

Both event date-time boundaries are inclusive.

Receipts during a specified period
/data-provider/events/receiving?eventStartDateTime=2026-09-14T00:00:00&eventEndDateTime=2026-09-20T23:59:59

Find events by submission date range​

Both boundaries apply to date created and are inclusive.

Submission date range
/data-provider/events/receiving?submitStartDateTime=2026-09-14T00:00:00&submitEndDateTime=2026-09-20T23:59:59

Find receipts from a supplier location​

Match a ship-from location code
/data-provider/events/receiving?shipFromLocationCode=XYZ-DC01

Find receipts tied to one or more purchase orders​

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

Match purchase order numbers
/data-provider/events/receiving?purchaseOrderNumber=12345,67890
Match purchase order numbers (repeated params)
/data-provider/events/receiving?purchaseOrderNumber=12345&purchaseOrderNumber=67890

Find an event by its submitted identifier​

Match a submitted event identifier
/data-provider/events/receiving?eventId=EVENT123

Find an event by its raw KDE row UUID​

Match a raw KDE row UUID
/data-provider/events/receiving?id=123e4567-e89b-42d3-a456-426614174000

Response​

Return result for the receiving event data queried.

{
    "content": [
        {
            "id": "<event id>",
            "eventDateTime": "<event date>",
            "dataProviderVendorId": "<data provider vendor id>",
            "dataProviderVendorName": "<data provider vendor name>",
            "purchaseOrderDate": "<purchase order date>",
            "purchaseOrderNumber": "<purchase order number>",
            "billOfLadingNumber": "<bol number>",
            "asnNumber": "<ASN (advanced shipping notice) number>",
            "expectedDeliveryDate": "<expected delivery date>",
            "shipFromLocationCode": "<ship from vendor location code>",
            "shipToLocationCode": "<ship to location code>",
            "standardCarrierAlphaCode": "<standard carrier alpha code (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": "<shipment lading quantity>",
            "shipmentLadingUom": "<shipment lading unit of measure>",
            "eventTransactionTime": "<event transaction time>",
            "businessUnit": "<business unit>",
            "productList": [
                {
                    "palletId": "<pallet id>",
                    "palletPackagingDescriptionCode": "<pallet packaging description code>",
                    "palletTiers": "<pallet tiers>",
                    "palletBlocks": "<pallet blocks>",
                    "palletLayers": "<pallet layers>",
                    "cartonsPerLayer": "<cartons per layer>",
                    "poLineNumber": "<purchase order line number>",
                    "vendorItemCode": "<vendor item code>",
                    "purchaserItemCode": "<purchaser item code>",
                    "caseGtin": "<case GTIN (Global Trade Identification Number)",
                    "caseLotNumber": "<case lot number>",
                    "shipQuantity": "<pallet quantity>",
                    "shipQuantityUom": "<ship quantity uom> (Units of Measure)",
                    "expirationDate": "<expiration date>",
                    "productionDate": "<production date>",
                    "packagingDate": "<packaging date>",
                    "bestBeforeDate": "<best before date>",
                    "harvestDate": "<harvest date>",
                    "countryOfOrigin": "<country of origin>",
                    "tlcSourceReferenceDuns": "<TLC source reference duns>",
                    "tlcSourceReferenceGln": "<TLC source reference gln>",
                    "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>",
                    "tlcSourcePhoneNumber": "<TLC source phone number>",
                    "itemUpc": "<product UPC (Universal Product Code)>",
                    "itemPlu": "<product PLU>",
                    "itemDateCode": "<product date code>",
                    "itemDateCodeType": "<product date code type>"
                }
            ]
        }
    ],
    "pageable": {
        "pageNumber": <page number>,
        "pageSize": <page size>,
        "sort": {
            "unsorted": <is unsorted>,
            "sorted": <is sorted>,
            "empty": <is page empty>
        },
        "offset": <offset size>,
        "unpaged": <is unpaged>,
        "paged": <is paged>
    },
    "totalPages": <total pages>,
    "totalElements": <total elements>,
    "last": <is last page>,
    "numberOfElements": <number of elements>,
    "size": <page size>,
    "number": <page number>,
    "sort": {
        "unsorted": <is unsorted>,
        "sorted": <is sorted>,
        "empty": <is empty>
    },
    "first": <is first page>,
    "empty": <is page empty>
}

Content​

  • id (uuid): The unique id of the event
  • eventDateTime (datetime): Date and time the order was actually received
  • dataProviderVendorId (string): Your ID for the vendor/supplier
  • dataProviderVendorName (string): Name of the vendor/supplier
  • purchaseOrderDate (date): Purchase order date
  • purchaseOrderNumber (string): The purchase order number you received from your customer
  • billOfLadingNumber (string): The Bill of Lading provided by you to your customer
  • asnNumber (string): This is the unique identifier for the ASN you provide to your customer (if you provide one)
  • expectedDeliveryDate (date): Date when shipper expects to deliver goods to recipient
  • shipFromLocationCode (string): The vendor’s location code for ship from location
  • shipToLocationCode (string): The buyer’s location code for ship to location. This should be provided as part of the Purchase Order
  • standardCarrierAlphaCode (string): Standard Carrier Alpha Code (SCAC).
  • carrierShipmentMethod (string): Carrier shipment method code.
  • equipmentDescription (string): Description of the transport equipment.
  • equipmentNumber (string): Equipment identifier.
  • appointmentNumber (string): Appointment or delivery appointment number.
  • carrierTrackingNumber (string): Carrier-provided tracking number.
  • loadPlanningNumber (string): Load or load planning number.
  • methodOfPayment (string): Method of payment (e.g. PREPAID, COLLECT).
  • shipmentLadingQuantity (number): Quantity of lading units in the shipment.
  • shipmentLadingUom (string): Unit of measure for shipment lading quantity.
  • eventTransactionTime (datetime): The time the event was sent
  • businessUnit (string): The internal organizational group responsible for the event
  • productList (object[])
    • palletId (string): GS1 Serial Shipping Container Code, SSCC-18 (if provided)
    • palletPackagingDescriptionCode (string): Pallet packaging description code.
    • palletTiers (number): Number of tiers on the pallet.
    • palletBlocks (number): Number of blocks on the pallet.
    • palletLayers (number): Number of layers per pallet
    • cartonsPerLayer (number): Number of cartons per layer
    • poLineNumber (string): Line number in the purchase order for this item; this links the Traceability Lot Code to the line item on the PO
    • vendorItemCode (string): This is the vendor's (or your) internal product id or item code stored in their master data. If the cases shipped are labeled with a case GTIN-14, this information should be stored in the product master data record for the item code / product id referenced
    • purchaserItemCode (string): This is the purchaser's product item code provided via their PO or other form of data sharing. This information is stored in your master data. If the customer has shared a GTIN, it should be stored in the master data record. The purchaser's item code may also be the purchaser’s GTIN, but not necessarily-–it could be a SKU or another type of ID. This may point to the receiver’s master product data record
    • caseGtin (string): GTIN-14 of cases on pallet
    • caseLotNumber (string): This is the Lot Number displayed on the case label you are providing to the customer. This will be required starting in January 2026
    • shipQuantity (number): The number of units of this Traceability Lot Code on the pallet
    • shipQuantityUom (string): Unit of measure (e.g., Case)
    • expirationDate (date): The expiration date
    • productionDate (date): The production date
    • packagingDate (date): The packaging date
    • bestBeforeDate (date): The best before date
    • harvestDate (date): The harvesting date
    • countryOfOrigin (string): The three letter country code of origin
    • tlcSourceReferenceDuns (string): 9 Digit Dun & Bradstreet Number, must be registered in DUNS and available to FDA. The TLC Source reference DUNS + 4
    • tlcSourceReferenceGln (string): 13 Digit GS1 Global Location Number. Must be registered in GS1 US Data Hub | Location. The TLC Source reference GLN
    • tlcSourceReferenceFfrn (string): FDA Food Facility Registration Number, must be current in FDA Facility Regisration Database. The TLC Source reference FFRN
    • tlcSourceReferenceFei (string): FDA Establishment Identifier. This number may be requested at no cost from FDA. The TLC Source reference FEI
    • tlcSourceReferenceUrl (string): A web link point to a site where FDA may access the TLC Source Reference. The TLC Source reference URL
    • tlcSourceReferenceOther (string): This could be another identifier. One can prefix the ID with a type to make it easier to lookup. For example: 'USDAEgg: Plant 42"
    • tlcSourceName (string): The TLC source name
    • tlcSourceAddress1 (string): The TLC Source physical street address line 1 information
    • tlcSourceAddress2 (string): The TLC Source physical street address line 2 information, if applicable
    • tlcSourceCity (string): The TLC Source city location
    • tlcSourceState (string): The TLC Source state or region location
    • tlcSourcePostalCode (string): The TLC Source ZIP or postal code
    • tlcSourceCountry (string): The TLC Source country
    • tlcSourcePhoneNumber (string): The TLC Source phone number
    • itemUpc (string): Item-level Universal Product Code, may be GTIN-8, GTIN-12, or GTIN-13. GS1 GTIN Executive Summary
    • itemPlu (string): Include if items in the case are marked with PLU numbers; this may be used instead of UPC
    • itemDateCode (date): Often items are marked with a date code; if so, this field can be used to capture it
    • itemDateCodeType (string): Indicate the type of date code if provided

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