Key differences between V1 and V2 APIs and events of the Inventory service

Learn the key differences between V1 and V2 APIs and events of the Inventory service.

Attention:

V1 availability and reservation APIs are scheduled for end of support at the end of February 2025. Complete V1 to V2 migration of availability and reservation APIs to continue using and leveraging the latest capabilities. For more information about what to do, see Upgrading to Inventory service V2 APIs and events.

APIs

In V1 availability APIs, the available quantity is placed onhand or in future field, based on the supplyType. In V2, it is entirely based on the ETA of supply. If the ETA of supply is in the future, then it is accounted for in future availability. Otherwise, it is accounted for current availability window in the response.
The V2 availability requests support new fields: requestedEndTs and requestedQuantity that are not there in V1. For more information, see Node availability request.
The V1 network API allows users to override the distributionGroupId attribute at line level that allows fetching availability of multiple distribution groups in a single call. The V2 network API doesn’t allow this. If there is a need to get availability at multiple distribution groups, then it is suggested to make separate API calls by passing one distribution group at a time. For more information, see Network request.
V2 reservation by date request supports requestedReservationTs and requestedEndTs fields that are not supported in V1. For more information, see Reservation by date request.
While using V2 availability mode, the V2 distribution group reservation is always placed at a node by using the node priority feature. In V1 availability mode, you can choose the distribution group level reservation with or without node priority. For more information about the node priority, see Reservations.

For more information about V2 APIs, see V2 availability APIs.

Events

During V1 to V2 migration, the inventory with zero availability is not getting ported so they do not appear in the snapshot events. If your system needs to continuously publish the zero availability for these items, you must synchronize the supply after the migration.
In V1 events, the blank attribute values are published as empty strings. In V2, they are published as null.
Note: The V2 events follow the similar format as V2 APIs to show availability.

For more information about V2 events, see New event formats.

Node availability request

V1 node availability request

https://api.watsoncommerce.ibm.com/inventory/{tenantId}/v1/availability/node
{
    "demandType": "OPEN_ORDER",
    "lines": [
        {
            "lineId": "1",
            "itemId": "PLATE",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "deliveryMethod": "PICK",
            "segment": "ONLINE",
            "segmentType": "Channel",
            "shipNodes": [
                "Matrix-Store-001"
            ]
        }
    ]
}

V2 node availability request

https://api.watsoncommerce.ibm.com/inventory/{tenantId}/v2/availability/node?bundleAggregatesAcrossNodes={bundleAggregatesAcrossNodes}
{
    "availabilityType": "SELL",
    "lines": [
        {
            "lineId": "1",
            "itemId": "ITEM",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "deliveryMethod": "PICK",
            "segment": "ONLINE",
            "segmentType": "Channel",
            "requestedEndTs": "2020-03-02T00:00:00Z",
            "requestedQuantity": "10",
            "shipNodes": [
                "Matrix-Store-001"
            ]
        }
    ]
}

Node availability response

The V1 response has availability shown in onhandAvailableQuantity and futureAvailableQuantity which are aggregated quantities based on supplyTypes. The V2 response shows availability with time windows to know the correct availability at any given time. The currentAvailbility is derived from supplies with current or past ETAs. The futureAvailability is derived from supplies with future ETAs and shown with date breakups. If a supply is effective within multiple time windows, then it is considered in all those availability windows.

For more information, see Node availability by date.

V1 node availability response

{
    "lines": [
        {
            "lineId": "1",
            "shipNodeAvailability": [
                {
                    "deliveryMethod": "PICK",
                    "onhandAvailableQuantity": 10.0,
                    "futureAvailableQuantity": 20.0,
                    "onhandEarliestShipTs": "2022-10-11T21:28:03.226Z",
                    "onhandLatestShipTs": "2022-10-11T21:28:03.226Z",
                    "futureEarliestShipTs": "2022-10-11T21:28:03.226Z",
                    "futureLatestShipTs": "2022-10-11T21:28:03.226Z",
                    "earliestShipTs": "2022-10-11T21:28:03.226Z",
                    "latestShipTs": "2022-10-11T21:28:03.226Z",
                    "thresholdLevel": "0",
                    "thresholdType": "ONHAND",
                    "shipNode": "Matrix-Store-001",
                    "totalAvailableQuantity": 30.0
                }
            ]
        }
    ]
}

V2 node availability response

{
    "availabilityType": "SELL",
    "considerSafetyStock": true,
    "lines": [
        {
     "deliveryMethod": "PICK",
            "itemId": "ITEM",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "segment": "ONLINE",
            "segmentType": "Channel",
            "shipNodes": [
                "Matrix-Store-001"
            ],
            "lineId": "1",
            "shipNodeAvailabilities": [
                {
                    "shipNode": "Matrix-Store-001",
                    "currentAvailability": {
                        "toTs": "2022-10-20T00:00:00.000Z",
                        "availableQuantity": 10.0,
                        "shortageQuantity": 0.0,
                        "thresholdLevel": 0,
                        "thresholdType": "ONHAND"
                    },
                    "futureAvailability": [
                        {
                            "toTs": "2022-10-26T21:53:41.967Z",
                            "availableQuantity": 30.0,
                            "shortageQuantity": 0.0,
                            "fromTs": "2022-10-20T00:00:00.000Z"
                        }
                    ]
                }
            ]
        }
    ]
}

Network request

V1 network request

{
    "distributionGroupId": "DG-1",
    "segment": "ONLINE",
    "segmentType": "Channel",
    "considerSafetyStock": false
    "lines": [
        {
            "lineId": "1",
            "itemId": "PLATE",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "deliveryMethod": "SHP",
            "segment": "ONLINE",
            "segmentType": "Channel”,
	    "distributionGroupId": "DG-1",
        }
    ]
}

V2 network request

{
    "distributionGroupId": "DG-1",
    "segment": "ONLINE",
    "segmentType": "Channel",
     "considerSafetyStock": false,
    "lines": [
        {
            "lineId": "1",
            "itemId": "ITEM",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "requestedEndTs": "2020-03-02T00:00:00Z",
            "requestedQuantity": "10",
            "deliveryMethod": "SHP",
            "segment": "ONLINE",
            "segmentType": "Channel”
        }
    ]
}

Network response

Similar to Node response.

For more information, see Distribution group availability by date.

V1 network response

{
    "lines": [
        {
            "lineId": "1",
            "networkAvailabilities": [
                {
                    "deliveryMethod": "SHP",
                    "onhandAvailableQuantity": 10.0,
                    "futureAvailableQuantity": 20.0,
                    "onhandEarliestShipTs": "2022-10-11T21:42:50.198Z",
                    "onhandLatestShipTs": "2022-10-11T21:42:50.198Z",
                    "futureEarliestShipTs": "2022-10-11T21:42:50.198Z",
                    "futureLatestShipTs": "2022-10-11T21:42:50.198Z",
                    "earliestShipTs": "2022-10-11T21:42:50.198Z",
                    "latestShipTs": "2022-10-11T21:42:50.198Z",
                    "thresholdLevel": "0",
                    "thresholdType": "ONHAND",
                    "alertLevel": "0",
                    "alertQuantity": 922337203685477,
                    "distributionGroupId": "DG-1",
                    "thresholdQuantity": 922337203685477,
                    "totalAvailableQuantity": 30.0
                }
            ]
        }
    ]
}

V2 network response

{
    "considerSafetyStock": true,
    "lines": [
        {
            "itemId": "ITEM",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "deliveryMethod": "SHP",
            "segment": "ONLINE",
            "segmentType": "Channel",
            "lineId": "1",
            "networkAvailabilities": [
                {
                    "distributionGroupId": "DG-1",
                    "currentAvailability": {
                        "toTs": "2022-10-20T00:00:00.000Z",
                        "availableQuantity": 10.0,
                        "shortageQuantity": 0.0,
                        "thresholdLevel": 0,
                        "thresholdType": "ONHAND",
                        "thresholdQuantity": 922337203685477
                    },
                    "futureAvailability": [
                        {
                            "toTs": "2022-10-27T16:38:46.347Z",
                            "availableQuantity": 30.0,
                            "shortageQuantity": 0.0,
                            "fromTs": "2022-10-20T00:00:00.000Z"
                        }
                    ]
                }
            ]
        }
    ]
}

Reservation by date request

V1 reservation by date request

https://api.watsoncommerce.ibm.com/inventory/{tenantId}/v1/reservations

{
    "demandType": "OPEN_ORDER",
    "lines": [
        {
            "itemId": "PLATE",
            "lineId": "1",
            "quantity": 1.0,
            "shipNode": "Matrix-Store-001",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "deliveryMethod": "PICK",
            "segment": "ONLINE",
            "segmentType": "Channel"
        }
    ],
    "reference": "REF5",
    "timeToExpire": 10
}

V2 reservation by date request

https://api.watsoncommerce.ibm.com/inventory/{tenantId}/v2/reservations

{
    "availabilityType": "SELL",
    "lines": [
        {
            "itemId": "ITEM",
            "lineId": "1",
            "quantity": 1.0,
            "shipNode": "Matrix-Store-001",
            "unitOfMeasure": "EACH",
            "requestedReservationTs": "2020-01-01T00:00:00Z",
            "requestedEndTs": "2020-01-31T00:00:00Z",
            "productClass": "NEW",
            "deliveryMethod": "PICK",
            "segment": "ONLINE",
            "segmentType": "Channel"
        }
    ],
    "reference": "REF5",
    "timeToExpire": 10
}

Reservation by date response

The V1 reservations can be placed at current time only. The V2 reservations can be placed at future time that uses the fields requestedReservationTs and requestedEndTs so that maximum quantity can be reserved. The reservationTs tells the time when reservation is placed.

For more information, see Reservations by date (V2).

V1 reservation by date response

{
    "lines": [
        {
            "lineId": "1",
            "reservedQuantity": 1.0,
            "id": "891ffab9-ada7-471a-98a2-76214ebbdda1",
            "reservationId": "891ffab9-ada7-471a-98a2-76214ebbdda1",
            "expirationTs": "2022-10-11T21:43:00.000Z"
        }
    ]
}

V2 reservation by date response

{
    "lines": [
        {
            "itemId": "ITEM",
            "unitOfMeasure": "EACH",
            "productClass": "NEW",
            "shipNode": "Matrix-Store-001",
            "deliveryMethod": "PICK",
            "segment": "ONLINE",
            "segmentType": "Channel",
            "lineId": "1",
            "requestedReservationTs": "2022-10-12T17:56:00.000Z",
            "quantity": 1.0,
            "totalReservedQuantity": 1.0,
            "reservations": [
                {
                    "id": "32e7aebc-9c33-414e-84a9-cff875028bca",
                    "reservationTs": "2022-10-12T17:56:00.000Z",
                    "expirationTs": "2022-10-12T18:07:00.000Z",
                    "reservedQuantity": 1.0,
                    "shipNode": "Matrix-Store-001"
                }
            ]
        }
    ],
    "availabilityType": "SELL",
    "considerSafetyStock": true
}