Lesa á ensku Breyta

Deila með

Inventory availability APIs for e-commerce

  • Grein

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.

Athugasemd

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. As a prerequisite to using this API, you must first enable IVS as the inventory data provider for your Commerce environment. The UpdateProductWarehouseAvailabilities API operates under the BusinessPartnerEmployee role, which is used 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 can fetch inventory data from two data sources:

  • When the Use Inventory Visibility as inventory data provider setting is turned on in Commerce shared parameters in headquarters, the inventory availability data is retrieved from the IVS you configured for your Commerce headquarters environment.
  • When the Use Inventory Visibility as inventory data provider setting is turned off in Commerce shared parameters in headquarters, the inventory availability data is retrieved 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, we don't recommend that you 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 can provide a more accurate estimate of a product's availability by considering the transactions that have been created in the channels but that aren't yet known to Commerce headquarters.

To define how product quantity should be returned 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 physical available and total available quantities of a requested product are returned in the API output.
    • Return inventory quantity subtracting inventory buffer – The quantity that's returned in the API output 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 – Only the inventory level is returned in the API output. 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.