Frequently Asked Questions
Please find a collection of frequently asked questions and answers related to our OpenAPI integration. If you are not able to find a solution to your question here in this page, please continue to our Discussions section and post a new question there for our team to review and respond to.
Additionally, you can find many answers to general questions about a partnership with ItsaCheckmate here in our Partner Knowledge Kit.
We have organized these frequently asked questions below in the following sections:
General Integration Questions
Developer & Sandbox ItsaCheckmate Portal Access
OAuth & API Questions
Menu & Menu Elements
Orders & Order Errors
Point of Sale (POS) Questions
Menu Management Portal
Menu Update Notice Webhook
General Integration Questions
Q: How long will the integration take?
A: Right now, we can estimate that it will take one developer about 2-3 weeks from start to certification.
Q: How many developers or developer hours will it take?
A: We are still working on getting an accurate assessment of this based on our early adopters feedback. Right now, we can estimate that it will take one developer about 2-3 weeks from start to certification.
Q: I have signed up, how early can I start the integration?
A: Our team will be in touch within 3 business days about the next steps.
Q: What is the process of getting a restaurant customer live after the integration is completed?
A: Once the integration is certified, our partnership team will connect with your team to discuss launching a beta customer and our Go to Market strategy. You will simply be able to introduce customers to our team at [email protected] and we will work to onboard them and set up the integration with your system as well. If you would like to discuss this prior, please email [email protected].
Q: What is the cost for a restaurant customer to use ItsaCheckmate?
A: Our shelf pricing for customers is outlined on our website and can be found here.
Q: What is the cost to me as a developer to use the integration?
A: $0.12 cents per transaction and capped at $15/month/location. More information can be found here under “Pricing”.
Q: Does the integration support open check functionality for in-store ordering and payment?
A: It does not as of today. This is something we will be looking to support in the Q2 of 2023 for select POS systems.
Q: Does the integration support payment and closing a bill through ItsaCheckmate?
A: You will have to handle payment on your side as ItsaCheckmate does not handle the payment processing or connect you with the POS payment processor at this time. Typically other partners manage payment on their side via a solution like Stripe before the order gets to our system to inject. Then the assumption is that reconciliation occurs between you and the restaurant.
Q: I would love to understand more information about what specifically you can support today through the integration?
A: As of now, you can review ItsaCheckmate OpenAPI Documentation to get a better understanding of what is available today for your team to leverage.
Developer & Sandbox ItsaCheckmate Portal Access
Q: How do I gain access to the developer portal?
A: Navigate to the following link: https://platform.itsacheckmate.com/. On that page, select the Forgot Password link. Enter the email address that we have indicated has been given access. You should receive an email to reset your password, allowing you to set up your own unique password for access.
OAuth & API Questions
Q: Quick question regarding API Key and Secret: Will we receive a unique key and secret per merchant location, or will we be using a single key and secret for all of our merchants, along with the unique location id?
A: V2 API leverages OAuth authentication and you need to create an OAuth application (on developer portal) which will provide you a single Client ID/Secret -> which will in turn need to be used to generate an “Access Token” per each location. You may checkout this documentation for V2 API for more details.
Q: What does it mean to 'Activate' a Location?
A: When you hit that Activate Endpoint - GET - {{HOST}}/api/v2/activate - we'll mark your Access Grant as accessed true - and also we'll generate a Menu that can be fetched for the Location - via GET {{HOST}/api/v2/menu/{{order_source}} - if we have the Ordering Platform's name already set in the Order Processing List. Also, part of the 'generate a Menu' process involves sending an Update Notice Webhook to your server - so some automated process on your end knows to fetch the Menu. When you hit the Activate Endpoint - that's your way of telling us that you want to ingest the Menu and start POS injecting Orders for real, right now. Excluding the Get Location API call, you will need to Activate a Location before you can use the endpoints.
Q: How can I see if a location is already active?
A: To see if a Location is Active hit the Activate Endpoint - GET {{HOST}}/api/v2/activate. If it's already active then you'll get a 200 response with body: { message: "Location already authorized." }
Q: Can I turn a location inactive?
A: No. But it's not really the Location that becomes Active exactly. It's the Access Grant associated with the Location. If you start the OAuth Flow over again you will generate a new Access Grant that will not be active until you hit the Activate Endpoint again.
Q: Why is Get Location API call excluded from the 'Activate' requirement?
A: For all of the API calls - besides Get Location - i.e. /api/v2/get_location - we require that you hit the Activate Endpoint once previously - just because we want to be sure that you are ready to process orders and fully ready. The reason why we exclude Get Location from this requirement is because some of the Ordering Platforms choose not to implement OAuth with a forced login or registration for their Ordering Platform as part of the OAuth flow (please note that this is not recommended). Without that forced login they can't know what Location in their system to match the Token to; so - we let them use the Get Location endpoint for matching purposes - since you can see the name and address in the response:
{
"data": {
"id": 225631,
"name": "Your Ordering Platform - Test Location",
"address": "123 Easy Street",
"city": "Ocean City",
"state": "CA",
"zipcode": "90001",
"url": "",
"brand": "Test Brand",
"time_zone": "Pacific/Pago_Pago",
"pos": "Toast",
"phone_number": "+1(845)747-7963"
}
}
Menu & Menu Elements
Q: Are the modifier names case sensitive? Does the same rule apply for the Item and Group (category) names?
A: Modifier names are case sensitive. And, yes the same applies to Items and Categories.
Q: I have one question regarding the Menu: There are few items like Extra Toppings or Pepperoni that have weird concatenated ids (like this: be51c532-72ae-41b8-8cab-6af7d02a5366##CM_MODGROUP_ID##MenuItem:e494b7e9-a693-4ebd-99b9-f29b538ac00d). Are these supposed to look like this?
A: You will receive IDs for some modifiers which have the same name as other modifiers under a parent item. Such an ID is needed to disambiguate the actual same-named modifiers in the POS while submitting an order.
Q: Can menus be time-based? For example, can there be a different menu for lunch and dinner or a weekday menu and a weekend menu? Similarly, it would be good to know if you can have a different menu or different prices for delivery vs pickup.
A: Absolutely! Menus in our system are all time-based. For every menu, users must set up weekly hours. These hours can be a single set of hours for a given day, or there can be split hours for a single menu (like having a menu that is available for lunch, then have a break, then available again for dinner). Also, multiple menus can each have their own hours. They can be unique hours, or they can overlap each other (like having an all-day menu from 10 AM to 10 PM and a happy hour menu from 5 PM to 7 PM).
As for pricing, our system has the concept of price elevation that can be applied per ordering channel. This is done on a percent basis, and we do have rounding options to avoid messy numbers. However, to answer the question about different menus/pricing for pickup vs delivery, that would have to be a somewhat custom development for your platform. What I mean is that our system can push multiple menus to a platform with no problem, but our system doesn't necessarily have a natural way to say, "This is a delivery menu, and this is a pickup menu." Also, the platform would need to have corresponding logic to apply each of those menus to the proper channel. In addition to this, if the menus were identical in items but differed in pricing, our system would likely run into same-name disambiguation issues. One of the ways that this works with another specific platform is that the platform accepts a menu where each item has two price fields, and on their side, they have logic to apply the appropriate price to the correct ordering experience. In that example, users are able to independently elevate pricing for pickup vs. delivery and not run into the same-name disambiguation issues since it's a single menu with single instances of each of the items in it, but just with multiple prices for each item.
Please keep in mind that what I have just described above is part of a custom integration that we have with a single, large platform. This is not inherently available in our OpenAPI integration, and there is no out-of-the-box way to support different menus or pricing for pickup vs. delivery on a single platform without custom work to be done on both sides, and any custom development requires a business case and approval from leadership.
Orders & Order Errors
Q: How do we capture the order acceptance event? Are all the orders automatically accepted on the ItsaCheckmate system?
A: We accept all the orders automatically.
Q: When I created an order using the sandbox API, I didn't get an error in response when the item or modifier name did not match the menu. But there is an error when I check on the dashboard. What happened here?
A: This is the expected behavior. It is the way our system is designed to work. We expect the item/modifier names to be the same as what we send to you while pushing the menu. If it mismatches, then we error that order which our Error Handling team handles manually. Order processing is not synchronous as it would take more than 30 seconds which is the standard timeout settings of various systems.
Q: Will we be notified of an order error, with detail, via a webhook message?
A: Any errors will be manually handled by our Error Handling team and you won't be notified about it in developer environment. However in production environment, we have multiple mechanisms to notify store about a failed order.
Q: In the case where there are naming errors, does the order fail to post to the POS? What's the behavior in these error cases?
A: Yes, order will fail to submit to POS and it will be handled manually by our Error Handling team.
Q: Can you explain more about how the ItsaCheckmate team handles order errors?
A: IACM assumes all responsibility for an order once we confirm it. Partner platforms can assume that once we confirm receipt of an order this is the same as the restaurant confirming an order.
A: If an order fails due to naming or mapping issues, our error handling team will correct these in real time and resubmit them to the POS. If there is some blocker on the POS side (like min/max issues) that will not allow the order to be integrated, we will integrate the order as an open item order that will have all items in the description so that the restaurant can still fulfill the order. If there is an issue where the POS is offline and so cannot receive anything via API we will email them a notification that their POS is offline. In these cases we usually disable their menus until the POS comes back online. We do not currently send any status updates back to the ordering platforms for submitted tickets. However, we will always get that order information to the restaurant.
Q: For orders, how do we handle situations like - restaurant accepts the order, prepares the order, and then the user calls the restaurant to cancel the order or the user calls the restaurant to update/delete items?
A: Most, if not all, cancellations by a customer need to go through the Ordering Platform since the customer who ordered the food didn't pay the restaurant directly and would need to cancel through the platform. Then the platform would handle that with the restaurant. In the case where the restaurant is canceling the order, either because something occurred on their end or somehow the customer notified the restaurant instead of the online platform they ordered from, it would be on the restaurant to handle this with the ordering platform via the tablet or web portal (or whatever method they usually handle this). In this case, ItsaCheckmate would not be involved either. We currently do not do this for any ordering platforms (send a cancellation update or pass a canceled status back to the POS). Once we deposit the order into the POS we do not (nor do we necessarily have the ability to) change the status of that order in the POS.
Q: Any specific reasons why you don't have order update webhooks? Is it a limitation of the POS systems you integrate into or any reasons we are unaware of? Do you have plans in the future to include them?
A: We will be sending you the absolute most up to date menu that customers will be seeing and ordering from, given that it is being pulled right from the POS. After integration with us via this method, there are substantially less canceled orders / out of stock issues. That said, when there are canceled orders, you should connect with the restaurant directly and they will need to troubleshoot this on their POS. We hope to have more options around this in the future, but to reinforce this as an example, we have roughly 20,000 locations on a particular large ordering platform and this is the same process that is used there as well, along with our other integrated platforms. We do have plans in the future but it is limited by POS.
Q: We are able to successfully send an order to the IACM sandbox. However we don't see order details. How do we view order details to validate the correctness of the order?
A: There should have either been an error or successful order in the Platform application. If there is none, there appears to be some configuration issue on our side or we need to debug further. Kindly share the order number and our team will look into it.
Q: I was hoping for a view of the order details from a restaurant perspective. Think about us as the restaurant and we will process the order. Do you guys have a view like that? Do you guys provide restaurants with a tablet? Or does the order get printed directly to a printer? Even otherwise, the restaurant owner should have an ItsaCheckmate portal where they can review the details I assume?
A: Orders will print directly to the POS printer. We do not provide any tablets or any other hardware to the restaurant. The user is always able to view order details either in the POS or in the OP's portal/dashboard, outside of the ticket that prints as soon as we inject the order into the POS). We have also recently added a UI view for our users to be able to see both successful and errored orders from the Menu Management portal, but this is still in beta and does not show the order details yet, but shows the order id, source, customer name, time, and status (success/fail/etc.). This will likely include order details in the near future.
Q: How does ItsaCheckmate handle future orders? Are future orders held until a certain time before the requested_at value and then sent to the POS?
A: ItsaCheckmate does not hold orders for OpenAPI order integrations. Any order is sent immediately to the POS at the restaurant. Future orders (orders with a requested_at value in the future) are expected to be managed as such by the restaurant. This requested_at value is sent to the POS in the order payload, and it is up to the POS and the restaurant on how they wish to handle things from there.
Point of Sale (POS) Questions
Q: How many POS systems do you integrate with?
A: Over 45 different systems. The full list can be found here.
Q: Are we able to “GET” customer information from the POS system as of today?
A: We do not support the extraction of information outside of menu data from the POS to send to you as a partner. Use cases like loyalty, marketing, payments and many others are areas we hope to support in the near future.
Q: Are POS systems bound to a specific version of the API, or do both versions of the API support all of your integrated POS's?
A: Version 2 api is fully backward compatible with version 1 and should offer the same features as version 1 including POS compatibility.
Q: I am curious to know what the print would look like in terms of the prices/total etc. The reason I ask is the API doesn't take total or taxes. It takes the price and quantity alone. Who does the totals and how is tax calculated?
A: Each POS system may be different in how this is implemented. Several POS systems perform these calculations based on the order payload sent in. Others might rely upon the information that we have in our system. Either way, not to worry on your end as we handle that part ourselves with the POS in mind.
Menu Management Portal
Q: How do we capture the "food prep time" value? We see there is a section under hours management but it says our platform is not supported. Even if you enable it for us, how are subsequent changes to this field captured? is there a webhook?
A: We actually only support that via API with a very small number of Ordering Platforms with custom-built integrations. This may be something that we extend support to all OpenAPI partners, but at the moment, any ordering platform that we integrate with that we do not support this prep time via API with, the prep time I believe is managed by the user within the ordering platform portal itself instead of within our system.
Q: How does the Ordering Platform Online/Offline Availability toggle work?
A: Once you toggle a location offline and push the menu, you will receive an empty set of hours in the menu payload -- confirming that there are no opening hours for this store.
Q: How does the Category Availability toggle work?
A: Once you mark any category as unavailable in the menu management portal and push the menu, you should not receive that category (and children elements) in the menu payload.
Q: “The Special / Holiday Hours feature is not supported for the current integrated ordering platforms of this location. This feature is only supported for the following ordering platforms at this time:” - Is this correct? Are we not required to implement this? Why are we seeing this message if we have decided to support Special Hours?
A: If your team has stated that you intend to support Special Hours, please continue to develop and test it and disregard that message. Because the ItsaCheckmate sandbox portal is a clone of our production environment, that message list the platforms that are currently supported on our production instance. Once your platform is onboarded into production and it has been marked that it supports special hours, your platform will appear underneath that message with other supported platforms.
Q: When using the item availability toggle, I'm getting "suspend_until": "1664856000" for the item "Hot Honey Biscuit" even though it is made available on IACM portal.
A: suspend_until is epoch time also referred as UNIX or POSIX time. If you convert it into a readable format, that will be a time in the past. Ideally, you would need to convert this time format and mark the item as sold out only if the suspend until value is greater than the current time. Epoch/Unix time is the number of seconds that have elapsed since 00:00:00 UTC on 1 January 1970.
Q: What is the reason that you are sending this suspend until time if the item has been made available in the Menu Management Portal and that time is in the past already? What do you expect us to do with these past dates?
A: There are various reasons we need to keep track of sold out state of items even beyond when it's made available (eg: analytics), hence these values persist till some later dates. We expect your system to perform a check if this epoch time is a future date, if so then mark item as out of stock, else mark it as available (if suspend until is in past or nil).
Menu Update Notice Webhook
Q: I'm signed into the developer and location portals, but I need to know how to configure webhooks. Should we provide the webhook URL to you? Also I see webhook is applicable only for menu updates. Will you send the webhook pushes for order updates also?
A: We have a webhook for menu updates that you would need to create and configure in the Settings page of the developer portal. Instructions can be found here at https://openapi-itsacheckmate.readme.io/v2.0/reference/update-notice. ItsaCheckmate will hit this webhook to update you whenever there is a new or updated menu available for a location. You can subsequently use the menu fetch API to pull that menu and update on your platform. For submitting orders to ItsaCheckmate, there is a separate endpoint which you can hit with order details https://openapi-itsacheckmate.readme.io/reference/getting-started-with-your-api. We respond with a success (2xx) for the above order submission, confirming success. No further order updates are delivered back to the ordering platform.