{"data":{"siteConfig":{"withRbac":false},"site":{"pathPrefix":""},"apis":[{"id":"465efde6-34f0-5c36-ab2b-e242580660f8overview/__redocly content redirect/authentication/overview/","definitionId":"authentication","link":"/authentication/overview/","sourcePath":"/data/toasttab/redocly-portal-config-prerelease-promotions/authentication.reference.page.yaml","info":{"version":"1.0.0","title":"Toast authentication API","description":"The authentication API returns an authentication token that you can present\nwhen your integration client software uses other Toast APIs. For more\ninformation about authentication, see [the Toast Developer\nGuide](https://doc.toasttab.com/doc/devguide/authentication.html).\n","termsOfService":"https://pos.toasttab.com/api-terms-of-use","contact":{"name":"Toast developer support"}},"data":{"redirect":true,"type":"reference-docs","definitionId":"authentication","label":"Authentication","settings":{"generateCodeSamples":{"languages":[{"lang":"curl"},{"lang":"Java"},{"lang":"Python"}]},"showConsole":false,"hideHostname":true,"hideDownloadButton":true,"sortPropsAlphabetically":true,"schemaDefinitionsTagName":"Data definitions","hideTryItPanel":true},"apiVersions":[{"definitionId":"authentication","isDefault":true,"title":"authentication","id":"authentication"}],"isDefaultApiVersion":true,"redocStoreStr":"{\"menu\":{\"activeItemIdx\":-1},\"definition\":{\"data\":{\"openapi\":\"3.0.0\",\"info\":{\"version\":\"1.0.0\",\"title\":\"Toast authentication API\",\"description\":\"The authentication API returns an authentication token that you can present\\nwhen your integration client software uses other Toast APIs. For more\\ninformation about authentication, see [the Toast Developer\\nGuide](https://doc.toasttab.com/doc/devguide/authentication.html).\\n\",\"termsOfService\":\"https://pos.toasttab.com/api-terms-of-use\",\"contact\":{\"name\":\"Toast developer support\"}},\"tags\":[{\"name\":\"Authentication\"}],\"externalDocs\":{\"description\":\"Authentication developer guide\",\"url\":\"https://doc.toasttab.com/doc/devguide/authentication.html\"},\"paths\":{\"/authentication/login\":{\"post\":{\"tags\":[\"Authentication\"],\"summary\":\"Get an authentication token\",\"description\":\"Returns an authentication token that your Toast API client can present\\nwhen using other Toast platform APIs.\\n\",\"externalDocs\":{\"description\":\"Authentication developer guide\",\"url\":\"https://doc.toasttab.com/doc/devguide/authentication.html\"},\"operationId\":\"authenticationLoginPost\",\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/AuthenticationRequest\"}}},\"description\":\"The authentication credentials for your Toast API client integration\\nsoftware.\\n\",\"required\":true},\"responses\":{\"200\":{\"description\":\"A JSON `AuthenticationResponse` object that includes an\\nauthentication token string.\\n\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/AuthenticationResponse\"}}}},\"401\":{\"description\":\"The Toast API client credentials in your request are not valid.\\n\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}}}}}}}},\"servers\":[{\"url\":\"https://toast-api-server/authentication/v1\"}],\"components\":{\"schemas\":{\"AuthenticationRequest\":{\"type\":\"object\",\"description\":\"Authentication credentials for your Toast API integration client software.\\n\",\"properties\":{\"clientId\":{\"description\":\"The identifier string for your Toast API client. You receive the\\nidentifier string from the Toast integrations team.\\n\",\"type\":\"string\",\"example\":\"VKuhk4NaLedOcjZpJM8grvdrsFi3MlcM\"},\"clientSecret\":{\"description\":\"The secret string that corresponds to your Toast API client. You\\nreceive the secret string from the Toast integrations team.\\n\",\"type\":\"string\",\"example\":\"eS960aiKdvgbSDcLUCk68HR2CJKwwHNO2HKfgxjCWxoj27KIp6jFAi2XOOc_oCuv\"},\"userAccessType\":{\"description\":\"Always include the `userAccessType` value and set it to\\n`TOAST_MACHINE_CLIENT`.\\n\",\"type\":\"string\",\"example\":\"TOAST_MACHINE_CLIENT\"}}},\"AuthenticationResponse\":{\"type\":\"object\",\"description\":\"A wrapper object for the response to a successful Toast API authentication\\nrequest.\\n\",\"properties\":{\"token\":{\"$ref\":\"#/components/schemas/AuthenticationToken\"},\"status\":{\"description\":\"The value `SUCCESS` indicates that your authentication request was successful.\",\"type\":\"string\",\"example\":\"SUCCESS\"}}},\"AuthenticationToken\":{\"type\":\"object\",\"description\":\"Information about a Toast platform API session, including an\\nauthentication token string that your Toast API client software can\\npresent when using other Toast platform APIs.\\n\",\"properties\":{\"tokenType\":{\"description\":\"The OAuth 2 authentication scheme used for the authentication token.\\nToast API authentication uses the bearer authentication scheme.\\n\",\"type\":\"string\",\"example\":\"Bearer\"},\"scope\":{\"description\":\"The scope value in the authentication token request response is\\n`null`. The `accessToken` JSON Web Token (JWT) contains the list of\\n[scopes for your Toast API\\nclient](https://dev.toasttab.com/doc/devguide/apiScopes.html).\\n\",\"type\":\"string\"},\"expiresIn\":{\"description\":\"The number of seconds that the authentication token is valid. \\n\",\"type\":\"integer\",\"example\":86400},\"accessToken\":{\"description\":\"A JSON Web Token (JWT) string that contains an authentication token.\\nYou [present this string when you make\\nrequests](https://dev.toasttab.com/doc/devguide/authentication.html#using-authentication-token)\\nto other Toast API resources. The JWT includes information about your\\nToast API client.\\n\",\"type\":\"string\"},\"idToken\":{\"description\":\"For internal use only.\\n\",\"type\":\"string\"},\"refreshToken\":{\"description\":\"For internal use only.\\n\",\"type\":\"string\"}}},\"ErrorMessage\":{\"type\":\"object\",\"description\":\"An object that contains information about one or more errors that the\\nToast platform encountered when processing your API request.\\n\",\"properties\":{\"status\":{\"description\":\"The HTTP status code of the response.\\n\",\"type\":\"string\"},\"code\":{\"description\":\"A numeric identifier for the error condition.\\n\",\"type\":\"integer\"},\"message\":{\"description\":\"A description of the error condition.\\n\",\"type\":\"string\"},\"messageKey\":{\"description\":\"Reserved for future use.\\n\",\"type\":\"string\"},\"fieldName\":{\"description\":\"Reserved for future use.\\n\",\"type\":\"string\"},\"link\":{\"description\":\"The URL of a resource that provides more information about the error\\ncondition.\\n\",\"type\":\"string\"},\"requestId\":{\"description\":\"The unique identifier of the HTTP request that your client sent to the Toast API.\\n\",\"type\":\"string\"},\"developerMessage\":{\"description\":\"Additional detail about the error condition, if it is available.\\n\",\"type\":\"string\"},\"errors\":{\"description\":\"A JSON array of `ErrorMessage` objects.\\n\",\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/ErrorMessage\"}},\"canRetry\":{\"description\":\"Reserved for future use.\\n\",\"type\":\"string\"}}}}}}},\"options\":{\"hideTryItPanel\":true,\"pagination\":\"item\",\"generateCodeSamples\":{\"languages\":[{\"lang\":\"curl\"},{\"lang\":\"Java\"},{\"lang\":\"Python\"}]},\"showConsole\":false,\"hideHostname\":true,\"hideDownloadButton\":true,\"sortPropsAlphabetically\":true,\"schemaDefinitionsTagName\":\"Data definitions\",\"disableSearch\":true,\"ctrlFHijack\":false,\"disableSidebar\":true,\"theme\":{\"overrides\":{\"DownloadButton\":{\"custom\":\"\"},\"NextSectionButton\":{\"custom\":\"\"}},\"codeBlock\":{\"tokens\":{}},\"schema\":{\"constraints\":{},\"examples\":{}},\"rightPanel\":{\"textColor\":\"#eeeeee\"},\"typography\":{\"heading1\":{},\"heading2\":{},\"heading3\":{},\"rightPanelHeading\":{}}}}}","permission":"guest","lastModified":"2023-01-05T21:46:45.000Z","redocInfoPageId":"authentication.reference.page.yaml#overview","redocPagination":"item","redocInfoPageLink":"","redocHasInfoPage":false,"redocHasSecurityDefinitions":false,"httpVerb":null,"matchPath":"","excludeFromSearch":false,"sourcePath":"/data/toasttab/redocly-portal-config-prerelease-promotions/authentication.reference.page.yaml"},"definitionProperties":{},"permission":"guest","versions":[{"definitionId":"authentication","isDefault":true,"id":"authentication","title":"authentication","link":null}]},{"id":"fb27578b-1a4b-57f5-965f-2f35138f5ac6overview/__redocly content redirect/giftcards/overview/","definitionId":"giftCards","link":"/giftcards/overview/","sourcePath":"/data/toasttab/redocly-portal-config-prerelease-promotions/giftcards.reference.page.yaml","info":{"version":"1.0.0","title":"Gift Card Integration API","description":"A REST API that allows the Toast platform to process \ngift card transactions using a gift card provider that it does not \ncurrently support.\n","contact":{"name":"Toast developer support"}},"data":{"redirect":true,"type":"reference-docs","definitionId":"giftCards","label":"Gift cards integration specification","settings":{"generateCodeSamples":{"languages":[{"lang":"curl"},{"lang":"Java"},{"lang":"Python"}]},"showConsole":false,"hideHostname":true,"hideDownloadButton":true,"sortPropsAlphabetically":true,"schemaDefinitionsTagName":"Data definitions","hideTryItPanel":true},"apiVersions":[{"definitionId":"giftCards","isDefault":true,"title":"giftCards","id":"giftCards"}],"isDefaultApiVersion":true,"redocStoreStr":"{\"menu\":{\"activeItemIdx\":-1},\"definition\":{\"data\":{\"openapi\":\"3.0.0\",\"info\":{\"version\":\"1.0.0\",\"title\":\"Gift Card Integration API\",\"description\":\"A REST API that allows the Toast platform to process \\ngift card transactions using a gift card provider that it does not \\ncurrently support.\\n\",\"contact\":{\"name\":\"Toast developer support\"}},\"paths\":{\"/yourendpointname\":{\"post\":{\"operationId\":\"yourendpointnamePost\",\"summary\":\"Returns gift card transaction information\\n\",\"description\":\"Provides information about a gift card transaction processed by \\nthe Toast platform. The transaction information in the \\nmessage body is intended to allow a gift card provider to \\nperform corresponding operations on the gift card account, \\nmaintained by that provider.\\n\\nYou define the endpoint name for this implementation. The Toast \\nplatform makes requests to the REST path that you supply \\nduring integration setup.\\n\\nEach `POST` request to the endpoint includes a \\n`Toast-Transaction-Type` header parameter value to indicate the \\ntype of gift card transaction it represents. The possible \\ntransaction types are:\\n\\n* Activate a new gift card.\\n* Add value to an active gift card.\\n* Get the current balance of a gift card.\\n* Redeem value from a gift card, for example for a purchase.\\n* Reverse a previous transaction, for example to void a purchase \\n made with the gift card.\\n\\nThe `GiftCardTransaction` \\nobject in the message body includes a set of information that \\nis specific for each transaction type.\\n\\nThe response time for a gift card transaction request must be \\nless than 500ms.\\n\\nAll gift card transactions must be considered idempotent. The \\nimplementation must handle multiple requests with the same \\n`Toast-Transaction-GUID` *and* the same `giftCardIdentifier`.\\n\",\"parameters\":[{\"name\":\"Toast-Transaction-GUID\",\"description\":\"A unique identifier of the gift card transaction, defined \\nby the Toast platform.\\n\",\"in\":\"header\",\"schema\":{\"type\":\"string\"}},{\"name\":\"Toast-Restaurant-External-ID\",\"description\":\"The unique identifier of the restaurant, defined by the \\nToast platform.\\n\",\"in\":\"header\",\"schema\":{\"type\":\"string\"}},{\"name\":\"Toast-Transaction-Type\",\"description\":\"The type of gift card transaction that occurred. Values are:\\n\\n\",\"in\":\"header\",\"schema\":{\"type\":\"string\",\"enum\":[\"GIFTCARD_ACTIVATE\",\"GIFTCARD_ADD_VALUE\",\"GIFTCARD_GET_BALANCE\",\"GIFTCARD_REDEEM\",\"GIFTCARD_REVERSE\"]}},{\"name\":\"Authorization\",\"description\":\"a JSON Web Token (JWT) that you can use to authenticate the request. Verify the token using the public key that you get from the Toast user management service.\",\"in\":\"header\",\"schema\":{\"type\":\"string\"}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/GiftCardTransaction\"}}},\"description\":\"A `GiftCardTransaction` \\nobject containing information about the gift card \\ntransaction that the Toast platform processed.\\n\"},\"responses\":{\"200\":{\"description\":\"OK. The `transactionStatus` value of the \\n`GiftCardTransactionResponse` object is `ACCEPT`.\\n\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/GiftCardTransactionResponse\"}}}},\"400\":{\"description\":\"Bad request. The `transactionStatus` value of the \\n`GiftCardTransactionResponse` object is one of: \\n\\n* `ERROR_INVALID_TOAST_TRANSACTION_TYPE`\\n* `ERROR_CARD_ALREADY_ACTIVATED`\\n* `ERROR_CARD_NOT_ACTIVATED`\\n* `ERROR_CARD_INVALID`\\n* `ERROR_INVALID_INPUT_PROPERTIES`\\n* `ERROR_TRANSACTION_DOES_NOT_EXIST`\\n* `ERROR_INVALID_TOKEN`\\n* `ERROR_TRANSACTION_CANNOT_BE_REVERSED`\\n* `ERROR_INVALID_RESTAURANT`\\n* `ERROR_VERIFICATION_FAILED`\\n* `ERROR_VERIFICATION_REQUIRED`\\n* `ERROR_VERIFICATION_NOT_SUPPORTED`\\n\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/GiftCardTransactionResponse\"}}}},\"500\":{\"description\":\"Internal server error.\"}}}}},\"servers\":[{\"url\":\"https://toast-api-server/yourapiname/v1\"}],\"components\":{\"schemas\":{\"GiftCardTransaction\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction in the Toast \\nplatform. Gift card providers are expected to handle that \\ntransaction.\\n\\nThe set of information in this object depends on the gift card \\ntransaction type. The transaction type is specified in the \\n`Toast-Transaction-Type` header parameter for the request.\\n\\nThe `GiftCardTransaction` object includes the following values \\nfor specific transaction types:\\n\\n* `GIFTCARD_ACTIVATE` - includes an `activateTransactionInformation` value.\\n* `GIFTCARD_ADD_VALUE` - includes an `addValueTransactionInformation` value.\\n* `GIFTCARD_GET_BALANCE` - includes a `getBalanceTransactionInformation` value.\\n* `GIFTCARD_REDEEM` - includes a `redeemTransactionInformation` value.\\n* `GIFTCARD_REVERSE` - includes a `reverseTransactionInformation` value.\\n\",\"properties\":{\"activateTransactionInformation\":{\"$ref\":\"#/components/schemas/TransactionInformationActivate\"},\"addValueTransactionInformation\":{\"$ref\":\"#/components/schemas/TransactionInformationAddValue\"},\"getBalanceTransactionInformation\":{\"$ref\":\"#/components/schemas/TransactionInformationGetBalance\"},\"redeemTransactionInformation\":{\"$ref\":\"#/components/schemas/TransactionInformationRedeem\"},\"reverseTransactionInformation\":{\"$ref\":\"#/components/schemas/TransactionInformationReverse\"}}},\"TransactionInformation\":{\"type\":\"object\",\"properties\":{\"giftCardIdentifier\":{\"description\":\"The unique identifier of the gift card.\\n\",\"type\":\"string\"},\"identifierSource\":{\"description\":\"Indicates how the Toast platform received the gift card identifier string. Values are:\\n\\n* `KEYED` - A restaurant employee or guest manually entered the identifier string.\\n\\n* `SCANNED` - A restaurant employee or guest used a barcode scanner or other scanning device to enter the identifier string.\\n\\n* `SWIPED` - A restaurant employee or guest used a magnetic card strip reader to enter the identifier string.\\n\\n* `KEYED_ONLINE` - The source of this transaction is Toast Online Ordering, The provider can reject the transaction regardless of the restaurant's verification code settings.\\n\\n* `UNKNOWN` - The Toast platform received the identifier string using a method other than `KEYED`, `SCANNED`, or `SWIPED`, or the method is not known.\\n\",\"type\":\"string\",\"enum\":[\"KEYED\",\"SCANNED\",\"SWIPED\",\"KEYED_ONLINE\",\"UNKNOWN\"]},\"verificationCode\":{\"type\":\"object\",\"description\":\"The verification code, also often referred to as a PIN code, for the gift card account. A verification code is an additional layer of security that some gift card providers include.\\n\",\"properties\":{\"value\":{\"description\":\"The verification code value of the gift card.\\n\",\"type\":\"string\"},\"source\":{\"description\":\"Indicates how the Toast platform received the verification code value. This can differ from an `identifierSource` if the verification code is keyed in by a restaurant employee or guest after a swipe.\\n\\nValues are:\\n\\n* `KEYED` - A restaurant employee or guest manually entered the verification code string.\\n\\n* `SCANNED` - A restaurant employee or guest used a barcode scanner or other scanning device to enter the verification code string.\\n\\n* `SWIPED` - A restaurant employee or guest used a magnetic card strip reader to enter the verification code string. \\n\\n* `VERIFIED` - The Toast platform has previously verified the verification code for this transaction. This is commonly used in the subsequent transactions on the same order. The provider should ignore the validation.\\n\\n* `UNKNOWN` - The Toast platform received the verification code string using a method other than `KEYED`, `SCANNED`, or `SWIPED`, or the method is not known.\\n\",\"type\":\"string\",\"enum\":[\"KEYED\",\"SCANNED\",\"SWIPED\",\"VERIFIED\",\"UNKNOWN\"]}}}}},\"TransactionInformationActivate\":{\"allOf\":[{\"$ref\":\"#/components/schemas/TransactionInformation\"},{\"type\":\"object\",\"description\":\"Information about a gift card transaction in the Toast \\nplatform that activates a new card. Gift card providers are \\nexpected to handle the transaction.\\n\",\"properties\":{\"initialBalance\":{\"description\":\"The currency amount of the funds available from the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"},\"checkIdentifier\":{\"description\":\"The unique identifier of the check that this gift card transaction\\nis part of. No action needs to be taken based on this identifier,\\nit is just provided for tracking purposes.\\n\",\"type\":\"string\"}}}]},\"TransactionInformationAddValue\":{\"allOf\":[{\"$ref\":\"#/components/schemas/TransactionInformation\"},{\"type\":\"object\",\"description\":\"Information about a gift card transaction in the Toast POS \\nsystem that adds to the funds that are available on the card. \\nGift card providers are expected to handle the transaction.\\n\",\"properties\":{\"additionalValue\":{\"description\":\"The currency amount of the funds being added to the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"},\"checkIdentifier\":{\"description\":\"The unique identifier of the check that this gift card transaction\\nis part of. No action needs to be taken based on this identifier,\\nit is just provided for tracking purposes.\\n\",\"type\":\"string\"}}}]},\"TransactionInformationGetBalance\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction in the Toast \\nplatform that requests the currency value of the funds available \\nfrom the gift card. Gift card providers are expected to handle \\nthe transaction.\\n\",\"allOf\":[{\"$ref\":\"#/components/schemas/TransactionInformation\"}]},\"TransactionInformationRedeem\":{\"allOf\":[{\"$ref\":\"#/components/schemas/TransactionInformation\"},{\"type\":\"object\",\"description\":\"Information about a gift card transaction in the Toast \\nplatform that reduces the balance of funds available from the card. \\nFor example, when the gift card is used for a purchase. Gift card \\nproviders are expected to handle the transaction.\\n\",\"properties\":{\"redeemedValue\":{\"description\":\"The currency amount of the funds being redeemed from the gift \\ncard.\\n\",\"type\":\"number\",\"format\":\"double\"},\"checkIdentifier\":{\"description\":\"The unique identifier of the check that this gift card transaction\\nis part of. No action needs to be taken based on this identifier,\\nit is just provided for tracking purposes.\\n\",\"type\":\"string\"},\"isCashOut\":{\"description\":\"True if this redeem transaction is a cash out transaction,\\nfalse otherwise\\n\",\"type\":\"boolean\"},\"relatedTransaction\":{\"description\":\"The Toast platform unique identifier for a previous gift card transaction.\\nYour integration can use this identifier to confirm information about a\\nprevious, related transaction such as PIN verification. For example, if a\\nrestaurant employee adds a tip or gratuity to a transaction, the Toast POS\\nreverses the initial redemption and sends another redemption with the new\\namount. This value provides the identifier of the initial transaction. If the\\ncurrent transaction is not part of an adjustment (for example, reversing a\\ntransaction) this value is `null`.\\n\",\"type\":\"string\"}}}]},\"TransactionInformationReverse\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction in the Toast \\nplatform that undoes a previous transaction. Gift card providers \\nare expected to handle the transaction. The only types of\\ntransactions that can be reversed are `GIFTCARD_ADD_VALUE`,\\n`GIFTCARD_REDEEM`, and `GIFTCARD_ACTIVATE`.\\nIf a `GIFTCARD_ADD_VALUE` is reversed then the amount of the\\noriginal transaction should be deducted from the card's balance.\\nIf a `GIFTCARD_REDEEM` is reversed then the amount of the\\noriginal transaction should be added to the card's balance.\\nIf a `GIFTCARD_ACTIVATE` is reversed then the card should be\\nset to inactive and its balance set to `0.00`.\\n`GIFTCARD_GET_BALANCE` and `GIFTCARD_REVERSE` cannot be reversed.\\n\",\"allOf\":[{\"$ref\":\"#/components/schemas/TransactionInformation\"}],\"properties\":{\"previousTransaction\":{\"description\":\"The identifier of an earlier gift card transaction. This \\nidentifier is provided in the `Toast-Transaction-GUID` header \\nparameter.\\n\",\"type\":\"string\",\"format\":\"guid\"}}},\"GiftCardTransactionResponse\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction from the gift \\ncard provider. The Toast platform uses this information to \\ncomplete guests' gift card transactions.\\n\\nThe set of information in this object depends on the gift card \\ntransaction type. The transaction type is specified in the \\n`Toast-Transaction-Type` header parameter for the request.\\n\\nAll `GiftCardTransactionResponse` objects must include a \\n`transactionStatus` value.\\n\\nThe `GiftCardTransactionResponse` object includes the following \\nadditional values for specific transaction types:\\n\\n* `GIFTCARD_ACTIVATE` - includes an `activateResponse` value.\\n* `GIFTCARD_ADD_VALUE` - includes an `addValueResponse` value.\\n* `GIFTCARD_GET_BALANCE` - includes a `getBalanceResponse` value.\\n* `GIFTCARD_REDEEM` - includes a `redeemResponse` value.\\n* `GIFTCARD_REVERSE` - includes a `reverseResponse` value.\\n\\nFor \\nexample, the response object for a `GIFTCARD_ACTIVATE` transaction \\nincludes an `activateResponse` value.\\n\",\"properties\":{\"transactionStatus\":{\"description\":\"Indicates the result of a gift card transaction, reported by the\\ngift card service provider. Possible values are:\\n\\n\\n\",\"type\":\"string\",\"enum\":[\"ACCEPT\",\"ERROR_INVALID_TOAST_TRANSACTION_TYPE\",\"ERROR_CARD_ALREADY_ACTIVATED\",\"ERROR_CARD_NOT_ACTIVATED\",\"ERROR_CARD_INVALID\",\"ERROR_INVALID_INPUT_PROPERTIES\",\"ERROR_TRANSACTION_DOES_NOT_EXIST\",\"ERROR_INVALID_TOKEN\",\"ERROR_TRANSACTION_CANNOT_BE_REVERSED\",\"ERROR_INVALID_RESTAURANT\",\"ERROR_VERIFICATION_FAILED\",\"ERROR_VERIFICATION_REQUIRED\",\"ERROR_VERIFICATION_NOT_SUPPORTED\"]},\"activateResponse\":{\"$ref\":\"#/components/schemas/TransactionResponseActivate\"},\"addValueResponse\":{\"$ref\":\"#/components/schemas/TransactionResponseAddValue\"},\"getBalanceResponse\":{\"$ref\":\"#/components/schemas/TransactionResponseGetBalance\"},\"redeemResponse\":{\"$ref\":\"#/components/schemas/TransactionResponseRedeem\"},\"reverseResponse\":{\"$ref\":\"#/components/schemas/TransactionResponseReverse\"}}},\"TransactionResponseActivate\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction from the gift card \\nservice provider for activating a new gift card. The Toast POS \\nsystem uses this information to complete guests' gift card \\ntransactions.\\n\",\"properties\":{\"currentBalance\":{\"description\":\"The currency amount of the funds available from the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"}}},\"TransactionResponseAddValue\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction from the gift card \\nservice provider for add value transactions. The Toast platform \\nuses this information to complete guests' gift card transactions.\\n\",\"properties\":{\"currentBalance\":{\"description\":\"The currency amount of the funds available from the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"}}},\"TransactionResponseGetBalance\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction from the gift card \\nservice provider for get balance transactions. The Toast POS \\nsystem uses this information to complete guests' gift card \\ntransactions.\\n\",\"properties\":{\"currentBalance\":{\"description\":\"The currency amount of the funds available from the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"}}},\"TransactionResponseRedeem\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction from the gift card \\nservice provider that reduces the balance of funds available from \\nthe card. For example, when the gift card is used for a purchase. \\nThe Toast platform uses this information to complete guests' \\ngift card transactions.\\n\",\"properties\":{\"currentBalance\":{\"description\":\"The currency amount of the funds available from the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"},\"redeemedValue\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The currency amount of the funds that were redeemed from the \\ngift card. This value may be different than the \\n`redeemedValue` in a gift card transaction request. For \\nexample, if the card balance is less than the redeem value \\nrequested by the Toast platform, the `redeemedValue` in the \\nresponse will be less than the `redeemedValue in the request.\\n\"}}},\"TransactionResponseReverse\":{\"type\":\"object\",\"description\":\"Information about a gift card transaction from the gift card \\nservice provider that undoes a previous gift card transaction. \\nThe Toast platform uses this information to complete guests' \\ngift card transactions.\\n\",\"properties\":{\"currentBalance\":{\"description\":\"The currency amount of the funds available from the gift card.\\n\",\"type\":\"number\",\"format\":\"double\"}}}}}}},\"options\":{\"hideTryItPanel\":true,\"pagination\":\"item\",\"generateCodeSamples\":{\"languages\":[{\"lang\":\"curl\"},{\"lang\":\"Java\"},{\"lang\":\"Python\"}]},\"showConsole\":false,\"hideHostname\":true,\"hideDownloadButton\":true,\"sortPropsAlphabetically\":true,\"schemaDefinitionsTagName\":\"Data definitions\",\"disableSearch\":true,\"ctrlFHijack\":false,\"disableSidebar\":true,\"theme\":{\"overrides\":{\"DownloadButton\":{\"custom\":\"\"},\"NextSectionButton\":{\"custom\":\"\"}},\"codeBlock\":{\"tokens\":{}},\"schema\":{\"constraints\":{},\"examples\":{}},\"rightPanel\":{\"textColor\":\"#eeeeee\"},\"typography\":{\"heading1\":{},\"heading2\":{},\"heading3\":{},\"rightPanelHeading\":{}}}}}","permission":"guest","lastModified":"2022-12-22T13:56:16.000Z","redocInfoPageId":"giftcards.reference.page.yaml#overview","redocPagination":"item","redocInfoPageLink":"","redocHasInfoPage":false,"redocHasSecurityDefinitions":false,"httpVerb":null,"matchPath":"","excludeFromSearch":false,"sourcePath":"/data/toasttab/redocly-portal-config-prerelease-promotions/giftcards.reference.page.yaml"},"definitionProperties":{},"permission":"guest","versions":[{"definitionId":"giftCards","isDefault":true,"id":"giftCards","title":"giftCards","link":null}]},{"id":"79593a32-4629-520e-a687-1e1e0c32dcc6overview/__redocly content redirect/promotions/overview/","definitionId":"promotions","link":"/promotions/overview/","sourcePath":"/data/toasttab/redocly-portal-config-prerelease-promotions/promotions.reference.page.yaml","info":{"version":"1.0.0","title":"Toast promotions integration API - draft","contact":{"name":"Toast developer support"}},"data":{"redirect":true,"type":"reference-docs","definitionId":"promotions","label":"Promotions","settings":{"generateCodeSamples":{"languages":[{"lang":"curl"},{"lang":"Java"},{"lang":"Python"}]},"showConsole":false,"hideHostname":true,"hideDownloadButton":true,"sortPropsAlphabetically":true,"schemaDefinitionsTagName":"Data definitions","hideTryItPanel":true},"apiVersions":[{"definitionId":"promotions","isDefault":true,"title":"promotions","id":"promotions"}],"isDefaultApiVersion":true,"redocStoreStr":"{\"menu\":{\"activeItemIdx\":-1},\"definition\":{\"data\":{\"openapi\":\"3.0.0\",\"info\":{\"version\":\"1.0.0\",\"title\":\"Toast promotions integration API - draft\",\"contact\":{\"name\":\"Toast developer support\"}},\"paths\":{\"/promotion\":{\"post\":{\"summary\":\"Endpoint to handle all promotion-related requests.\",\"description\":\"Takes in an optional JSON `PromotionRequest` body and performs a promotion operation defined by the specified `Toast-Transaction-Type`.\\n- PROMOTION_VERIFY:\\n Verifies whether a given promotion code is applicable to a check. Confirms that the promotion code is available for use, the check meets the criteria of the promotion, and that no other, conflicting promotions or discounts are applied.\\n

\\n Each unique `PROMOTION_VERIFY` request has a unique GUID. Providers can cache a response based on a `Toast-Transaction-GUID`.\\n

\\n If the request is valid (it is properly formatted and the promotion code can be applied), then the API returns a corresponding `PromotionObject`\\n that is applicable to the check provided in the `PromotionRequest`. This `PromotionObject` contains the proper state of the promotion,\\n including the amount to take off the check (as calculated by the provider), the name of the promotion, and the `appliedDate`. It is recommended\\n that the provider use the `appliedDate` provided by the `VerifyPromotionRequest`.\\n

\\n This operation must be idempotent, such that the same request must always get the same response (barring any separate apply/void requests).\\n The provider should reserve a promotion code based on a `PROMOTION_VERIFY` response, and may wish to use a composite key of (check.guid, restaurant-external-guid).\\n Providers should use the `Toast-Transaction-GUID` to prevent replayed requests from reserving the promotion more than once. Additionally, the `Toast-Transaction-GUID` acts\\n as an identifier for the promotion in future requests.\\n

\\n The average response time for a promotion verify request should be 500ms, with the maximum response time being 2s.\\n

\\n- PROMOTION_REVALIDATE:\\n Revalidates all `AppliedPromotions` provided on an `RevalidatePromotionsRequest` (in the `promotionsToActOn` field). This should check that all promotions in that field\\n are still applicable to the provided check, and represent the correct amount. The promotions in `promotionsToActOn` are not APPLIED.\\n

\\n If the `PROMOTION_REVALIDATE` request is valid (it is properly formatted and the promotion code can be applied), then the API returns a 200 response with\\n a list of all AppliedPromotion objects from `promotionsToActOn` with up-to-date values. If the total discount of a promotion is different than what was provided, the corresponding\\n `AppliedPromotion` response should have this new value.\\n
\\n The promotions that are not included in `promotionsToActOn` are immutable because they have been APPLIED, and can no longer be removed from the check.\\n

\\n If there are any promotions that are invalid, the API returns a 400 response with an `ErrorResponse` object. The `ErrorResponse` should contain all\\n invalid promotions. Toast will resend a request to the revalidate endpoint after removing all invalidated promotions.\\n

\\n This operation must be idempotent, such that the same request must always get the same response (barring any separate apply/void requests). If promotions are locked,\\n their unlocking time should be refreshed upon this request. If promotion locks have expired, they should acquire a new lock.\\n

\\n The average response time for a revalidate request should be 500ms, with the maximum response time being 2s.\\n

\\n- PROMOTION_APPLY:\\n Redeems all `AppliedPromotions` provided on an `ApplyPromotionsRequest` (in the `promotionsToActOn` field). If the redemption is successful, the API commits the transaction and returns a 200 response.\\n

\\n Each unique `PROMOTION_APPLY` request will have a unique GUID, which will be referenced later to verify the state of a promotion code or to void a previously\\n applied promotion code. If the request contains a `Toast-Transaction-GUID` that has already been committed or voided for a different check GUID,\\n the API provider must return a 400 response with the appropriate `ErrorResponse` object. If there are any issues applying promotions, the API provider must return a 400\\n response, and we will revalidate our existing promotions.\\n

\\n If the request is valid (it is properly formatted and the promotion code can be applied), then the API returns a list of `AppliedPromotion` objects\\n that are applicable to the check provided in the `PromotionRequest`. Each `AppliedPromotion` object contains the proper state of the promotion,\\n including the amount to be taken off the check (as calculated by the provider).\\n

\\n This operation must be considered idempotent for multiple requests with the same `Toast-Transaction-GUID` and the same check GUID, for a 24 hour period (that is, it should apply once and only once).\\n

\\n The average response time for an apply promotion request should be 500ms, with the maximum response time being 2s.\\n

\\n- PROMOTION_STATUS:\\n Responds with the `PromotionObject` or `ErrorResponse` that is associated with the provided `Toast-Transaction-GUID`, as well as the status of the redemption\\n (\\\"VERIFIED\\\", \\\"VOIDED\\\", or \\\"APPLIED\\\").\\n If the transaction GUID is not associated with a promotion that was VERIFIED, the response code is 400.\\n

\\n The average response time for a promotion status request should be 500ms, with the maximum response time being 2s.\\n

\\n- PROMOTION_VOID:\\n Voids supplied promotions from a `VoidPromotionsRequest` (in the `appliedPromotions` field).\\n This endpoint is called when the entire check is voided, or the promotion is removed from the check. This endpoint is called on\\n promotions that are verified as well as committed. If called on a non-committed promotion AND there is a lock placed on the\\n promotion, the lock should be lifted, allowing another user to potentially use the promotion code.\\n If the promotions have already been voided, then nothing should change for those.\\n

\\n This call must be idempotent for multiple requests with the same `Toast-Transaction-GUID`. The `Toast-Transaction-GUID` may be used to cache\\n a response, and to prevent a replay attack.\\n

\\n The average response time for a promotion void request should be 500ms, with the maximum response time being 2s.\\n

\\n\",\"parameters\":[{\"name\":\"Authorization\",\"description\":\"Contains configured authorization information.\\nThis should be used by the client to verify the identity of the sender\\n

\\nContains an OAuth bearer token in JWT (JSON Web Token) format.\\n

\\nSignature is to be verified by the partner with the public session verification key, available at `https://[toast-api-hostname]/usermgmt/v1/oauth/token_key`. \\nThe public session verification key can be cached by the partner, but Toast reserves the right to change the public key at any time. A refresh rate of once a day, and upon an unsuccessful validation of token, is recommended.\\n

\\nThe token contains expiry date information. Requests older than the expiry date should be ignored.\\n

\\nThe recommended Java implementation of JSON Web Token (JWT) is auth0 java-jwt.\\n

\\nThe public key is provided in RSA format. Use the RSA256 algorithm to authorize the token.\\n\",\"in\":\"header\",\"required\":true,\"schema\":{\"type\":\"string\",\"format\":\"string\"}},{\"name\":\"Toast-Transaction-GUID\",\"description\":\"The identifier of the promotion request. Based on the requestType, it is used for different functions:\\n - PROMOTION_VERIFY requests use a new, unique GUID for each request to verify if a promotion code is applicable to a check. The `Toast-Transaction-GUID` is used to identify\\n the new promotion in future requests.\\n - PROMOTION_REVALIDATE requests use a new, unique GUID for each request to verify if promotions are still applicable to a check.\\n - PROMOTION_APPLY requests use a new, unique GUID to commit promotion codes on a given check. If the same `Toast-Transaction-GUID` is used on the same check with the same promo\\n codes, it should return the same result as before, without decrementing usage of the promotion code.\\n - PROMOTION_STATUS requests, given an already used `Toast-Transaction-GUID`, will give status information for the transaction.\\n - PROMOTION_VOID requests, given a unique `Toast-Transaction-GUID`, void promotion code usages.\\n\",\"in\":\"header\",\"required\":true,\"schema\":{\"type\":\"string\"}},{\"name\":\"Toast-Restaurant-External-ID\",\"description\":\"The ID that identifies the restaurant for this configuration.\",\"in\":\"header\",\"required\":true,\"schema\":{\"type\":\"string\",\"format\":\"string\"}},{\"name\":\"Toast-Transaction-Type\",\"description\":\"The type of operation.\",\"in\":\"header\",\"required\":true,\"schema\":{\"type\":\"string\",\"format\":\"string\",\"enum\":[\"PROMOTION_VERIFY\",\"PROMOTION_REVALIDATE\",\"PROMOTION_APPLY\",\"PROMOTION_STATUS\",\"PROMOTION_VOID\"]}}],\"requestBody\":{\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/PromotionRequest\"}}},\"description\":\"A JSON `PromotionRequest` or `VerifyPromotionRequest` object\\ncontaining information about an order and promotion code. **Note:**\\n`VerifyPromotionRequest` is a subtype of `PromotionRequest`. If\\npassed during a void, to void all promotions associated with it.\\n\"},\"responses\":{\"200\":{\"description\":\"Returns a JSON `PromotionObject`\\n representing the response if this was a PROMOTION_VERIFY or PROMOTION_APPLY request.\\nReturns 200 for a successful PROMOTION_VOID request.\\npromotion codes should only be \\\"used up\\\" on a PROMOTION_APPLY request.\\n\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/PromotionObject\"}}}},\"400\":{\"description\":\"Invalid request. Returns a JSON `ErrorResponse`\\nto describe why the request was not valid.\\nReasons for an `ErrorResponse` can include a bad request (such as invalid format or missing information),\\nor if the promotion code transaction being voided has never been seen.\\n\",\"content\":{\"application/json\":{\"schema\":{\"$ref\":\"#/components/schemas/ErrorResponse\"}}}},\"401\":{\"description\":\"Not properly authorized to make this request.\"},\"500\":{\"description\":\"An unexpected internal error occurred.\"}}}}},\"servers\":[{\"url\":\"https://your-api-server/promotions/v1\"}],\"components\":{\"schemas\":{\"Check\":{\"type\":\"object\",\"description\":\"Represents a single check within an order.\",\"allOf\":[{\"$ref\":\"#/components/schemas/ExternalReference\"},{\"type\":\"object\",\"required\":[\"selections\"],\"properties\":{\"openedDate\":{\"description\":\"The date and time when this check was opened. If not specified, set to the current system time.\",\"type\":\"string\",\"format\":\"date-time\"},\"closedDate\":{\"description\":\"The most recent date and time when this check's payment status was set to CLOSED.\",\"type\":\"string\",\"format\":\"date-time\"},\"modifiedDate\":{\"description\":\"The most recent date and time when this check was modified.\",\"type\":\"string\",\"format\":\"date-time\"},\"deletedDate\":{\"description\":\"The date and time when this check was deleted. `deletedDate` is only applicable when `deleted` is true. If the check is not deleted, defaults to `1970-01-01T00:00:00.000+0000`.\",\"type\":\"string\",\"format\":\"date-time\"},\"deleted\":{\"type\":\"boolean\",\"description\":\"True if this check has been deleted.\"},\"createdDevice\":{\"$ref\":\"#/components/schemas/Device\"},\"selections\":{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/Selection\"}},\"customer\":{\"$ref\":\"#/components/schemas/Customer\"},\"appliedLoyaltyInfo\":{\"$ref\":\"#/components/schemas/AppliedLoyaltyInfo\"},\"taxExempt\":{\"type\":\"boolean\",\"default\":false,\"description\":\"True if this check is tax exempt. Tax exempt number is not yet supported.\"},\"displayNumber\":{\"type\":\"string\",\"description\":\"Generally starts at 1 each day and counts up. Toast will supply a `displayNumber` if one is not specified when POSTing. The `displayNumber` is not a unique identifier.\"},\"appliedServiceCharges\":{\"type\":\"array\",\"description\":\"Any restaurant-configured service charges that applied to this check.\",\"items\":{\"$ref\":\"#/components/schemas/AppliedServiceCharge\"}},\"amount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The subtotal amount due on this check in USD, after discounts but before tax.\"},\"taxAmount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The computed tax amount in USD. Includes service charge and item-level taxes.\"},\"totalAmount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The total amount due on this check in USD, including discounts and taxes.\"},\"payments\":{\"type\":\"array\",\"description\":\"Payments made on this check.\",\"minItems\":0,\"items\":{\"$ref\":\"#/components/schemas/Payment\"}},\"tabName\":{\"type\":\"string\",\"description\":\"The name taken by a restaurant employee to identify the order. This name appears on the KDS (Kitchen Display System) for pending orders. The `tabName` can be up to 255 characters in length.\"},\"appliedDiscounts\":{\"type\":\"array\",\"description\":\"The discounts applied to this check. In a `POST` request, only one `appliedDiscount` is allowed per check.\",\"minItems\":0,\"items\":{\"$ref\":\"#/components/schemas/AppliedDiscount\"}},\"voided\":{\"type\":\"boolean\",\"description\":\"True if this check has been voided.\"},\"voidDate\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"The date and time when this check was voided.\"},\"voidBusinessDate\":{\"type\":\"integer\",\"description\":\"The business date (yyyymmdd) on which this check was voided.\"},\"paidDate\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"The most recent date and time when this check received payment. If not specified when POSTing, set to the current system time.\"}}}]},\"Device\":{\"type\":\"object\",\"description\":\"The *Device ID* value that the Toast POS system 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, do the following. 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 menu item (that is, Check.selections) or a modifier (Selection.modifiers) selection.

All selections must have valid `item` and `itemGroup` fields. `quantity` defaults to 1.

To specify a modifier selection, add it to the `modifiers` list of another selection. For each modifier selection, its `optionGroup` field must be set correctly, because a menu item can be included in multiple menu option groups, potentially with different prices or sizing. \",\"allOf\":[{\"$ref\":\"#/components/schemas/ExternalReference\"},{\"type\":\"object\",\"required\":[\"item\",\"quantity\"],\"properties\":{\"item\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"itemGroup\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"optionGroup\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"preModifier\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"quantity\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"Quantity ordered. A decimal number for items sold by weight; a counting number for discrete items.\"},\"selectionType\":{\"type\":\"string\",\"description\":\"Specifies whether this selection is a special request or other off-menu sale. If left null or set to NONE, describes a normal modifier or item selection.\",\"enum\":[\"NONE\",\"OPEN_ITEM\",\"SPECIAL_REQUEST\",\"PORTION\"]},\"salesCategory\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"appliedDiscounts\":{\"type\":\"array\",\"description\":\"The itemized discounts applied to this item.\",\"minItems\":0,\"items\":{\"$ref\":\"#/components/schemas/AppliedDiscount\"}},\"deferred\":{\"type\":\"boolean\",\"description\":\"Defines whether this selection is a deferred revenue transaction, such as a gift card sale.\"},\"preDiscountPrice\":{\"type\":\"number\",\"description\":\"Gross sale price for this selection. Excludes tax.\",\"format\":\"double\"},\"price\":{\"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.\"},\"tax\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The total tax amount for this selection.\"},\"voided\":{\"type\":\"boolean\",\"description\":\"True if this selection has been voided.\"},\"voidDate\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"The date and time when this selection was voided.\"},\"voidBusinessDate\":{\"type\":\"integer\",\"description\":\"The business date (yyyymmdd) on which this selection was voided.\"},\"voidReason\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"displayName\":{\"type\":\"string\",\"description\":\"The display name of the selection. This field can be used to set a special request value, otherwise it will be generated from this selection's `item` property.\"},\"createdDate\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"The date and time when this selection was created. If not specified, set to the current date and time.\"},\"modifiedDate\":{\"type\":\"string\",\"format\":\"date-time\",\"description\":\"The date and time when this selection was last modified. If not specified, set to the current date and time.\"},\"modifiers\":{\"type\":\"array\",\"description\":\"A list of modifiers applying to the `item` in this `Selection`.\",\"items\":{\"$ref\":\"#/components/schemas/Selection\"}},\"fulfillmentStatus\":{\"type\":\"string\",\"default\":\"NEW\",\"description\":\"Indicates the stage of the preparation workflow that the\\nselected menu item is in. The `fulfillmentStatus` of a\\nmenu item selection changes as restaurant employees move\\nthe item through the functions of the Toast POS including \\norder entry on a device and prep station display on a KDS.\\n\\n\\n\",\"enum\":[\"NEW\",\"HOLD\",\"SENT\",\"READY\"]},\"appliedTaxes\":{\"type\":\"array\",\"description\":\"An array of `AppliedTaxRate` objects that contain information about tax payments made for the selection.\",\"items\":{\"$ref\":\"#/components/schemas/AppliedTaxRate\"}}}}]},\"Customer\":{\"type\":\"object\",\"allOf\":[{\"$ref\":\"#/components/schemas/ToastReference\"},{\"type\":\"object\",\"required\":[\"firstName\",\"lastName\",\"email\",\"phone\"],\"properties\":{\"firstName\":{\"type\":\"string\"},\"lastName\":{\"type\":\"string\"},\"phone\":{\"type\":\"string\"},\"email\":{\"type\":\"string\"}}}]},\"AppliedServiceCharge\":{\"type\":\"object\",\"description\":\"A percentage/open/fixed service charge added to a check which could, in general, represent an upcharge like a gratuity or delivery fee. Whether the upcharge is taxable is defined in the restaurant-configured `serviceCharge`. The values for the AppliedServiceCharge are computed based on the referenced `serviceCharge` configuration.\",\"allOf\":[{\"$ref\":\"#/components/schemas/ExternalReference\"},{\"type\":\"object\",\"required\":[\"serviceCharge\"],\"properties\":{\"chargeAmount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The final applied amount excluding tax. This is required if the amountType is OPEN.\"},\"serviceCharge\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"chargeType\":{\"description\":\"Derived from `serviceCharge`. An OPEN service charge can either be a dollar amount or a percentage. Response only.\",\"type\":\"string\",\"enum\":[\"FIXED\",\"PERCENT\",\"OPEN\"]},\"name\":{\"description\":\"Derived from `serviceCharge`. The configured, user-friendly label for the service charge. Response only.\",\"type\":\"string\"},\"delivery\":{\"description\":\"Derived from `serviceCharge`. Defines whether this service charge is a delivery charge.\",\"type\":\"boolean\"},\"gratuity\":{\"description\":\"Derived from `serviceCharge`. Defines whether this service charge is a gratuity. Can be used to derive a required tip amount on the check.\",\"type\":\"boolean\"},\"taxable\":{\"description\":\"Derived from `serviceCharge`. Defines whether this service charge is taxable.\",\"type\":\"boolean\"},\"appliedTaxes\":{\"type\":\"array\",\"description\":\"Derived from `serviceCharge`. Identifies the taxes applied to the service.\",\"items\":{\"$ref\":\"#/components/schemas/AppliedTaxRate\"}}}}]},\"AppliedTaxRate\":{\"type\":\"object\",\"description\":\"A tax rate applied to a menu item or service charge.\",\"discriminator\":{\"propertyName\":\"entityType\"},\"required\":[\"taxRate\"],\"allOf\":[{\"$ref\":\"#/components/schemas/ToastReference\"},{\"type\":\"object\",\"properties\":{\"entityType\":{\"description\":\"The type of object this is.\",\"type\":\"string\"},\"taxRate\":{\"$ref\":\"#/components/schemas/ToastReference\"},\"name\":{\"type\":\"string\",\"description\":\"The name of the tax rate.\"},\"rate\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The tax rate, which can be a fixed amount, a percentage, or null.\"},\"taxAmount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The tax amount that was actually applied.\"},\"type\":{\"type\":\"string\",\"description\":\"The type of the tax rate. If no tax rate is configured, defaults to PERCENT.\",\"enum\":[\"PERCENT\",\"FIXED\",\"NONE\"]}}}]},\"AppliedDiscountTrigger\":{\"type\":\"object\",\"description\":\"The menu selection that triggered the application of this discount.\",\"properties\":{\"selection\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"quantity\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The quantity ordered of the selection that triggered the applied discount.\"}}},\"AppliedDiscount\":{\"type\":\"object\",\"description\":\"A discount applied to a check or item. The Toast POS system calculates service\\ncharges before applying discounts. The system calculates tax after applying\\ndiscounts. In a `POST` request, the type of the discount must be fixed amount\\nor fixed percentage, and the discount must be applied to a check. See\\n[Applying Discounts to a Check in an Order](https://doc.toasttab.com/Ie5QH/apiApplyingDiscountsToACheck.html).\\n\",\"allOf\":[{\"$ref\":\"#/components/schemas/ToastReference\"},{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\",\"description\":\"The name of the applied discount.\"},\"discountAmount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The discount amount in USD. This amount will be subtracted from the check or item.\"},\"discount\":{\"$ref\":\"#/components/schemas/ToastReference\"},\"triggers\":{\"type\":\"array\",\"description\":\"Optional items that triggered this discount.\",\"items\":{\"$ref\":\"#/components/schemas/AppliedDiscountTrigger\"}},\"approver\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"comboItems\":{\"type\":\"array\",\"description\":\"A list of menu item selections that this discount applies to (empty for non-combo discounts).\",\"items\":{\"$ref\":\"#/components/schemas/ExternalReference\"}},\"appliedPromoCode\":{\"type\":\"string\",\"description\":\"The promotion code that was applied for this discount.\"},\"provider\":{\"type\":\"string\",\"description\":\"The provider of the discount.\"}}}]},\"AppliedLoyaltyInfo\":{\"type\":\"object\",\"description\":\"Information about the guest loyalty program account associated with a check.\",\"required\":[\"loyaltyIdentifier\",\"vendor\"],\"allOf\":[{\"$ref\":\"#/components/schemas/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.\"},\"vendor\":{\"type\":\"string\",\"description\":\"The specific loyalty program service provider that supports the loyalty account.\",\"enum\":[\"TOAST\",\"PUNCHH\",\"PUNCHH2\",\"PAYTRONIX\",\"APPFRONT\"]},\"accrualFamilyGuid\":{\"type\":\"string\",\"description\":\"Response only. An internal Toast POS identifier for loyalty program transactions. This is not returned from the initial `POST` order request, but is available at a later time.\"},\"accrualText\":{\"type\":\"string\",\"description\":\"Response only. A description of the loyalty program transaction to print on the customer's reciept. For example, \\\"Earned 27 points.\\\" The maximum length of the description is 255 characters. This is not returned from the initial `POST` order request, but is available at a later time.\"}}}]},\"Payment\":{\"type\":\"object\",\"description\":\"Defines a payment.\",\"allOf\":[{\"$ref\":\"#/components/schemas/ExternalReference\"},{\"type\":\"object\",\"required\":[\"type\",\"amount\",\"tipAmount\"],\"properties\":{\"paidDate\":{\"description\":\"The date when the payment was made.\",\"type\":\"string\",\"format\":\"date-time\"},\"paidBusinessDate\":{\"description\":\"The business date (yyyyMMdd) on which this payment was first applied. Response only.\",\"type\":\"integer\"},\"type\":{\"type\":\"string\",\"description\":\"The payment method. When POSTing, only OTHER is supported. All other types are response only. For cash payments, please create an external cash payment type in `otherPayment` options.\",\"enum\":[\"CASH\",\"CREDIT\",\"GIFTCARD\",\"HOUSE_ACCOUNT\",\"REWARDCARD\",\"LEVELUP\",\"OTHER\",\"UNDETERMINED\"]},\"cardEntryMode\":{\"type\":\"string\",\"description\":\"Indicates how credit card data was obtained. Response only.\",\"enum\":[\"SWIPED\",\"KEYED\",\"ONLINE\",\"EMV_CHIP_SIGN\",\"TOKENIZED\",\"PRE_AUTHED\",\"SAVED_CARD\",\"FUTURE_ORDER\"]},\"amount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The amount of this payment, excluding tips.\"},\"tipAmount\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The amount tipped on this payment.\"},\"amountTendered\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The amount tendered for this payment.\"},\"cardType\":{\"type\":\"string\",\"description\":\"The type of credit card used. Response only.\",\"enum\":[\"VISA\",\"MASTERCARD\",\"AMEX\",\"DISCOVER\",\"JCB\",\"DINERS\",\"CIT\",\"MAESTRO\",\"LASER\",\"SOLO\",\"UNKNOWN\"]},\"last4Digits\":{\"type\":\"string\",\"description\":\"The last 4 digits of the credit card used. Response only.\"},\"originalProcessingFee\":{\"type\":\"number\",\"format\":\"double\",\"description\":\"The original processing fee for this payment. The original processing fee value is populated after the payment has been captured. Response only.\"},\"cashDrawer\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"refundStatus\":{\"type\":\"string\",\"description\":\"Response only.\",\"enum\":[\"NONE\",\"PARTIAL\",\"FULL\"]},\"refund\":{\"$ref\":\"#/components/schemas/Refund\"},\"paymentStatus\":{\"type\":\"string\",\"description\":\"The status of this payment when the type is CREDIT. Response only.\",\"enum\":[\"OPEN\",\"PROCESSING\",\"AUTHORIZED_AT_RISK\",\"AUTHORIZED\",\"ERROR\",\"DENIED\",\"VOIDED_AT_RISK\",\"CANCELLED\",\"CAPTURE_IN_PROGRESS\",\"CAPTURED\",\"VOIDED\"]},\"voidInfo\":{\"$ref\":\"#/components/schemas/VoidInformation\"},\"houseAccount\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"otherPayment\":{\"$ref\":\"#/components/schemas/ExternalReference\"}}}]},\"Refund\":{\"type\":\"object\",\"description\":\"A discount applied to a check or item.\",\"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\":{\"description\":\"The business date (yyyyMMdd) on which this refund was created. Response only.\",\"type\":\"integer\"}}},\"VoidInformation\":{\"type\":\"object\",\"description\":\"Information about a void applied to a check or item.\",\"properties\":{\"voidUser\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"voidApprover\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"voidDate\":{\"description\":\"The date when the void took place.\",\"type\":\"string\",\"format\":\"date-time\"},\"voidBusinessDate\":{\"description\":\"The business date (yyyyMMdd) on which this void was made. Response only.\",\"type\":\"integer\"},\"voidReason\":{\"$ref\":\"#/components/schemas/ExternalReference\"}}},\"ExternalReference\":{\"type\":\"object\",\"description\":\"A wrapper object with fields that allow reference to a Toast entity by Toast GUID or a partner's identifier.\",\"discriminator\":{\"propertyName\":\"entityType\"},\"allOf\":[{\"$ref\":\"#/components/schemas/ToastReference\"},{\"type\":\"object\",\"properties\":{\"externalId\":{\"description\":\"External identifier string that is prefixed by the naming authority.\",\"type\":\"string\"}}}]},\"ToastReference\":{\"type\":\"object\",\"description\":\"A wrapper object with fields that allow reference to a Toast entity by Toast GUID.\",\"discriminator\":{\"propertyName\":\"entityType\"},\"required\":[\"guid\",\"entityType\"],\"properties\":{\"guid\":{\"description\":\"The GUID maintained by Toast.\",\"type\":\"string\"},\"entityType\":{\"description\":\"The type of object this is.\",\"type\":\"string\"}}},\"PromotionRequest\":{\"type\":\"object\",\"description\":\"A request to verify, revalidate, apply, or void a Promotion to a Check. There are three types (VERIFY, APPLY, and VOID), which have different required fields for their respective requests.

VERIFY requests contain `check`, `appliedPromotions`, `requestDateTime`, and `requestUser`.\",\"required\":[\"check\",\"appliedPromotions\",\"requestDateTime\"],\"properties\":{\"check\":{\"$ref\":\"#/components/schemas/Check\"},\"checkGuid\":{\"type\":\"string\",\"description\":\"The unique identifier of the check to which the promotions were applied.\"},\"appliedPromotions\":{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/AppliedPromotion\"},\"description\":\"A list of promotions applied on the check, linked to their AppliedDiscount. Includes metadata about promotions.\"},\"newPromotion\":{\"$ref\":\"#/components/schemas/PromotionObject\"},\"promotionsToActOn\":{\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/AppliedPromotion\"},\"description\":\"Specific promotions that a request should act on (such as void or apply all of the supplied promotions).\"},\"requestDateTime\":{\"description\":\"The date and time when this check request was made. If not specified, set to the current system time.\\n[Use ISO 8601 date and time format for all Toast APIs](https://dev.toasttab.com/Ie5QH/api_dates_and_timestamps.html).\\n\",\"type\":\"string\",\"format\":\"date-time\"},\"requestBusinessDate\":{\"description\":\"The business date (yyyyMMdd) on which this request was created.\",\"type\":\"integer\"},\"requestUser\":{\"$ref\":\"#/components/schemas/ExternalReference\"},\"orderOpenedDate\":{\"type\":\"string\",\"description\":\"The date the corresponding Order was opened.\",\"format\":\"date-time\"},\"orderOpenedBusinessDate\":{\"type\":\"integer\",\"description\":\"The business date (yyyyMMdd) on which this order was opened.\"}}},\"VerifyPromotionRequest\":{\"type\":\"object\",\"description\":\"A type of `PromotionRequest` to verify that a new promotion can be added to a check. The only fields that are provided in this request are `check`, `appliedPromotions`, `newPromotion`, `requestDateTime`, and `requestUser`.

The `newPromotion` field contains the promotion code that should be queried for the restaurant, and `check`, `appliedPromotions`, and `requestDateTime` can be used to validate that a promotion can be applied.\",\"required\":[\"check\",\"appliedPromotions\",\"newPromotion\",\"requestDateTime\"],\"allOf\":[{\"$ref\":\"#/components/schemas/PromotionRequest\"}]},\"ApplyPromotionsRequest\":{\"type\":\"object\",\"description\":\"A request with a list of AppliedPromotions that should be applied/committed. The only fields that are provided in this request are `check`, `appliedPromotions`, `promotionsToActOn`, `requestDateTime`, and `requestUser`. All promotions on `promotionsToActOn` should be committed, and the other fields can be used to validate them.\",\"required\":[\"check\",\"appliedPromotions\",\"promotionsToActOn\",\"requestDateTime\"],\"allOf\":[{\"$ref\":\"#/components/schemas/PromotionRequest\"}]},\"RevalidatePromotionsRequest\":{\"type\":\"object\",\"description\":\"A request with a list of AppliedPromotions that should be revalidated. The only fields that are provided in this request are `check`, `appliedPromotions`, `promotionsToActOn`, `requestDateTime`, and `requestUser`. Promotions on `promotionsToActOn` should be revalidated, and can be updated by the response. Promotions not included in this field have already been APPLIED, and can no longer be modified. The other fields can be used to validate the promotions in `promotionsToActOn`.\",\"required\":[\"check\",\"appliedPromotions\",\"promotionsToActOn\",\"requestDateTime\"],\"allOf\":[{\"$ref\":\"#/components/schemas/PromotionRequest\"}]},\"VoidPromotionsRequest\":{\"type\":\"object\",\"description\":\"A request with a list of AppliedPromotions and the GUID of the check that they belong to. The only fields that are provided in this request are `promotionsToActOn` and `checkGuid`. All promotions supplied in `promotionsToActOn` should be voided. The individual promotions should be identifiable by the tuple of (promotion.externalId, checkGuid, and Toast-Restaurant-External-ID).\",\"required\":[\"promotionsToActOn\",\"checkGuid\"],\"allOf\":[{\"$ref\":\"#/components/schemas/PromotionRequest\"}]},\"PromotionObject\":{\"type\":\"object\",\"description\":\"An object to encapsulate information about a promotion.\",\"properties\":{\"appliedDate\":{\"description\":\"The date when this promotion was applied. If not specified, set to the current system time.\\n[Use ISO 8601 date and time format for all Toast APIs](https://dev.toasttab.com/Ie5QH/api_dates_and_timestamps.html).\\n\",\"type\":\"string\",\"format\":\"date-time\"},\"appliedBusinessDate\":{\"description\":\"The YYYYMMDD integer for the business date that the promotion was applied at the given restaurant.\\n\",\"type\":\"integer\"},\"promoCode\":{\"type\":\"string\",\"description\":\"The promotion code that was applied for this discount.\"},\"name\":{\"type\":\"string\",\"description\":\"The name of the applied discount. The name must be supplied by vendor and be guest-friendly, as it will appear on both the POS and the receipt.\"},\"discountAmount\":{\"description\":\"The dollar amount of the discount that was applied. Please note that this amount should not include tax. Toast handles all tax calculations for discounts.\",\"type\":\"number\",\"format\":\"double\"},\"referenceId\":{\"description\":\"A string field that can be used by partners to store some id. Can only be filled on the VERIFY request; the response value will be included on the promotion for future requests.\",\"type\":\"string\"}}},\"AppliedPromotion\":{\"type\":\"object\",\"description\":\"An object containing information about a promotion attached to a check.\",\"required\":[\"externalId\"],\"allOf\":[{\"$ref\":\"#/components/schemas/PromotionObject\"},{\"type\":\"object\",\"properties\":{\"externalId\":{\"description\":\"The `Toast-Transaction-GUID` from the VERIFY request made to produce this applied promotion. This field should be populated by the provider in the response for verify requests.\",\"type\":\"string\"},\"appliedDiscountGuid\":{\"description\":\"This GUID corresponds to an AppliedDiscount.guid contained in Check.appliedDiscounts, and indicates the applied discount that is associated with the promotion.\",\"type\":\"string\"}}}]},\"PromotionError\":{\"type\":\"object\",\"description\":\"A response object that contains information about why a promotion cannot be applied.\",\"allOf\":[{\"$ref\":\"#/components/schemas/AppliedPromotion\"},{\"type\":\"object\",\"properties\":{\"developerErrorMessage\":{\"description\":\"Internal-only message that developers can use to better understand the error.\",\"type\":\"string\"},\"userErrorMessage\":{\"description\":\"A user-friendly error message to display to the restaurant employee on the POS.\",\"type\":\"string\"},\"errorType\":{\"type\":\"string\",\"description\":\"A specific type for well-known error states.\\n \\n\",\"enum\":[\"INVALID_REQUEST\",\"CODE_ALREADY_USED\",\"CODE_NOT_EXIST\",\"CODE_NOT_APPLY\",\"CODE_INACTIVE\",\"OTHER\"]}}}]},\"StatusResponse\":{\"type\":\"object\",\"description\":\"A response object containing information about connection and more.\",\"discriminator\":{\"propertyName\":\"entityType\"},\"required\":[\"status\"],\"properties\":{\"status\":{\"description\":\"Status of connection.\",\"type\":\"string\"}}},\"ErrorResponse\":{\"type\":\"object\",\"description\":\"A response object containing information about connection and more.\",\"discriminator\":{\"propertyName\":\"entityType\"},\"required\":[\"status\"],\"properties\":{\"developerErrorMessage\":{\"description\":\"Internal-only message that developers can use to better understand the error.\",\"type\":\"string\"},\"userErrorMessage\":{\"description\":\"A user-friendly error message to display to the restaurant employee on the POS.\",\"type\":\"string\"},\"invalidPromotions\":{\"description\":\"An array of promotions for this check. For a `PROMOTION_VERIFY`, contains only a single element, the promotion being checked.\\nFor `PROMOTION_REVALIDATE` or `PROMOTION_APPLY` requests in which multiple applied promotions may be invalid, all invalid promotions are described here.\\n\",\"type\":\"array\",\"items\":{\"$ref\":\"#/components/schemas/PromotionError\"}}}}}}}},\"options\":{\"hideTryItPanel\":true,\"pagination\":\"item\",\"generateCodeSamples\":{\"languages\":[{\"lang\":\"curl\"},{\"lang\":\"Java\"},{\"lang\":\"Python\"}]},\"showConsole\":false,\"hideHostname\":true,\"hideDownloadButton\":true,\"sortPropsAlphabetically\":true,\"schemaDefinitionsTagName\":\"Data definitions\",\"disableSearch\":true,\"ctrlFHijack\":false,\"disableSidebar\":true,\"theme\":{\"overrides\":{\"DownloadButton\":{\"custom\":\"\"},\"NextSectionButton\":{\"custom\":\"\"}},\"codeBlock\":{\"tokens\":{}},\"schema\":{\"constraints\":{},\"examples\":{}},\"rightPanel\":{\"textColor\":\"#eeeeee\"},\"typography\":{\"heading1\":{},\"heading2\":{},\"heading3\":{},\"rightPanelHeading\":{}}}}}","permission":"guest","lastModified":"2023-02-13T02:57:02.000Z","redocInfoPageId":"promotions.reference.page.yaml#overview","redocPagination":"item","redocInfoPageLink":"","redocHasInfoPage":false,"redocHasSecurityDefinitions":false,"httpVerb":null,"matchPath":"","excludeFromSearch":false,"sourcePath":"/data/toasttab/redocly-portal-config-prerelease-promotions/promotions.reference.page.yaml"},"definitionProperties":{},"permission":"guest","versions":[{"definitionId":"promotions","isDefault":true,"id":"promotions","title":"promotions","link":null}]}]}}