A Tab is analogous to a ticket. Typically a Tab is opened and then one or more orders of Items are added to it. The tab is eventually closed by zeroing out the balance due.
A Tab is analogous to a ticket. Typically a Tab is opened and then one or more orders of Items are added to it.
The tab is eventually closed by zeroing out the balance due, either by providing one or more payments, or by refunding/voiding items.
The Tab’s spot represents a physical location, such as a seat at a table in a restaurant or a delivery address, that the order will be sent to. If the spot allows scheduling, which is typical of takeout and delivery orders, then the order can be scheduled for delivery to that spot at a future date. Otherwise the delivery time will be set to ASAP.
The spot also can affect what items can be ordered. For example, a spot at the bar may serve alcoholic beverages whereas a spot on the patio does not. In most cases the spot should be determined before items are selected.
The guest is represented by a unique identifier such as their phoneNumber or a customerId.
It is recommended that the guest identifier be provided as the guest, through their inclusion in certain segments, may affect the final price of the order. e.g. by having a first time buyer, employee, or military discount.
A Catalog Item is resolved from a product that already exists in the GoTab product catalog, identified by its productUuid (or other product identifiers). Pricing, tax, and other attributes are inherited from the catalog.
An Open Item is an ad-hoc item not tied to the catalog. It requires a name and a unitPrice since there is no catalog entry to resolve those values from.
Both item types support modifiers, itemUnits, and quantity.
⚠️ Quantity rule: To order multiple units of the same product, set quantity on a single item object. Do not add separate objects with the same productId — duplicate entries cause an error.
Open items are useful when you need to charge for something that isn’t in the catalog — such as a custom service charge, a special event item, or a one-off product.
Field
Type
Required
Notes
name
string
✅
Display name (3–20 chars), visible on receipt and KDS
quantity
number
✅
Minimum: 1
unitPrice
integer
✅
Price in cents (min: 1, max: 100000)
modifiers
array
—
A list of modifier groups and their selected options
externalId
string
—
Your external reference for this item
itemUnits
string
—
Unit label shown on receipt, e.g. "oz", "lbs", "bottles"
taxRate
number
—
Decimal tax rate (min: 0, max: 1). e.g. 0.085 for 8.5%
The notes field accepts a JSON object and is available on both open items and catalog items. Use it to attach integration-specific metadata that your system needs to associate with the item — for example, an external order ID or a loyalty reference. The field is returned as-is on the item node in GraphQL queries.
Both catalog and open items support modifiers. A modifier represents a guest’s selection within an option group — for example, choosing a size, a temperature, or a set of toppings.
Field
Type
Notes
optionGroupHash
string
The hash identifying the option group
options
array
One or more options selected from the group
options[].optionHash
string
The hash identifying the specific option
options[].quantity
number
Quantity of that option selected
"modifiers": [
{
"optionGroupHash": "{optionGroupHash}",
"options": [
{
"optionHash": "{optionHash}",
"quantity": 1
}
]
}
]
💡 A single item can have multiple modifier groups. Each group can also have multiple options selected — for example, a “Toppings” group where the guest picks several items at once. See Example 3 for a full illustration.
First ensure that a spot and time are selected. From there, customers will select products from one or more menus.
Menu and products are dynamic in GoTab based on various reasons (e.g. rules and segments) for a location. If your application is displaying menus/products/items, prior to creating a new tab your application should be querying their availability. This best practice will ensure a guest is not viewing a menu or product that is not available for order and prevent errors at checkout.
Rules and segments that can impact an order are guest segments (e.g. VIP, first time buyer, beer club member, etc.).
Products or items may be disabled or 86’d throughout the day, and some restaurants may disable their online or takeout ordering temporarily for various reasons.
Send a POST request to /api/loc/:location_uuid/tabs to create a tab at the location.
📘 Use Price Check
You do not need to include any discount or fee items, but you do need to ensure that the payment sufficiently covers the balance. Use the price check route when creating and closing a tab all at once.
A customer must be associated with a tab — therefore a customerId or a phoneNumber is required when creating the tab.
Parameter
Developer Notes
"phoneNumber": "+19999999999"
Required if customerId not supplied
"customerId": ""
Required if phoneNumber not supplied
⚠️ Do not include fees and discounts if you retrieved them from the price check route.
Currently, the API only supports CLOSED tabs. openTab must be set to false.
When openTab: false — the tab is created and closed immediately. There must be at least one item and the payments must bring the balance due to 0, or an error will be thrown. A spotUuid is also required, as it fires the order to the correct KDS.
When openTab: true — the tab is created as an open tab and items can be added to it later via Add Items to Tab.
Depending on how your application is taking orders, you may need to display a pick-up time or delivery time to the customer. Make sure you are allowing orders to be placed within the available schedules. By default, scheduled is set to ASAP. Additional notes are optional but it is also important to query specific menu requirements set up by the operator — for example, with takeout/pickup orders the customer may be required to provide the make and/or model of their car.
"scheduled": "2022-01-31",
"spotUuid": "string", // Required when openTab is false
"notes": "Make it quick!"// (Optional) Notes on the order
The following examples cover the most common integration scenarios. Each demonstrates a different use case to help you understand which approach fits your needs.
Scenario: A third-party delivery platform (e.g. DoorDash) submits a completed order with a single item and payment all in one request. This is the most common pattern for delivery integrations where the order is paid externally and just needs to be fired to the kitchen immediately.
{
"externalId": "GoTab Test 1",
"openTab": false,
"spotUuid": "spt_Rem6_xbjGabsHhAWWdTBdIiL",
"phoneNumber": "1233455678",
"items": [
{
"externalId": "9876",
"quantity": 4,
"productUuid": "prd_utucyIkdVyqOwgK4o2KKY819",
"modifiers": []
}
],
"payments": [
{
"payAmount": 6180,
"tipAmount": 800,
"externalId": "3PD transactionId",
"methods": [
{
"amount": 6980,
"processor": "DOORDASH"
}
]
}
]
}
💡 payAmount + tipAmount must equal the amount on each payment method. In this example: 6180 + 800 = 6980.
Example 2: Open Tab with a Single Item and Modifier
Scenario: A tableside or kiosk ordering flow where the guest is still seated and may continue ordering. The tab is opened immediately with one item and a modifier selection (e.g. choosing a size or add-on). Additional items can be added later via the Add Items to Tab endpoint.
Scenario: A more complex dine-in order where multiple items are added at once, and some items have multiple modifier groups (e.g. a burger with both a “doneness” group and a “toppings” group). This demonstrates that a single item can belong to multiple modifier groups, and each group can have multiple options selected simultaneously.
Scenario: A pre-order or catering workflow where the guest is ordering in advance for a future date — such as a next-day pickup or an event. The fiscalDate must be between 1 and 90 days in the future. Scheduled tabs must be open tabs.
💡 Items can be empty at creation and added later once the operator confirms availability for that date. Use the Add Items to Tab endpoint to add items to the scheduled tab.
Example 5: Open Tab with Adjustments (Discounts / Surcharges)
Scenario: Applying a tab-level adjustment at order creation — such as a family discount, a catering surcharge, or a promotional credit. The value is in cents; use a negative value for discounts and a positive value for surcharges.
💡 tabAdjustments are applied at the tab level, not per item. For item-level discounts, those should be handled via product pricing rules or segments configured in GoTab.
