Reconcile Guest Check Transactions Using Control Daily Totals

Data reconciliation is required to ensure that the API client has captured all the transactions that have been posted from the upstream systems. The data posted for a given date can be either for the current business date in real time or previous business dates due to delayed postings or multi-day opened checks. Therefore, it is recommended that you follow the patterns and schedules for API clients described below. This ensures data integrity and completeness.

Recommended Patterns

Dimensions

Dimension calls should be made once a day for each type, after the expected start of day per location.

• In Simphony, it is possible for an object to be created and used on the same day. For example, a menu item. In this case while pulling dimensions once per day, it is possible to get a sales record without reference. This is true for dimension types referenced in consumption of the check API calls.

• The client should be capable of creating a temporary dimension in the downstream system as needed when this circumstance occurs, as it may be relevant to any relational data storage. Creation of the temporary record by location (locRef)/Number (for example, miNum, dscNum, tmedNum) should be unique and allow for a later update on the next get dimension call to fill in the additional information. The name used temporarily in this record, if needed, is subjective for visibility in the BI System. For example, temporary-<objectNumber> so the circumstance is visible. This is a fairly edge case condition.

• For location dimensions, where the time zone is needed locally, it is best to store this information in a local map for reference and maintain a call once per day, or possibly during startup if this must be maintained in memory.

Daily Totals

Make Daily Totals calls once per day per location, following the success of the definition calls for the respective location.

Checks

Typically, checks are always moving forward on an openBusinessDate. Within a single business date, checks opened that day can be retrieved by making the initial call for the day to the getGuestChecks API without providing a changedSinceUTC value. Then, the returned currUTC field response is stored and used for all subsequent calls for that business date, both for the same day and any later call back.

The changedSinceUTC and currUTC fields are not compared to transaction time during the API call. When this time has passed in the call, it means return all checks that have been updated or created in the cloud, not the POS, since this time is in UTC. This implementation lets offline checks that are out of order to still be included with continuous delta calls, rather than needing to back up and pull a previous window of time with redundant information. Consider this as a delta or pagination indicator, rather than having any true business significance as a timestamp.

The currUTC value for the last call of the day is stored by the integration. If a change is detected to the day by calling the controlTotals API (for example, if offline transactions were posted several days later) it can be used to call the getGuestChecks API again and to pick up just those checks, regardless of the time they were created in the POS. A change to a previous business date is visible in one or more of the returned metrics, for example numClsdChecks or lastTransUTC.

The last standard call to getGuestChecks should be made after collecting definitions and daily totals at the end of the day being processed, once the change of business date has been confirmed. Confirm the change of business date via getLatestBusDt. Then, use control totals to check for changes in the previous day rather than invoking the checks API, as this is better for performance.

Multi-day Check Considerations

A multi-day check refers to a check that is opened on one business date and closed on another business date. For example, where a check is started in the drive thru prior to the date change, and paid after the date change, in two rounds. In this case, using a reasonable offset from the configured start of day time, before making the final call for the previous day's checks returns all transactions, since the checks will be finished and posted prior to extraction.

There are edge cases where checks are open for longer periods across business dates. For example, if a check is inadvertently or deliberately left open in the system. These cases are considered less critical in delivery time for BI consumption than normal transactions. It is not be necessary to call for the previous day, all closed checks on the current day, or every two hours to cover this use case. You can identify the change by invoking getControlDailyTotals after daily totals for the previous days, based upon business operations that may have been modified, to know which days to call getGuestChecks.

Recommended End of Day Schedule

Based on the recommended patterns, the following schedule is suggested in order to reconcile all definitions and transaction data for all the locations in the enterprise as part of the end of day process.

Assumptions

• The enterprise queries the latest check level detail from every store every X hours.

• Some locations, especially those that are open for 24 hours, may have checks that span two business dates.

• Checks can be reopened, adjusted, or closed on a subsequent business date.

• Simphony's start of day occurs at midnight (T) store local time.

Based upon these assumptions, the following schedule is recommended to reconcile data. Make any necessary adjustments in case the assumptions are not applicable.

1. Identify the timezone (TZ) in which your stores are to be reported operationally.

2. At 2 a.m. TZ (T+X hours), start the end of day reconciliation process as below:

   • Make getLatestBusDt call for stores in TZ to confirm business date change. If this has not changed, delay actions for the affected store based on business operations and try again.

   • Make all the Dimensions calls for stores in TZ.

   • Make Daily Totals calls for stores in TZ.

   • Make Control Daily Totals calls for business date and previous 1-14 business dates (based on business operations) for stores in TZ. The result of the getControlTotals is stored by the integration, so you can compare the current status to the following days.

   • Make getGuestChecks calls for business date and any previous business date that indicated a change in the control totals, using the relative stored locRef/businessDate/currUTC values to retrieve delta only for stores in TZ.

3. Once the end of day process is completed, begin new day for stores in TZ.

   • Make initial getGuestChecks call for new business date for stores in TZ, without providing a changedSinceUTC field value. Store the locRef/businessDate/changedSinceUTC value from the response for use in subsequent calls for the same business date.

Note:

Make sure you adjust for daylight savings time as needed.

Reconcile Guest Check Transaction Data for Current Business Date

It is recommended that you reconcile the guest checks for the current business date in case you are fetching guest checks in real time.There may be a case where new transactions are posted for a current date due to offline workstations, or transactions that changed (for example, by using the reopen closed check function).

To reconcile the guest checks for current business date:

1. Identify the business date and location reference for reconciliation.

2. Get latest guest checks for the current business date as per your real-time schedule. See Get guest checks.

3. Store the currUTC attribute in your last guest check response.

4. Get the Controls Daily Totals for the given location and business date. See Get control daily totals.

5. Compare the currUTC values from the Guest Check Response in Step 3 with the lastTransUTC of the Controls Daily Totals response in Step 4 respectively.

In case of a mismatch, you can either fetch all the guest checks for the current business date using the getGuestChecks API or only the missed checks for that business date by passing the currUTC attribute from your guest check response as the changedSinceUTC request parameter of the getGuestChecks API. See Get guest checks.

In case there are no checks returned for the given business date's guest check call, it's possible that there are transactions from previous days that might have posted in the given business date. These can be reconciled during the end of day process for previous business dates.

Reconcile Guest Checks for Previous Business Dates for Updated Transactions

The getControlDailyTotals API indicates a potential change to previous business dates, to allow a minimal touch on those days.

The lastTransUTC value in the control totals result set indicates the last transaction time on any check opened on the business date after the busDt value in this API. So if a check is modified with a new transaction on a later business date this will still pick up the change without having to separately check the closeBusinessDate.

It is recommended that the API consumer client maintains a map of location/businessDate/lastTransUTC for comparing the trailing set of modifiable totals, up to 14 days, as required by business operations. Note that lastTransUTC corresponds to the max (detailLines.detailUTC) in the getGuestChecks result set. If a more recent time is detected during the start of day check, then make an additional getGuestChecks call for the modified day, using the stored last returned changedSinceUTC for that location/date.

It is recommended that you run the getControlDailyTotals API for previous business dates (up to 1-14 days based upon your business processes) and compare with previous results of the same API to identify updated or changed transactions for past business dates. If you identify a change, it may be caused by new transactions posted for a past business date due to workstations being offline, or transactions that changed (for example, by using the reopen closed check function). In those cases you should re-pull the transactions from the impacted business date using the getGuestChecks API.

To reconcile guest checks for any previous business date:

1. Identify the business date and location for reconciliation.

2. Get the Controls Daily Totals for the location and business date. See Get control daily totals.

3. Compare the stored values of lastTransUTC from the guest check API response for that business date in your system to the lastTransUTC of the Controls Daily Totals response in Step 2 respectively.

4. In case of a mismatch, you can fetch all the guest checks for the business date using the getGuestChecks API or only the missed checks for that business date by using the last stored changedSinceUTC attribute from your last guest check response for the date as the changedSinceUTC request parameter of the getGuestChecks API. See Get guest checks.

5. Update the stored lastTransUTC for the location and date with the new value returned in the latest getControlDailyTotals API call.