The sections below describe how to use the Toast orders API
/split endpoint to split checks. When a check is split, a new
check is created within the same order, and the specified items are moved
from the original check to the new one.
To split a check using the /split endpoint, ensure
the following conditions are met:
-
Your API client must have the
orders.channel:writeandorders.check-split:executescopes. -
The check has not yet been paid. A check with an existing payment cannot be split.
-
The check does not contain any check-level discounts. Item-level discounts are supported and will move with the corresponding item.
-
The order is not voided or deleted.
-
Third-party integrations or applications must be configured to prevent splitting when payments or check-level discounts are present.
The following procedure outlines the flow to split a check.
-
An order is created by an employee or by a tableside application using a POST request to the
/ordersendpoint. -
When a check split is initiated, send a POST request to the
/v2/orders/{orderGuid}/checks/{checkGuid}/splitendpoint before any payment is applied to the check. -
The request body must contain a JSON object specifying which items (selections) and, if applicable, service charges to move to the new check. Modifiers are moved automatically with their parent item.
-
The orders API returns the full order object, which includes the new check containing the moved items.
|
Note |
|
A check can be split more than once. As long as there are items that can be split to a new check, there is no limit to the number of times you can split a check. |
Use the /payments endpoint to post payments and
update the tip for each payment using the PATCH /payments
endpoint. For more information about using the /payments
endpoint, see the
payments reference documentations.
For more information about the orders API, see the orders API reference documentation.
The request body specifies which items to split off by indicating
the GUID of the item you want to split from the original check, and its
quantity. The example below shows all that you should POST to the
/split endpoint.
{
"selectionIds": {
"3e4fa917-5772-4c92-a1ad-045a9df9ddb3": "1"
}
}
The orders API returns the complete Order object. The checks array will contain the original check, with the items removed, and the new check with the items split from the original check.
{
"guid": "1555173e-38de-4484-8a0e-10608fc953c0",
"entityType": "Order",
"openedDate": "2025-11-04T18:50:07.820+0000",
"totalAmount": 24.87,
"checks": [
{
"guid": "428be523-b4d2-4cf2-9d28-c15934a994a7",
"entityType": "Check",
},
]
[content omitted]
"selections": [
{
"guid": "797bd731-154f-4e4b-bc3c-3032a8574854",
"entityType": "MenuItemSelection",
[content omitted]
}
{
"guid": "f4004c20-ac0b-4c80-97c2-ea448f5238ea",
"entityType": "Check",
},
]
[content omitted]
"selections": [
{
"guid": "92ea40ab-4939-4133-87a7-0ab33994390d",
"entityType": "MenuItemSelection",
}
]
}
The following sections describe the logic and behavior for splitting checks.
-
Fixed and open service charges are split 50/50, regardless of the number of items moved to the new check. For example, moving one of ten items to a new check will still result in 50% of the flat service charge cost being applied to the new check.
-
Percent service charges are copied to each new check, and the Toast platform recalculates the service charge cost based on the new check value.
-
When an item with an item-level discount is moved to a new split check, the Toast platform verifies the discount is still valid and re-applies it. This results in a new discount GUID.
-
Check-level discounts are not supported when splitting a check. These discounts can be applied by an employee on the POS after the split is complete.
Splitting a check with loyalty is not supported.
If a guest wishes to apply their loyalty account to accrue or pay with points, they can do so with the help of an employee.
Tax penny rounding may cause the combined total of the checks to change slightly after a split. For example, if you have an order whose total is $20.567 before rounding, and you split the check into two checks, the new amount for each check is $10.2835 which rounds to $10.28. Then, if you add these two checks up, their total would be $20.56, which is one penny less than the original single check.
The following limitations apply when using the /split
endpoint:
-
No partial quantities: You cannot split a single item by quantity, such as half an appetizer. Only whole number quantities can be split.
-
No even splits: You cannot split a check evenly, for example, "down the middle," and can only split a check by items. Even splits should be handled by attaching multiple payments to a single check via the POST
/paymentsendpoint. -
No merging checks via API: You cannot merge checks. This action can be performed by an employee on the POS.
-
Cannot empty original check: At least one item must remain on the original check. All items cannot be moved to a new check.
-
Single request split: Each split operation is a separate API request. Splitting into three or more checks requires multiple sequential API calls.
-
Check-level discounts: Splitting a check with an existing check-level discount is not supported. Check-level discounts must be applied by an employee after the split is complete.
-
Combo item splitting: Items within a combo cannot be split onto separate checks.
-
Loyalty integration: Splitting a check with loyalty applied is not supported.
-
No split indication: The Toast check object does not include a flag or indicator that the check was split when a check is split using a third-party application.
The table below describes the different errors you may see when
submitting an order to the Toast orders API /split
endpoint.
For more information about Toast API error responses, see API responses and errors
| Error code | Error message |
|---|---|
| 23300 | Cannot move all items from check. At least one item must remain on the original check. |
| 23301 | Cannot split check with check-level discounts. Remove discounts before splitting. |
| 23302 | Split check operations require non-zero whole number quantities. Quantity % is not supported. |
| 23303 | Splitting a voided or deleted check is not supported. |