Business Intelligence API Guide

Understanding Combo Meal Sales

Note:

Ensure that the Business Intelligence API account is created and assigned to the desired organizational level with required data access permissions. See Obtain Account Information.
This use case requires the API account to have the Sales and Operations data access permission.
The cURL command examples use the URL structure https://rest_server_url/resource-path, where rest_server_url is the server you use to log in to Reporting and Analytics. See Send Requests.
All APIs need a valid OAuth token for your API account. See Authenticate.

Getting Combo Meal Transaction Details

The sample guest check below shows a transaction with combo item sales.

This image shows a check example with several combo items including the two burger combos and one beer combo.

This check contains the following combo items:

Line Number	Combo Meal	Side 1	Side 2
1	Burger Combo
2		Fries
3			Beer
4	Burger Combo
5		Nachos
6			Juice
7	Beer Combo
8		Nachos

The getGuestChecks API for this check is shown below. Fields that are not relevant to this use case have been left out of the example in order to concentrate on the combo meal use case.

Request Body

curl -i -X POST -H "Authorization: Bearer
	 " -H "Content-Type:application/json" -d {"locRef":"1234","clsdBusDt":"2021-10-04"} https://baseurl/bi/v1/orgidentifier/getGuestChecks

Example of Response Body

{
	"guestChecks": [
		{
			"guestCheckId": 1201304,
			"chkNum": 150,
			[.....]
			"taxes": [....],
			"detailLines": [
				{
					"guestCheckLineItemId": 10851590,
					"lineNum": 1,
					"dtlId": 5,
					"parDtlId": null,
					[....]
					"dspTtl": 11.5,
					"dspQty": 1,
					"aggTtl": 11.5,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 503,
						"comboMealSeq": 3,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				{
					"guestCheckLineItemId": 10851591,
					"lineNum": 2,
					"dtlId": 6,
					"parDtlId": 5,
					[....]
					"dspTtl": 0,
					"dspQty": 1,
					"aggTtl": null,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 504,
						"comboMealSeq": 3,
						"comboGrpNum": 102,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				{
					"guestCheckLineItemId": 10851593,
					"lineNum": 3,
					"dtlId": 7,
					"parDtlId": 5,
					[....]
					"dspTtl": 0,
					"dspQty": 1,
					"aggTtl": null,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 501,
						"comboMealSeq": 3,
						"comboSideSeq": 1,
						"comboGrpNum": 103,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				{
					"guestCheckLineItemId": 10851592,
					"lineNum": 4,
					"dtlId": 8,
					"parDtlId": null,
					[....]
					"dspTtl": 11.5,
					"dspQty": 1,
					"aggTtl": 11.5,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 503,
						"comboMealSeq": 4,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}	
				},
				{
					"guestCheckLineItemId": 10851594,
					"lineNum": 5,
					"dtlId": 9,
					"parDtlId": 8,
					[....]
					"dspTtl": 0,
					"dspQty": 1,
					"aggTtl": null,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 502,
						"comboMealSeq": 4,
						"comboGrpNum": 102,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				{
					"guestCheckLineItemId": 10851595,
					"lineNum": 6,
					"dtlId": 10,
					"parDtlId": 8,
					[....]
					"dspTtl": 0,
					"dspQty": 1,
					"aggTtl": null,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 510,
						"comboMealSeq": 4,
						"comboSideSeq": 1,
						"comboGrpNum": 103,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				{
					"guestCheckLineItemId": 10851597,
					"lineNum": 7,
					"dtlId": 11,
					"parDtlId": null,
					[....]
					"dspTtl": 4,
					"dspQty": 1,
					"aggTtl": 4,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 509,
						"comboMealSeq": 7,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				{
					"guestCheckLineItemId": 10851596,
					"lineNum": 8,
					"dtlId": 12,
					"parDtlId": 11,
					[....]
					"dspTtl": 0,
					"dspQty": 1,
					"aggTtl": null,
					"aggQty": 1,
					[....]
					"menuItem": {
						"miNum": 502,
						"comboMealSeq": 7,
						"comboGrpNum": 102,
						"returnFlag": false,
						"activeTaxes": "1",
						"prcLvl": 1
					}
				},
				[.. other line items....]
			]
		},
	]
}

To identify the different combo meals in a getGuestChecks API response, each combo meal and its components must have a unique comboMealSeq. The check API response above contains three unique comboMealSeq which are 3, 4, and 7. They represent the three combo meals included in the transaction. All detailLines with the same comboMealSeq belong to the same combo meal.

For each combo meal, you can identify the primary menu item and the component menu items with help of the comboGrpNum attribute. The primary menu item does not return the comboGrpNum attribute, whereas the components do return the comboGrpNum attribute. This can also be verified by comparing the parDtlId of the components which all have the same value as the dtlId of the primary menu item of the combo meal.

The table below demonstrates this check's API response.

lineNum	dtlId	parDtlld	miNum	comboMealSeq	comboGrpNum	Interpretation
1	5	null	503	3	null	Primary menu item of the first combo meal (Burger Combo).
2	6	5	504	3	102	Component of the first combo meal (Fries).
3	7	5	501	3	103	Component of the first combo meal (Beer).
4	8	null	503	4	null	Primary menu item of the second combo meal (Burger Combo).
5	9	8	502	4	102	Component of the second combo meal (Nachos).
6	10	8	510	4	103	Component of the second combo meal (Juice).
7	11	null	509	7	null	Primary menu item of third combo meal (Beer Combo).
8	12	11	502	7	102	Component of the third combo meal (Nachos).

The examples below demonstrate how to get the menu item names by calling the getMenuItemDimensions API for the menu item numbers returned in the getGuestchecks API response.

curl -i -X POST -H "Authorization: Bearer
	" -H "Content-Type:application/json" -d {"locRef":"1234", "searchCriteria": "where equals(menuItems.num,501) or equals(menuItems.num,502) or equals(menuItems.num,503) or equals(menuItems.num,504) or equals(menuItems.num,509) or equals(menuItems.num,510)"} https://baseurl/bi/v1/orgidentifier/getMenuItemDimensions

Example of Response

{
	"locRef": "1234",
	"menuItems": [
		{
			"num": 503,
			"name": "Burger Combo",
			"name2": " ",
			"majGrpNum": 51,
			"majGrpName": "Food",
			"famGrpNum": 52,
			"famGrpName": "Main Course"
		},
		{
			"num": 509,
			"name": "Beer Combo",
			"name2": " ",
			"majGrpNum": 52,
			"majGrpName": "Beverages",
			"famGrpNum": 55,
			"famGrpName": "Liquor"
		},
		{
			"num": 501,
			"name": "Beer",
			"name2": " ",
			"majGrpNum": 52,
			"majGrpName": "Beverages",
			"famGrpNum": 55,
			"famGrpName": "Liquor"
		},
		{
			"num": 502,
			"name": "Nachos",
			"name2": " ",
			"majGrpNum": 51,
			"majGrpName": "FOOD",
			"famGrpNum": 51,
			"famGrpName": "Sides"
		},
		{
			"num": 510,
			"name": "Juice",
			"name2": " ",
			"majGrpNum": 52,
			"majGrpName": "Beverages",
			"famGrpNum": 56,
			"famGrpName": "Juice"
		},
		{
			"num": 504,
			"name": "Fries",
			"name2": " ",
			"majGrpNum": 51,
			"majGrpName": "FOOD",
			"famGrpNum": 51,
			famGrpName": "Sides"
		}
	]
}

Getting Daily Aggregations of Combo Meal Sales

You can also get daily aggregations of combo meal sales directly for any given date using the getComboItemDailyTotals API. The API response groups the combo meals along with their respective component sales for the given date.

Request Body

curl -i -X POST -H "Authorization: Bearer
	" -H "Content-Type:application/json" -d {"locRef":"1234","busDt":"2021-10-04"} https://baseurl/bi/v1/orgidentifier/getComboItemDailyTotals

Example of Response Body

{
	"locRef": "EU_Location",
	"busDt": "2021-10-04",
	"revenueCenters": [
		{
			"rvcNum": 26,
			"comboItems": [
				{
					"comboMiNum": 503,
					"componentMiNum": 503,
					"origMiNum": 503,
					"otNum": 1,
					"slsCnt": 2,
					"slsTtl": 23,
					"components": [
						{
							"componentMiNum": 504,
							"origMiNum": 504,
							"otNum": 1,
							"slsCnt": 1,
							"slsTtl": 0
						},
						{
							"componentMiNum": 501,
							"origMiNum": 501,
							"otNum": 1,
							"slsCnt": 1,
							"slsTtl": 0
						},
						{
							"componentMiNum": 502,
							"origMiNum": 502,
							"otNum": 1,
							"slsCnt": 1,
							"slsTtl": 0
						},
						{
							"componentMiNum": 510,
							"origMiNum": 510,
							"otNum": 1,
							"slsCnt": 1,
							"slsTtl": 0
						}
					]
				},
				{
					"comboMiNum": 509,
					"componentMiNum": 509,
					"origMiNum": 509,
					"otNum": 1,
					"slsCnt": 1,
					"slsTtl": 4,
					"components": [
						{
							"componentMiNum": 502,
							"origMiNum": 502,
							"otNum": 1,
							"slsCnt": 1,
							"slsTtl": 0
						}
					]
				}
			]
		}
	]
}

In the example response above, the aggregations are returned based on the primary menu item of the combo meal in the comboItems array whereas the corresponding component aggregations are returned in the components child array of the combo meal. The following table demonstrates this.

comboItems.comboMiNum	comboItems.componentMiNum	Combo Meal Item	Combo Meal Components
503		Burger Combo
	504		Fries
	501		Beer
	502		Nachos
	510		Juice
509		Beer Combo
	502		Nachos

Note:

The getComboItemDailyTotals API only returns the combo item and their side item sales. Any menu items that are sold a la carte, are not part of the response. Use the getMenuItemDailyTotal API to get all daily menu item sales.

Getting Real-Time Fixed Period-Based Aggregations for Combo Meals Sales

Follow these steps to perform combo meal aggregations for fixed time periods for a location.

To get the guest check transaction data with combo meals:

Get the latest business date.

Request Body

curl -i -X POST -H "Authorization: Bearer
	" -H "Content-Type:application/json" -d {"locRef":"1234"} https://baseurl/bi/v1/orgidentifier/getLatestBusinessDate

Example of Response Body

{
	"curUTC": "2020-10-20T15:15:00",
	"locRef": "1234",
	"latestBusDt": "2020-10-20"
}

Get latest guest checks containing the combo meal items for the day from up to the current time for the current business date.

Request Body

curl -i -X POST -H "Authorization: Bearer
	" -H "Content-Type:application/json" -d {"locRef":"1234","clsdBusDt":"2020-10-20", "searchCriteria":"!isNull(guestChecks.detailLines.menuItems.comboMealSeq)"} https://baseurl/bi/v1/orgidentifier/getGuestChecks

The response from step 2 contains all the guest checks that contain combo item sales for the given business date up to the current time. Aggregations can be performed as required using the response based on time intervals of clsdUTC time.

For instance, if you want to aggregate check totals for fixed periods where each fixed period is a 15 minute time interval of an hour, you need to call the getGuestChecks API for every 15 minutes using the API mentioned in step 2. See Real-Time Guest Check Transaction Data for more details on how to retrieve incremental guest check transactions in real time. Fixed period totals can be achieved by summation of guestChecks.chkTtl field for all the checks that have been closed in the respective time periods as shown in the table below. This table shows the date and time ranges for first four fixed periods for a given business date say, for example 2020-10-20.

Fixed Period	"clsdUTC" Lower Range	"clsdUTC" Upper Range
1	2020-1020T00:00:01	20202-10-20T00:15:00
2	2020-10-20T00:15:01	2020-10-20T00:30:00
3	2020-10-20T00:30:01	2020-10-20T00:45:00
4	2020-1020T00:45:01	2020-10-20T01:00:00
..	......	.......