Edit

Share via

Inventory availability APIs for e-commerce

Note

Community interest groups have now moved from Yammer to Microsoft Viva Engage. To join a Viva Engage community and take part in the latest discussions, fill out the Request access to Finance and Operations Viva Engage Community form and choose the community you want to join.

This article describes the inventory availability APIs for e-commerce in Microsoft Dynamics 365 Commerce.

Commerce provides the following APIs to query inventory availability of a product in e-commerce scenarios:

  • GetEstimatedAvailability – Use this API to query inventory for a product or product variant in the online channel's default warehouse or warehouses that are linked to the online channel's fulfillment group.
  • GetEstimatedProductWarehouseAvailability – Use this API to query inventory for a product or product variant in a specific warehouse.
  • GetDimensionValuesWithEstimatedAvailabilities – Use this API to query inventory levels that are aggregated on the dimensions for a product, either in the online channel's default warehouse or in warehouses that are linked to the online channel's fulfillment group.
  • UpdateProductWarehouseAvailabilities – Use this API to update inventory for products or product variants in specific warehouses.

Note

The GetEstimatedAvailability and GetEstimatedProductWarehouseAvailability APIs replace the GetProductAvailabilities and GetAvailableInventoryNearby APIs used in Commerce version 10.0.7 and earlier.

For more information about how to consume Retail Server APIs in external applications, see Consume Retail Server APIs in external applications.

GetEstimatedAvailability

Input parameters

Name Type Required/Optional Description
searchCriteria InventoryAvailabilitySearchCriteria Required

InventoryAvailabilitySearchCriteria

Name Type Required/Optional Description
ProductIds IEnumberable<long> Required
DefaultWarehouseOnly bool Optional If the value is true, only the online channel's default warehouse is queried. If the value is false, warehouses linked to the online channel's fulfillment group and share same legal entity with the online channel are queried.
SearchArea SearchArea Optional The area to search for stores for pickup in the fulfillment groups.
FilterByChannelFulfillmentGroup bool Optional This parameter determines the fulfillment groups when DefaultWarehouseOnly is set to false.
DeliveryModeTypeFilterValue (int) DeliveryModeTypeFilter Optional

Filter warehouses by their supported delivery modes:

  • (0) All – Find all warehouses. This value is the default value.
  • (1) Shipping – Find warehouses that are eligible for shipping.
  • (2) Pickup – Find warehouses that are eligible for pickup.
QuantityUnitTypeValue (int) QuantityUnitType Optional

The unit of measure to return the quantity in:

  • (0) Inventory – The inventory unit of measure. This value is the default value.
  • (1) Purchase – The purchase unit of measure.
  • (2) Sales – The sales unit of measure.

SearchArea

Name Type Required/Optional Description
Latitude decimal Optional
Longitude decimal Optional
Radius double Optional
DistanceUnit (int) DistanceUnit Optional
  • (0) Miles
  • (1) Kilometers
IsUnbounded bool Optional

Sample request body

{
    "searchCriteria": {
        "ProductIds": [
            123456
        ],
        "QuantityUnitTypeValue": 2,
        "DefaultWarehouseOnly": true
    }
}

Sample response body

{
    "ProductWarehouseInventoryAvailabilities": [
        {
            "ProductId": 123456,
            "InventLocationId": "{OnlineChannelWarehouse}",
            "DataAreaId": "{DataAreaId}",
            "PhysicalInventory": 0,
            "PhysicalReserved": 0,
            "TotalAvailable": 1,
            "TotalAvailableInventoryLevelLabel": "Available",
            "TotalAvailableInventoryLevelCode": "AVAIL",
            "OrderedInTotal": 0,
            "PhysicalAvailable": 0,
            "PhysicalAvailableInventoryLevelLabel": "Out of stock",
            "PhysicalAvailableInventoryLevelCode": "OOS",
            "LastInventoryTransactionId": 987654,
            "UnpostedOnlineOrderedQuantity": 0,
            "UnpostedFulfilledQuantity": 0,
            "IsInventoryAvailabilityQuantityReturned": true,
            "UnprocessedQuantity": 0,
            "QuantityUnitTypeValue": 2,
            "UnitOfMeasure": "ea",
            "MaximumPurchasablePhysicalAvailableQuantity": 0,
            "MaximumPurchasableTotalAvailableQuantity": 1,
            "SumUncountedTransactions": 0,
            "ExtensionProperties": []
        }
    ],
    "AggregatedProductInventoryAvailabilities": [
        {
            "ProductId": 123456,
            "DataAreaId": "{DataAreaId}",
            "TotalAvailableQuantity": 1,
            "TotalAvailableInventoryLevelLabel": "Available",
            "TotalAvailableInventoryLevelCode": "AVAIL",
            "PhysicalAvailableQuantity": 0,
            "PhysicalAvailableInventoryLevelLabel": "Out of stock",
            "PhysicalAvailableInventoryLevelCode": "OOS",
            "QuantityUnitTypeValue": 2,
            "UnitOfMeasure": "ea",
            "MaximumPurchasablePhysicalAvailableQuantity": 0,
            "MaximumPurchasableTotalAvailableQuantity": 1,
            "ExtensionProperties": []
        }
    ],
    "ExtensionProperties": []
}

GetEstimatedProductWarehouseAvailability

Input parameters

Name Type Required/Optional Description
productWarehouses IEnumerable<ProductWarehouse> Required

ProductWarehouse

Name Type Required/Optional Description
ProductId long Required
InventLocationId string Required The ID of the warehouse.
DataAreaId string Required

Sample request body

{
    "productWarehouses": [
        {
            "ProductId": 123456,
            "InventLocationId": "{WarehouseId}",
            "DataAreaId": "{DataAreaId}"
        }
    ]
}

Sample response body

{
    "ProductWarehouseInventoryAvailabilities": [
        {
            "ProductId": 123456,
            "InventLocationId": "{OnlineChannelWarehouse}",
            "DataAreaId": "{DataAreaId}",
            "PhysicalInventory": 0,
            "PhysicalReserved": 0,
            "TotalAvailable": 1,
            "TotalAvailableInventoryLevelLabel": "Available",
            "TotalAvailableInventoryLevelCode": "AVAIL",
            "OrderedInTotal": 0,
            "PhysicalAvailable": 0,
            "PhysicalAvailableInventoryLevelLabel": "Out of stock",
            "PhysicalAvailableInventoryLevelCode": "OOS",
            "LastInventoryTransactionId": 987654,
            "UnpostedOnlineOrderedQuantity": 0,
            "UnpostedFulfilledQuantity": 0,
            "IsInventoryAvailabilityQuantityReturned": true,
            "UnprocessedQuantity": 0,
            "QuantityUnitTypeValue": 2,
            "UnitOfMeasure": "ea",
            "MaximumPurchasablePhysicalAvailableQuantity": 0,
            "MaximumPurchasableTotalAvailableQuantity": 1,
            "SumUncountedTransactions": 0,
            "ExtensionProperties": []
        }
    ],
    "AggregatedProductInventoryAvailabilities": [
        {
            "ProductId": 123456,
            "DataAreaId": "{DataAreaId}",
            "TotalAvailableQuantity": 1,
            "TotalAvailableInventoryLevelLabel": "Available",
            "TotalAvailableInventoryLevelCode": "AVAIL",
            "PhysicalAvailableQuantity": 0,
            "PhysicalAvailableInventoryLevelLabel": "Out of stock",
            "PhysicalAvailableInventoryLevelCode": "OOS",
            "QuantityUnitTypeValue": 2,
            "UnitOfMeasure": "ea",
            "MaximumPurchasablePhysicalAvailableQuantity": 0,
            "MaximumPurchasableTotalAvailableQuantity": 1,
            "ExtensionProperties": []
        }
    ],
    "ExtensionProperties": []
}

GetDimensionValuesWithEstimatedAvailabilities

Input parameters

Name Type Required/Optional Description
searchCriteria ProductDimensionAvailabilitySearchCriteria Required

ProductDimensionAvailabilitySearchCriteria

Name Type Required/Optional Description
RequestedDimensionTypeValue (int) ProductDimensionType Required

The product dimension type to request and to aggregate inventory quantities by.

  • (1) Color – The color dimension.
  • (2) Configuration – The configuration dimension.
  • (3) Size – The size dimension.
  • (4) Style – The style dimension.
MatchingDimensionValues ICollection<ProductDimension> Optional Aggregate only products that have matching dimension values.
DefaultWarehouseOnly bool Optional If the value is true, only the online channel's default warehouse is queried. If the value is false, warehouses linked to the online channel's fulfillment group and share same legal entity with the online channel are queried.
FilterByChannelFulfillmentGroup bool Optional This parameter determines the fulfillment groups when DefaultWarehouseOnly is set to false.
DeliveryModeTypeFilterValue (int) DeliveryModeTypeFilter Optional

Filter warehouses by their supported delivery modes:

  • (0) All – Find all warehouses. This value is the default value.
  • (1) Shipping – Find warehouses that are eligible for shipping.
  • (2) Pickup – Find warehouses that are eligible for pickup.
CatalogId long Optional The identifier of the catalog that the product belongs to.

ProductDimension

Name Type Required/Optional Description
DimensionTypeValue (int) ProductDimensionType Required

The product dimension type to request and to aggregate inventory quantities by.

  • (1) Color – The color dimension.
  • (2) Configuration – The configuration dimension.
  • (3) Size – The size dimension.
  • (4) Style – The style dimension.
DimensionValue ProductDimensionValue Required

ProductDimensionValue

Name Type Required/Optional Description
RecordId long Required
Value string Required

Sample request body

{
    "searchCriteria": {
        "RequestedDimensionTypeValue": 3,
        "MatchingDimensionValues": [
            {
                "DimensionTypeValue": 3,
                "DimensionValue": {
                    "RecordId": 0,
                    "Value": "{Size}"
                }
            }
        ],
        "DefaultWarehouseOnly": true,
        "FilterByChannelFulfillmentGroup": true,
        "DeliveryModeTypeFilterValue": 1,
        "CatalogId": 0
    }
}

Sample response body

{
    "value": [
        {
            "DimensionTypeValue": 3,
            "DimensionValue": {
                "RecordId": 456789,
                "Value": "{Size}",
                "DimensionId": "{DimensionId}",
                "ColorHexCode": "",
                "ImageUrl": "",
                "RefinerGroup": "",
                "ExtensionProperties": []
            },
            "ProductIds": [
                123456
            ],
            "TotalAvailableInventoryLevelLabel": "Available",
            "TotalAvailableInventoryLevelCode": "AVAIL",
            "PhysicalAvailableInventoryLevelLabel": "Available",
            "PhysicalAvailableInventoryLevelCode": "AVAIL"
        }
    ]
}

UpdateProductWarehouseAvailabilities

The UpdateProductWarehouseAvailabilities API uses the Inventory Visibility Service (IVS) to update omnichannel inventory data in real time. To use this API, first enable IVS as the inventory data provider for your Commerce environment. The UpdateProductWarehouseAvailabilities API works under the BusinessPartnerEmployee role. Use this role for requests that represent a contractor working for a seller channel in a business to business to business (B2B2B) scenario.

Input parameters

Name Type Required/Optional Description
quantities IEnumerable<ProductWarehouseQuantity> Required

ProductWarehouseQuantity

Name Type Required/Optional Description
ProductId long Required
InventoryLocationId string Required The ID of the warehouse.
PhysicalInventory decimal Required The target quantity.

Sample request body

{
    "quantities": [
        {
            "ProductId": 123456,
            "InventoryLocationId": "{WarehouseId}",
            "PhysicalInventory": 100
        }
    ]
}

Sample response body

{
    "SuccessfulUpdates": [
        {
            "ProductId": 123456,
            "ItemId": "0001",
            "DataAreaId": "{DataAreaId}",
            "ColorId": "",
            "SizeId": "",
            "StyleId": "",
            "ConfigurationId": "",
            "InventoryLocationId": "{WarehouseId}",
            "InventorySiteId": "{SiteId}",
            "TotalAvailable": 100.0,
            "PhysicalAvailable": 100.0,
            "PhysicalInventory": 100.0,
            "PhysicalReserved": 0,
            "OrderedInTotal": 0
        }
    ],
    "FailedUpdates": [],
    "ExtensionProperties": []
}

The quantity output of APIs

The GetEstimatedAvailability and GetEstimatedProductWarehouseAvailability APIs fetch inventory data from two data sources:

  • When you turn on the Use Inventory Visibility as inventory data provider setting in Commerce shared parameters in headquarters, the APIs retrieve inventory availability data from the Inventory Visibility Service (IVS) you configured for your Commerce headquarters environment.
  • When you turn off the Use Inventory Visibility as inventory data provider setting in Commerce shared parameters in headquarters, the APIs retrieve inventory availability data from the Commerce Scale Unit (CSU) channel databases where estimated physical available and total available quantities are calculated.

The returned values can be shown on your e-commerce site, or they can be used to trigger other business logic on your e-commerce site. For example, you can prevent the purchase of products that have an "out of stock" inventory level.

Other APIs that are available in Commerce can also directly access Commerce headquarters to fetch on-hand quantities for products. However, don't use them in an e-commerce environment because of potential performance issues and the impact that such frequent requests can have on your Commerce headquarters servers. For channel-side calculation, the GetEstimatedAvailability and GetEstimatedProductWarehouseAvailability APIs provide a more accurate estimate of a product's availability by considering the transactions that are created in the channels but that aren't yet known to Commerce headquarters.

To define how product quantity returns in the API output, follow these steps:

  1. Go to Retail and Commerce > Headquarters setup > Parameters > Commerce parameters.

  2. On the Inventory tab, on the Inventory availability APIs for e-Commerce FastTab, in the Quantity in API output field, select one of the following options:

    • Return inventory quantity – The API output returns the physical available and total available quantities of a requested product.
    • Return inventory quantity subtracting inventory buffer – The API output quantity is adjusted by subtracting the inventory buffer value. For more information about the inventory buffer, see Configure inventory buffers and inventory levels.
    • Not return inventory quantity – The API output returns only the inventory level. For more information about inventory levels, see Configure inventory buffers and inventory levels.

  3. Run the 1070 (Channel configuration) job to sync the latest setting to channels.

  • Last updated on