Inventory Visibility on-hand change schedules and ATP

This article describes how to set up the On-hand change schedule feature to schedule future on-hand changes and calculate available-to-promise (ATP) quantities. ATP is the quantity of an item that's available and can be promised to a customer in the next period. Use of this calculation can greatly increase your order fulfillment capability.

For many manufacturers, retailers, or sellers, it isn't enough just to know what's currently on hand. They must have full visibility into future availability. This future availability should consider future supply, future demand, and ATP.

The ATP calculated measure is a predefined calculated measure that's typically used to find the on-hand quantity that's currently available. The supply quantity is the sum of quantities for those physical measures that have a modifier type of addition, and the demand quantity is the sum of quantities for those physical measures that have a modifier type of subtraction.

You can add multiple calculated measures to calculate multiple ATP quantities. However, the total number of distinct physical measures across all ATP calculated measures should be less than nine.

For example, you set up the following calculated measure:

On-hand-available = (PhysicalInvent + OnHand + Unrestricted + QualityInspection + Inbound) – (ReservPhysical + SoftReservePhysical + Outbound)

The sum (PhysicalInvent + OnHand + Unrestricted + QualityInspection + Inbound) represents supply, and the sum (ReservPhysical + SoftReservePhysical + Outbound) represents demand. Therefore, the calculated measure can be understood in the following way:

On-hand-available = Supply – Demand

You can add another calculated measure to calculate the On-hand-physical ATP quantity.

On-hand-physical = (PhysicalInvent + OnHand + Unrestricted + QualityInspection + Inbound) – (Outbound)

There are eight distinct physical measures across those two ATP calculated measures: PhysicalInvent, OnHand, Unrestricted, QualityInspection, Inbound, ReservPhysical, SoftReservePhysical, and Outbound.

For more information about calculated measures, see Calculated measures.

This section applies when you're using Inventory Visibility UI version 2.

Before you can use ATP, you must set up one or more calculated measures to calculate the ATP quantities. You must also turn on the feature and configure ATP settings in Microsoft Power Apps.

Follow these steps to turn on the On-hand change schedule feature in Power Apps and configure the ATP settings.

1. Sign in to Power Apps, and open the Inventory Visibility app.

2. On the navigation pane, select Feature management.

3. On the Available to promise tile, select Manage.

4. Set the Enable feature option to True to turn on the ATP feature.

5. Set the Max schedule period (days) field to the number of days that users can view and submit scheduled on-hand changes. Users who query for stock information will get the on-hand quantity, scheduled on-hand changes, and ATP for each day in the defined period, starting from the current date. The maximum value for this field is 180 days. By default, it's set to 30 days. Therefore, you can schedule changes for up to 30 days from today.

   Important

   The schedule period includes the current date. Therefore, users can schedule on-hand changes to occur any time from the current date (the day when the change is submitted) through (schedule period – 1) days in the future.

6. In the Schedule Measures section, set up schedule measures. You can use existing calculated measures as schedule measures, or you can create new ones. When you query Inventory Visibility, the ATP value is provided for defined calculated measures, based on the scheduled changes of component physical measures. In the Schedule Measures section, select New OnHand Change Schedule Configuration V2 on the toolbar to add a new calculated measure binding for ATP. The calculated measure is what you want to use to find the currently available on-hand quantity. For information about how to create a calculated measure, see Calculated measures.

   Important

   The default ATP calculated formula is for reference. You can modify and add other data sources and physical measures to set up the correct ATP calculation for your business.

7. In the ATP Index Set Configuration section, set up your ATP index. The ATP index resembles the product index hierarchy that lets you group query results by specific dimensions. For example, if you set ColorId and SizeId as your ATP index set, query results will be grouped by color and size. You can have multiple index sets.

   Important

   The default ColorId and SizeId index is for reference. You can remove dimensions and add other dimensions.

8. Select Save.

9. When you've finished configuring all the required settings, select Update Configuration under Admin Settings on the navigation pane.

Learn more in Complete and update the configuration.

An on-hand change schedule establishes expected dates and quantities of scheduled on-hand changes. You can submit an on-hand change schedule to Inventory Visibility, provided that the dates are within the period that's defined by the Schedule period setting (see the Enable and set up the features section of this article). Users who query for stock information will get the on-hand quantity, scheduled on-hand changes, and ATP for each day in that period.

Scheduled changes are initially uncommitted and therefore don't affect your actual on-hand quantities in the system. To commit the changes, you must submit an on-hand change event, which updates the actual available on-hand quantity. You must then revert the scheduled change by submitting an on-hand change schedule for a matching negative quantity.

For example, you place an order for 10 bikes and expect it to arrive tomorrow. Therefore, you submit an on-hand change schedule that has an inbound quantity of 10 and is dated for tomorrow. When the order arrives the next day, you add the bikes to your physical on-hand inventory. You must then commit the change to your system to update the actual on-hand quantity. To commit the change, you submit an on-hand change event that has an inbound quantity of 10. You then revert the scheduled change by submitting an on-hand change schedule that has an inbound quantity of -10.

When you query Inventory Visibility for on-hand and ATP quantities, it returns the following information for each day in the schedule period:

• Date – The date that the result applies to. The time zone is Coordinated Universal Time (UTC).
• On-hand quantity – The actual on-hand quantity for the specified date. This calculation is made according to the ATP calculated measure that's configured for Inventory Visibility.
• Scheduled supply – The sum of all scheduled inbound quantities that haven't become physically available for immediate consumption or shipment as of the specified date.
• Scheduled demand – The sum of all scheduled outbound quantities that haven't been consumed or shipped as of the specified date.
• ATP quantity – The minimum projected on-hand quantity that's available from the specified date through the end of the schedule period. This quantity includes all scheduled quantity adjustments. It's the maximum quantity that can be promised on the current date for delivery or consumption on that day.

For example, if the current date is February 1, 2022, and the schedule period is 7, users can submit scheduled on-hand changes that are expected to occur from February 1 through February 7, 2022. In this case, the ATP quantity for February 3, for example, is calculated based on the on-hand quantity for that day and the scheduled quantities from February 3 through February 7.

The following example shows how a series of scheduled quantity changes affects the on-hand and ATP quantities that Inventory Visibility reports. It also shows how to commit a scheduled change, how a committed schedule change affects the results, and what can occur if you don't commit a scheduled change.

The results in this example show a projected on-hand value. This value incorporates all scheduled updates for illustration purposes but isn't actually reported when you query Inventory Visibility.

1. The following settings are configured for your system on the ATP setting page of the Inventory Visibility app in Power Apps:

   • Schedule measures – A calculated measure that's named On-hand is added here. It's calculated as On-hand = Supply – Demand.
   • Max schedule period (days) – The value is set to 7.
   • ATP index set configuration – ColorId and SizeId are added here.

2. The following conditions also apply:

   • The current date is February 1, 2022.
   • The current on-hand quantity is 20.

3. For the current date (February 1, 2022), you submit a scheduled demand quantity of 3 to Inventory Visibility. Therefore, the projected on-hand quantity is 17. The following table shows the result.

   Expand table

   Date	On-hand	Scheduled supply	Scheduled demand	Projected on-hand	ATP
   2022-02-01	20		3	17	17
   2022-02-02	20			17	17
   2022-02-03	20			17	17
   2022-02-04	20			17	17
   2022-02-05	20			17	17
   2022-02-06	20			17	17
   2022-02-07	20			17	17

4. On the current date (February 1, 2022), you submit a scheduled supply quantity of 10 for February 3, 2022. The following table shows the result.

   Expand table

   Date	On-hand	Scheduled supply	Scheduled demand	Projected on-hand	ATP
   2022-02-01	20		3	17	17
   2022-02-02	20			17	17
   2022-02-03	20	10		27	27
   2022-02-04	20			27	27
   2022-02-05	20			27	27
   2022-02-06	20			27	27
   2022-02-07	20			27	27

5. On the current date (February 1, 2022), you submit the following scheduled quantity changes:

   • Demand quantity of 15 for February 4, 2022
   • Supply quantity of 1 for February 5, 2022
   • Supply quantity of 3 for February 6, 2022

   The following table shows the result.

   Expand table

   Date	On-hand	Scheduled supply	Scheduled demand	Projected on-hand	ATP
   2022-02-01	20		3	17	12
   2022-02-02	20			17	12
   2022-02-03	20	10		27	12
   2022-02-04	20		15	12	12
   2022-02-05	20	1		13	13
   2022-02-06	20	3		16	16
   2022-02-07	20			16	16

6. On the current date (February 1, 2022), you ship the scheduled demand quantity of 3. Therefore, you must commit this change so that it's reflected in your actual on-hand quantity. To commit the change, you submit an on-hand change event that has an outbound quantity of 3. You then revert the scheduled change by submitting an on-hand change schedule that has an outbound quantity of -3. The following table shows the result.

   Expand table

   Date	On-hand	Scheduled supply	Scheduled demand	Projected on-hand	ATP
   2022-02-01	17		0	17	12
   2022-02-02	17			17	12
   2022-02-03	17	10		27	12
   2022-02-04	17		15	12	12
   2022-02-05	17	1		13	13
   2022-02-06	17	3		16	16
   2022-02-07	17			16	16

7. On the next day (February 2, 2022), the schedule period shifts forward by one day. The following table shows the result.

   Expand table

   Date	On-hand	Scheduled supply	Scheduled demand	Projected on-hand	ATP
   2022-02-02	17			17	12
   2022-02-03	17	10		27	12
   2022-02-04	17		15	12	12
   2022-02-05	17	1		13	13
   2022-02-06	17	3		16	16
   2022-02-07	17			16	16
   2022-02-08	17			16	16

8. However, two days later (February 4, 2022), the supply quantity of 10 that was scheduled for February 3 still hasn't arrived. The following table shows the result.

   Expand table

   Date	On-hand	Scheduled supply	Scheduled demand	Projected on-hand	ATP
   2022-02-04	17		15	2	2
   2022-02-05	17	1		3	3
   2022-02-06	17	3		6	6
   2022-02-07	17			6	6
   2022-02-08	17			6	6
   2022-02-09	17			6	6
   2022-02-10	17			6	6

   As you see, the scheduled (but not committed) on-hand changes don't affect the actual on-hand quantity.

You can use the following application programming interface (API) URLs to submit on-hand change schedules, change events, and queries.

Learn more in Inventory Visibility public APIs.

An on-hand change schedule is created by submitting a POST request to the relevant Inventory Visibility service URL. You can also submit bulk requests.

An on-hand change schedule can be created only if the scheduled date is between the current date and the end of the current schedule period. The datetime format should be year-month-day (for example, 2022-02-01). The time format must be accurate only to the day.

This API creates a single on-hand change schedule.

Path:
    /api/environment/{environmentId}/onhand/changeschedule
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        id: string,
        organizationId: string,
        productId: string,
        dimensionDataSource: string, # optional
        dimensions: {
            [key:string]: string,
        },
        quantitiesByDate: {
            [datetime:datetime]: {
                [dataSourceName:string]: {
                    [key:string]: number,
                },
            },
        },
    }

The following example shows sample body content without dimensionDataSource.

{
    "id": "id-bike-0001",
    "organizationId": "usmf",
    "productId": "Bike",
    "dimensions": {
        "SiteId": "1",
        "LocationId": "11",
        "ColorId": "Red",
        "SizeId": "Small"
    },
    "quantitiesByDate": {
        "2022-02-01": {
            "pos": {
                "inbound": 10
            }
        }
    }
}

This API can create multiple records at the same time. The only differences between this API and the single-event API are the Path and Body values. For this API, Body provides an array of records. The maximum number of records is 512. Therefore, the on-hand change schedule bulk API can support up to 512 scheduled changes at a time.

Path:
    /api/environment/{environmentId}/onhand/changeschedule/bulk
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    [
        {
            id: string,
            organizationId: string,
            productId: string,
            dimensionDataSource: string,
            dimensions: {
                [key:string]: string,
            },
            quantityDataSource: string, # optional
            quantitiesByDate: {
                [datetime:datetime]: {
                    [dataSourceName:string]: {
                        [key:string]: number,
                    },
                },
            },
        },
        ...
    ]

The following example shows sample body content.

[
    {
        "id": "id-bike-0001",
        "organizationId": "usmf",
        "productId": "Bike",
        "dimensions": {
            "SiteId": "1",
            "LocationId": "11",
            "ColorId": "Red",
            "SizeId": "Small"
        },
        "quantitiesByDate": {
            "2022-02-01": {
                "pos": {
                    "inbound": 10
                }
            }
        }
    },
    {
        "id": "id-car-0002",
        "organizationId": "usmf",
        "productId": "Car",
        "dimensions": {
            "SiteId": "1",
            "LocationId": "11",
            "ColorId": "Red",
            "SizeId": "Small"
        },
        "quantitiesByDate": {
            "2022-02-05": {
                "pos": {
                    "outbound": 10
                }
            }
        }
    }
]

On-hand change events are made by submitting a POST request to the relevant Inventory Visibility service URL (see the start of the Submit change schedules, change events, and ATP queries through the API section).

The following example shows a request body that contains a single on-hand change event.

{
    "id": "id-bike-0001",
    "organizationId": "usmf",
    "productId": "Bike",
    "dimensions": {
        "SiteId": "1",
        "LocationId": "11",
        "SizeId": "Big",
        "ColorId": "Red"
    },
    "quantities": {
        "pos": {
            "inbound": 10.0
        }
    }
}

You can query scheduled on-hand changes and ATP results by submitting either a POST request or a GET request to the appropriate API URL (see the Submit change schedules, change events, and ATP queries through the API section).

In your request, set QueryATP to true if you want to query scheduled on-hand changes and ATP results. By default, the query returns all ATP-related data from today. You can specify ATPFromDate and ATPToDate to narrow the results. (The "to" and "from" dates just filter the result. They don't affect how ATP is calculated.) The value of the groupByValues parameter must exactly match one of your ATP index sets.

• If you're submitting the request by using the GET method, set these parameters in the URL.
• If you're submitting the request by using the POST method, set these parameters in the request body.

Path:
    /api/environment/{environmentId}/onhand/indexquery
Method:
    Post
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Body:
    {
        dimensionDataSource: string, # Optional
        filters: {
            organizationId: string[],
            productId: string[],
            siteId: string[],
            locationId: string[],
            [dimensionKey:string]: string[],
        },
        groupByValues: string[],
        returnNegative: boolean,
    }

The following example shows how to create an index query request body that can be submitted to Inventory Visibility by using the POST method.

{
    // OnHand Index Query fields
    "filters": {
        "organizationId": ["usmf"],
        "productId": ["Bike"],
        "SiteId": ["1"],
        "LocationId": ["11"]
    },
    "groupByValues": ["ColorId", "SizeId"],
    "returnNegative": true,

    // ATP related fields
    "QueryATP":true,
    "ATPFromDate": "2022-02-01",
    "ATPToDate": "2022-02-10",
}

Path:
    /api/environment/{environmentId}/onhand
Method:
    Get
Headers:
    Api-Version="1.0"
    Authorization="Bearer $access_token"
ContentType:
    application/json
Query(Url Parameters):
    groupBy
    returnNegative
    [Filters]

The following example shows how to create an index query request URL as a GET request.

https://inventoryservice.{RegionShortName}-il301.gateway.prod.island.powerapps.com/api/environment/{EnvironmentId}/onhand?organizationId=usmf&productId=Bike&SiteId=1&LocationId=11&groupBy=ColorId,SizeId&returnNegative=true&QueryATP=true&ATPToDate=2022-02-01&ATPToDate=2022-02-10

The result of this GET request is exactly the same as the result of the POST request in the previous example.

To set up an exact query, add ATP-related fields to the query body. Learn more in Exact query by using the post method.

{
    // Exact query fields
    // ...

    // ATP related fields
    "QueryATP":true,
    "ATPFromDate": "2022-02-01",
    "ATPToDate": "2022-02-10",
}

Any of the previous query examples might produce the following reply. For this example, the system is configured with the following settings:

• ATP calculated measure: iv.onhand = pos.inbound – pos.outbound
• Schedule period: 7

Here's an example of the reply body.

[
    {
        "quantitiesByDate": {
            "2022-02-02T00:00:00": {
                "pos": {
                    "outbound": 5,
                    "inbound": 0,
                },
                "iv": {
                    "onhand": -5,
                },
            },
            "2022-02-06T00:00:00": {
                "pos": {
                    "inbound": 7,
                    "outbound": 0,
                },
                "iv": {
                    "onhand": 7,
                },
            }
        },
        "atpQuantities": {
            "2022-02-01T00:00:00Z": {
                "iv": {
                    "onhand": 5.0
                }
            },
            "2022-02-02T00:00:00Z": {
                "iv": {
                    "onhand": 5.0
                }
            },
            "2022-02-03T00:00:00Z": {
                "iv": {
                    "onhand": 5.0
                }
            },
            "2022-02-04T00:00:00Z": {
                "iv": {
                    "onhand": 5.0
                }
            },
            "2022-02-05T00:00:00Z": {
                "iv": {
                    "onhand": 5.0
                }
            },
            "2022-02-06T00:00:00Z": {
                "iv": {
                    "onhand": 12.0
                }
            },
            "2022-02-07T00:00:00Z": {
                "iv": {
                    "onhand": 12.0
                }
            }
        },
        "productId": "Bike ",
        "dimensions": {
            "ColorId": "Red",
            "SizeId": "Big",
            "siteid": "1",
            "locationid": "11"
        },
        "quantities": {
            "pos": {
                "inbound": 10.0,
                "outbound": 0,
            },
            "iv": {
                "onhand": 10.0,
            }
        }
    }
]