swagger: '2.0'
info:
version: 1.0.0
title: Toast Authentication Payments API
description: 'The authentication API returns an authentication token that you can present
when your integration client software uses other Toast APIs. For more
information about authentication, see [the Toast Developer
Guide](https://doc.toasttab.com/doc/devguide/authentication.html).
'
termsOfService: https://pos.toasttab.com/api-terms-of-use
contact:
name: Toast developer support
host: toast-api-server
basePath: /authentication/v1
schemes:
- https
consumes:
- application/json
produces:
- application/json
tags:
- name: Payments
description: 'Related to guests'' payments for restaurant orders. Toast platform
payments apply to a check in an order.
'
paths:
/payments:
get:
tags:
- Payments
summary: Toast Get Payment Identifiers
description: 'Returns a list of the GUIDs for each payment made during
one restaurant business day.
The specific hours that make up a business
day depend on the business day cutoff in the restaurant configuration,
which is available from the restaurants API in the `closeoutHour`
property.
The business day for a restaurant is based on its local time (not UTC
or local time for an API client).
You must include one of the
`paidBusinessDate`, `refundBusinessDate`, or `voidBusinessDate` query
parameters.
'
operationId: paymentsGet
produces:
- application/json
parameters:
- name: Toast-Restaurant-External-ID
description: The GUID of the restaurant used as the context of the request.
in: header
required: true
type: string
- name: paidBusinessDate
description: 'Returns a list of the payments that were made during
one business day.
Specify the business day in the format yyyyMMdd.
For example, `20170101`.
'
in: query
required: false
type: string
- name: refundBusinessDate
description: 'Returns a list of the payments that were refunded
during one business day.
Specify the business day in the format
yyyyMMdd. For example, `20170101`.
'
in: query
required: false
type: string
- name: voidBusinessDate
description: 'Returns a list of the payments that were voided during
one business day.
Specify the business day in the format yyyyMMdd.
For example, `20170101`.
'
in: query
required: false
type: string
responses:
'200':
description: A JSON array of the GUID identifiers for the payments.
schema:
title: Response
type: array
items:
type: string
'400':
description: The API cannot process the request.
security:
- oauth2:
- orders:read
/payments/{guid}:
get:
tags:
- Payments
summary: Toast Get a Payment
description: Returns a JSON `Payment` object containing detailed information about a single payment, specified by its GUID.
operationId: paymentsGuidGet
produces:
- application/json
parameters:
- name: Toast-Restaurant-External-ID
description: The GUID of the restaurant used as the context of the request.
in: header
required: true
type: string
- name: guid
description: The GUID for the payment you want to return.
in: path
type: string
required: true
responses:
'200':
description: Returns a JSON `Payment` object.
schema:
$ref: '#/definitions/Payment'
'400':
description: The GUID was malformed.
'404':
description: The specified payment was not found.
security:
- oauth2:
- orders:read
/orders/{orderGuid}/checks/{checkGuid}/payments:
post:
tags:
- Payments
summary: Toast Post Payments
description: 'Adds one or more payments to a check in an existing order. Include
information about the payments in an array of `Payment` objects in the
message body. Specify the Toast platform GUID of the order
and check in REST path parameters.
For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiAddingPaymentsToACheck.html).
'
operationId: ordersChecksPaymentsPost
produces:
- application/json
parameters:
- name: orderGuid
description: 'The Toast platform identifier of the order that you are
adding payments to.
'
in: path
required: true
type: string
- name: checkGuid
description: 'The Toast platform identifier of the check that you are
adding payments to.
'
in: path
required: true
type: string
- name: body
description: 'An array of JSON `Payment` objects containing information about the payments you are adding.
'
in: body
required: true
schema:
type: array
items:
$ref: '#/definitions/Payment'
responses:
'200':
description: 'A JSON `Order` object that includes the payments that you added.
'
schema:
$ref: '#/definitions/Order'
'400':
description: The API cannot process the request.
security:
- oauth2:
- orders.payments:write
/orders/{orderGuid}/checks/{checkGuid}/payments/{paymentGuid}:
patch:
tags:
- Payments
summary: Toast Update a Tip Amount
description: 'Updates the tip amount in an existing payment for a check in an
order. Include the new `tipAmount` value in a `Payment` object
in the message body.
This endpoint does not allow any other
`Payment` object value for a `PATCH` request.
Specify the Toast
platform GUID of the order, check, and payment in REST path
parameters.
For more information, see [the _Toast Developer Guide_](https://doc.toasttab.com/doc/devguide/apiUpdatingTipsInAPayment.html).
'
operationId: ordersOrderGuidChecksCheckGuidPaymentsPaymentGuidPatch
produces:
- application/json
parameters:
- name: orderGuid
description: 'The Toast platform identifier of the order that you are
updating a tip in.
'
in: path
required: true
type: string
- name: checkGuid
description: 'The Toast platform identifier of the check that you are
updating a tip in.
'
in: path
required: true
type: string
- name: paymentGuid
description: 'The Toast platform identifier of the payment that you are
updating a tip in.
'
in: path
required: true
type: string
- name: body
description: 'A JSON `Payment` object
containing the `tipAmount` value that will replace any
existing tip amount for the payment.
Do not include any
value other than `tipAmount`.
'
in: body
required: true
schema:
$ref: '#/definitions/UpdatePaymentRequest'
responses:
'200':
description: 'A JSON `Order` object
that includes the tip amount that you updated.
'
schema:
$ref: '#/definitions/Order'
'400':
description: The API cannot process the request.
security:
- oauth2:
- orders.payments:write
definitions:
RefundTransaction:
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.
'
AppliedPackagingInfo:
type: object
description: 'Information describing the guest''s packaging preferences for this order, for example utensils, napkins, condiments.
For more information, see [Packaging preferences](https://doc.toasttab.com/doc/devguide/apiOrdersPackagingPreferences.html)
'
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
appliedPackagingItems:
type: array
minItems: 1
items:
$ref: '#/definitions/AppliedPackagingItem'
UpdatePaymentRequest:
type: object
description: 'A wrapper object containing payment fields that you can update.
'
properties:
tipAmount:
description: 'The amount tipped on a payment.
'
type: number
format: double
example: 3.25
AppliedDiscountTrigger:
type: object
description: The Selection that triggered the application of this discount
properties:
selection:
$ref: '#/definitions/ExternalReference'
quantity:
type: number
format: double
description: The amount of the selection used to trigger the applied discount.
Refund:
type: object
description: A currency amount removed from a guest payment.
properties:
refundAmount:
type: number
format: double
description: The amount of the refund, excluding the tip.
tipRefundAmount:
type: number
format: double
description: The amount of the tip refund.
refundDate:
description: The date and time when the refund was made.
type: string
format: date-time
refundBusinessDate:
x-toast-read-only: true
description: The business date (yyyyMMdd) on which this refund was created. Response only.
type: integer
refundTransaction:
description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.
'
type: object
$ref: '#/definitions/RefundTransaction'
RefundDetails:
type: object
description: 'Information about refunded currency amounts for an item
selection, modifier option, or service charge. The refund
information includes separate values for the pre-tax value
being refunded and the tax amount being refunded.
'
properties:
refundAmount:
description: 'The value of the menu item or service charge (excluding taxes) being
refunded. Includes the value of any nested modifier options that
increased the price of the item or modifier option (an upcharge for
the modifier option).
'
type: number
format: double
taxRefundAmount:
description: 'The tax amount being refunded.
'
type: number
format: double
refundTransaction:
description: 'An identifier for the refund transaction. You can use the identifier to associate items and service charges that were refunded in the same transaction.
'
type: object
$ref: '#/definitions/RefundTransaction'
AppliedServiceCharge:
type: object
description: 'A service charge that is added to a check. A service charge can represent an upcharge such as a gratuity or a delivery fee.
Whether the upcharge is taxable is defined in the restaurant-configured `serviceCharge`.
The fields on the `AppliedServiceCharge` are calculated based on the referenced `ServiceCharge` configuration.
'
allOf:
- $ref: '#/definitions/ExternalReference'
- type: object
required:
- serviceCharge
properties:
chargeAmount:
type: number
format: double
description: The final applied amount excluding tax. Required if `chargeType` is `OPEN`.
serviceCharge:
description: A reference to the restaurant-configured service charge. If a service charge is taxable, the tax amount is applied to the check.
$ref: '#/definitions/ExternalReference'
chargeType:
x-toast-read-only: true
description: 'The type of service charge. Response only.
Valid values:
* `FIXED` - The service charge is for a specific currency amount.
* `PERCENT` - The service charge is for a percentage of the check amount.
* `OPEN` - The service charge is not configured with an amount. The amount is specified by the restaurant employee.
'
type: string
enum:
- FIXED
- PERCENT
- OPEN
name:
x-toast-read-only: true
description: The configured human readable label for the service charge. Response only.
type: string
delivery:
x-toast-read-only: true
description: Whether this service charge is a delivery charge. Response only.
type: boolean
takeout:
x-toast-read-only: true
description: Whether this service charge is a takeout charge. Response only.
type: boolean
dineIn:
x-toast-read-only: true
description: Whether this service charge is a dine-in charge. Response only.
type: boolean
gratuity:
x-toast-read-only: true
description: Whether this service charge is a gratuity. Can be used to derive required tip amount on the check. Response only.
type: boolean
taxable:
x-toast-read-only: true
description: Whether this service charge is taxable. Response only.
type: boolean
appliedTaxes:
type: array
description: Taxes applied to the service charge.
items:
$ref: '#/definitions/AppliedTaxRate'
serviceChargeCalculation:
type: string
description: 'Defines whether a `PERCENT` service charge is applied before (`PRE_DISCOUNT`) or after (`POST_DISCOUNT`) discounts.
This field is `null` for `FIXED` and `OPEN` service charges.
'
enum:
- PRE_DISCOUNT
- POST_DISCOUNT
refundDetails:
description: 'A `RefundDetails` object that
contains information about refunded payment amounts for the item.
'
type: object
$ref: '#/definitions/RefundDetails'
serviceChargeCategory:
x-toast-read-only: true
description: 'The type of service charge. Default is `SERVICE_CHARGE`. Response only.
Valid values:
* `SERVICE_CHARGE` - The default type for a service charge.
* `CREDIT_CARD_SURCHARGE` - A fee assessed _only_ on payment transactions that use a credit card.
* `FUNDRAISING_CAMPAIGN` - Service charge associated with fundraising.
* `CASH_ROUNDING` - Adjustment to the check total to account for cash payments with minimum denominations greater than 0.01.
'
type: string
enum:
- SERVICE_CHARGE
- CREDIT_CARD_SURCHARGE
- FUNDRAISING_CAMPAIGN
- CASH_ROUNDING
paymentGuid:
x-toast-read-only: true
description: The Toast platform unique identifier for the payment the fee is linked to. The `paymentGuid` value is always `null` unless the `serviceChargeCategory` object value is `CREDIT_CARD_SURCHARGE` or `CASH_ROUNDING`. Response only.
type: string
AppliedLoyaltyInfo:
type: object
description: Information about the customer loyalty program account associated with a check.
required:
- loyaltyIdentifier
- vendor
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
loyaltyIdentifier:
type: string
description: An identifier for the loyalty program account. For `POST` orders, this identifier is transmitted to the loyalty program service provider to associate the check with the loyalty account.
maskedLoyaltyIdentifier:
type: string
description: 'A representation of the identifier of the loyalty program
account that can be displayed securely. For example:
`************1234`. The Toast POS displays this string to
restaurant employees and guests.
You can optionally include this
value when you `POST` an order. It is
available in response data when you `GET` the order.
If you do not provide a `maskedLoyaltyIdentifier` when you
`POST` an order, this value is `null` in response data.
The Toast POS app displays a masked representation of the
`loyaltyIdentifier`. All characters except the last four
are hidden.
'
vendor:
type: string
description: The specific loyalty program service provider that supports the loyalty account.
enum:
- TOAST
- PUNCHH
- PUNCHH2
- PAYTRONIX
- APPFRONT
- INTEGRATION
accrualFamilyGuid:
x-toast-read-only: true
type: string
description: 'Response only. An internal Toast platform identifier for loyalty
program transactions.
This is not returned from the initial
`POST` order request and is available at a later time.
'
accrualText:
x-toast-read-only: true
type: string
description: 'Response only. A description of the loyalty program transaction
to print on the customer''s receipt. For example,
"Earned 27 points."
The maximum length of the description string
is 255 characters.
This is not returned from the initial
`POST` order request and is available at a later time.
'
Device:
type: object
description: 'The *Device ID* value that the Toast platform assigns to a specific Toast POS device.
The `id` value is a unique identifier for a device.
To find the ID for a Toast POS device, from the overflow menu (⋮) select *Device Status* and then select the *Device* tab.
'
properties:
id:
type: string
description: The physical id of the device
Selection:
type: object
description: 'A `Selection` object can represent either a primary item (for example,
`Check.selections`) or a modifier (`Selection.modifiers`) selection.
Quantity defaults to `1`.
For a `POST` operation, all selections must have valid `item` and
`itemGroup` fields. The `item` and `itemGroup` values can be `null` for
`GET` requests. For example, they are `null` for gift cards and on special
requests.
To specify a modifier selection, add it to the `modifiers` list of
another selection. Each modifier selection must have its `optionGroup` field
set correctly, because a `MenuItem` can be included in multiple
`MenuOptionGroups`, potentially with different prices or sizing.
The `externalId` value for a selection must be unique. If you submit a
selection with an `externalId` that already exists for another selection,
the request will fail. You can use this behavior to implement idempotent
selection submission by always providing a consistent `externalId` for
each unique selection attempt.
'
allOf:
- $ref: '#/definitions/ExternalReference'
- type: object
required:
- item
- quantity
properties:
item:
type: object
description: A reference to the selected menu item.
$ref: '#/definitions/ConfigReference'
itemGroup:
type: object
description: A reference to the menu group from which the item was selected.
$ref: '#/definitions/ConfigReference'
optionGroup:
type: object
description: A reference to the modifier group from which the menu item was selected. Only applies if this is a modifier selection.
$ref: '#/definitions/ConfigReference'
preModifier:
type: object
description: A reference to the selected pre-modifier.
$ref: '#/definitions/ConfigReference'
quantity:
type: number
format: double
description: Quantity ordered. For items sold by weight, a decimal number. For discrete items, a counting number.
seatNumber:
x-toast-read-only: true
type: integer
description: "Indicates which guest seat at a restaurant table ordered\na menu item selection. Restaurant employees can choose the\nseat number when they add a menu item to a guest check.\n\n* A positive integer value indicates the seat number for\n the menu item.\n\n* `0` - Indicates that the menu item is shared by\n multiple guests.\n\n* `-1` - Indicates that the restaurant employee did not\n select a seat for the menu item.\n\nResponse only.\n"
unitOfMeasure:
type: string
description: 'The unit of measure used to weigh, determine size, or otherwise
quantify the item.
The default is `NONE`, which means that the item is not meant to
be measured during a sale.
Values are:
* `NONE` - The item is not meant to be measured.
* `LB` - Weighed in pounds.
* `OZ` - Weighed in ounces.
* `KG` - Weighed in kilograms.
* `G` - Weighed in grams.
* `GAL` - Measured in gallons.
* `L` - Measured in liters.
* `ML` - Measured in milliliters.
* `FL_OZ` - Measured in fluid ounces.
* `M` - Measured in meters.
* `CM` - Measured in centimeters.
* `FT` - Measured in feet.
* `IN` - Measured in inches.
* `YD` - Measured in yards.
'
enum:
- NONE
- LB
- OZ
- KG
- G
- GAL
- L
- ML
- FL_OZ
- M
- CM
- FT
- IN
- YD
selectionType:
type: string
description: 'Specifies whether this selection is a special request or other off-menu sale.
If `null` or `NONE`, describes a normal modifier or item selection.
`TOAST_CARD_SELL` and `TOAST_CARD_RELOAD` are currently response-only.
'
enum:
- NONE
- OPEN_ITEM
- SPECIAL_REQUEST
- PORTION
- HOUSE_ACCOUNT_PAY_BALANCE
- TOAST_CARD_SELL
- TOAST_CARD_RELOAD
salesCategory:
x-toast-read-only: true
type: object
description: A reference to the sales category of the item. Response only.
$ref: '#/definitions/ConfigReference'
appliedDiscounts:
x-toast-read-only: true
type: array
description: The itemized discounts that are applied to this item. Response only.
minItems: 0
items:
$ref: '#/definitions/AppliedDiscount'
deferred:
type: boolean
description: Whether this selection is a deferred revenue transaction, such as a gift card sale.
preDiscountPrice:
x-toast-read-only: true
type: number
description: Gross sale price for this selection. Excludes tax. Response only.
format: double
price:
x-toast-read-only: true
type: number
format: double
description: Net price for this selection. The final price of the item after considering discounts (including discounts at the check level), quantity adjustments, and modifier prices at the time the item was selected for purchase. Response only.
tax:
x-toast-read-only: true
type: number
format: double
description: The total tax amount for this selection. Response only.
voided:
x-toast-read-only: true
type: boolean
description: Set to `true` if this selection is voided. Response only.
voidDate:
x-toast-read-only: true
type: string
format: date-time
description: The date on which this selection was voided. Response only.
voidBusinessDate:
x-toast-read-only: true
type: integer
description: The business date (yyyyMMdd) on which this selection was voided. Response only.
voidReason:
x-toast-read-only: true
type: object
description: If `voided` is `true`, a reference to the void reason. Response only.
$ref: '#/definitions/ExternalReference'
refundDetails:
description: 'A `RefundDetails` object that
contains information about refunded payment amounts for the item.
'
type: object
$ref: '#/definitions/RefundDetails'
displayName:
type: string
description: 'The display name of the selection.
Can be used to set a special request value.
Otherwise, it is generated from this selection''s item property.
'
plu:
x-toast-read-only: true
type: string
description: The price look-up (PLU) code for the menu item selection used for pricing and inventory management.
premodifierPlu:
x-toast-read-only: true
type: string
description: The Price Look-Up (PLU) code for the premodifier associated with this menu item selection. This is a unique identifier used for pricing and inventory management purposes. Currently this field is read only.
createdDate:
type: string
format: date-time
description: The date on which this selection was created. If not specified, defaults to the current time.
modifiedDate:
type: string
format: date-time
description: The date on which this selection was last modified. If not specified, defaults to the current time.
modifiers:
type: array
description: A list of modifiers that apply to this selection.
items:
$ref: '#/definitions/Selection'
fulfillmentStatus:
x-toast-read-only: true
type: string
default: NEW
description: "Indicates the stage of the preparation workflow that the\nmenu item selection is in.\n\nThe `fulfillmentStatus` of a\nmenu item selection changes as restaurant employees move\nthe item through the functions of the Toast POS, for\nexample order entry and the kitchen display system (KDS).\nResponse only.\n\nValid values:\n\n* `NEW` - The menu item selection was added to a\n check but is not yet sent to the KDS for\n preparation.\n\n* `HOLD` - A restaurant employee paused the menu\n item selection so that it does not appear in the\n KDS for preparation.\n\n* `SENT` - The menu item selection was fired and\n appears in the KDS for preparation.\n\n* `READY` - Preparation is complete. The menu item\n selection is fulfilled and no longer appears in\n the KDS. If your restaurant does not use the Toast platform\n KDS, then order items do not reach the `READY`\n status.\n"
enum:
- NEW
- HOLD
- SENT
- READY
fulfillment:
x-toast-read-only: true
type: object
description: 'Information about the fulfillment requirements for this menu item selection. Response only.
'
$ref: '#/definitions/Fulfillment'
taxInclusion:
type: string
description: "Indicates whether the menu item price includes one or more tax\namounts. If the menu item is a modifier for another menu item\nselection, it always inherits the tax inclusion behavior of the menu\nitem that it applies to.\n\nValid values:\n* `INCLUDED` - The menu item price includes one or more tax amounts.\n* `NOT_INCLUDED` - The menu item price does not include any tax\n amounts.\n* `INHERITED` - The menu item is a modifier for another menu item\n selection in the check. The `taxInclusion` value of the parent menu\n item selection applies to the modifier. If a menu item selection\n *that is not a modifier* inherits tax inclusion behavior from a\n menu or menu group, the `taxInclusion` value is either\n `INCLUDED` or `NOT_INCLUDED`.\n"
enum:
- INCLUDED
- NOT_INCLUDED
- INHERITED
appliedTaxes:
x-toast-read-only: true
type: array
description: An array of `AppliedTaxRate` objects that contain information about tax payments made for the selection. Response only.
items:
$ref: '#/definitions/AppliedTaxRate'
diningOption:
x-toast-read-only: true
description: 'A reference to the setting or method that a restaurant uses to fulfill orders. For example, dine-in, takeout, or delivery might be dining options.
Restaurants configure the dining options that they fulfill orders in.
Response only.
'
type: object
$ref: '#/definitions/ExternalReference'
openPriceAmount:
description: 'A non-negative currency amount that sets the price of a
menu item that is configured to use the *Open Price*
pricing strategy. If you do not supply an
`openPriceAmount` value for an open price menu item, the
orders API sets the price to 0.00.
If a menu item is configured to use tax-inclusive
pricing, the orders API calculates the base price and tax
amount based on the open price that you specify. _The
open-price amount includes both the base-price and
inclusive tax amount._
`POST` only. The `openPriceAmount` value is not
present in orders API return data. It is used to
populate `receiptLinePrice`.
'
type: number
format: double
receiptLinePrice:
type: number
format: double
description: "The price of the menu item selection without any quantity, taxes, \ndiscounts, and modifier adjustments. If the menu item has taxes included, the `receiptLinePrice` value shows the original price, including taxes.\n\nFor example, if the menu item selection is for two orders of fries, \n`receiptLinePrice` is the price of one order of fries. If a menu item selection \nis for three large drinks, receiptLinePrice is the price of one large drink.\n\nPopulated based on the menu configuration, or using the value provided in \n`externalPriceAmount` or `openPriceAmount`.\n"
optionGroupPricingMode:
type: string
description: Information about how the modifier group affects the pricing of its parent item.
enum:
- INCLUDED
- FIXED_PRICE
- ADJUSTS_PRICE
- REPLACES_PRICE
- LOCATION_SPECIFIC_PRICE
externalPriceAmount:
description: 'The menu item price that was calculated by the
marketplace facilitator organization that created the
order.
`POST` only. The orders API does not include the
`externalPriceAmount` value in return data. It is
used to populate `receiptLinePrice`.
**Note**: you can only include this information if your
Toast API client is associated with a designated
marketplace facilitator organization. Most Toast API
clients do not create marketplace facilitator orders.
'
type: number
format: double
splitOrigin:
description: 'Reserved for future use.
'
type: object
$ref: '#/definitions/ExternalReference'
AppliedTaxRate:
type: object
description: A tax rate that is applied to an item or service charge.
required:
- taxRate
allOf:
- $ref: '#/definitions/ToastReference'
- type: object
properties:
entityType:
description: The type
# --- truncated at 32 KB (85 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/toast/refs/heads/main/openapi/toast-payments-api-openapi.yml