The Goodtill External Sale API allows orders to be sent to the Goodtill POS programmatically. Once an External Sale order is created, it will appear on the relevant Goodtill POS registers within 10 seconds.
If the order is marked as pre-accepted or accepted on the POS, the tickets will be printed and the order will be sent to the Kitchen Display application ready to be prepared, exactly the same as if the order was taken directly on the POS application. The operator can then advance the order state, depending on the type of order (delivery or collection) before marking the order as completed.
If the order is rejected on the POS application, the sale will be voided in Goodtill. The third party system can be notified of the rejection by polling the GetSale endpoint until the order is marked as complete.
External Sales are recorded in the backoffice and are comprised of Goodtill products, the same as standard POS sales, allowing both POS and External Sale data to be included in backoffice reports. The third party application which creates the order must process the payment – Goodtill only records the payment amount and method used for the transaction.
The following flowchart shows an External Sale moving through the system:
Suggested integration path
- Ensure that all products and modifiers from the external system have been created in Goodtill.
- Use the ExternalSale-GetProducts endpoint to fetch these products and modifiers in the external system, including their IDs.
- Store the Goodtill IDs in the products and modifiers in the external system.
- When a new sale is created in the external system, call ExternalSale-CreateSale to create the sale in Goodtill and send it to the POS.
- Optional. Send any changes in order state from the external system to Goodtill via the ExternalSale-UpdateSaleStatus endpoint.
- Optional. Listen for changes to the Goodtill order state in the external system to relay this to the customer. This can be achieved by polling the API or via webhooks.
- Optional. Relay sale cancellations in the external system to Goodtill by calling ExternalSale-UpdateStatus with the REJECTED or CANCELLED statuses.
If you would like to use the External Sale API in your application, please contact email@example.com for a Vendor-Id token.
Can the external system product IDs be stored in Goodtill?
Each Goodtill product has 4 custom fields which can be used for storing external data. These fields are included in the ExternalSale-GetProducts data, so this could be used to map the product IDs.
What happens if a product is out of stock?
The CreateSale endpoint does not validate stock availability. The sale will be created regardless of whether stock is available.
What's the benefit to setting product IDs in the CreateSale request?
Setting product IDs for the sales items in the request has the following benefits:
- Sales of the product will be counted in Goodtill reports.
- The VAT rate does not need to be specified, this is instead taken from the product configuration.
Why aren't tickets printed when orders are received?
The POS will only print the tickets when the order reaches the ACCEPTED state. The tickets are printed when the order is updated from CREATED to ACCEPTED from the POS app, or if the order is received in the ACCEPTED state. If the ExternalSale-UpdateSaleStatus endpoint has been used to advance the state past ACCEPTED when the POS fetches the sale, the tickets will not be printed.
How are multiple outlets handled?
The API allows differentiating between outlets using the Outlet-Id header - more details here. To place an order in a specific outlet, ensure that the correct Outlet-Id header is set and the user account has permission to access the requested outlet.
Does the POS need to be online to accept orders?
Sales can be created via the API regardless of whether any POS terminals are online. The POS will fetch any incomplete sales within the last 14 days when it next becomes active.
Can the POS be used to take the payment (via cash, card etc) for an external sale?
Yes. If there is an amount due, because the payments total in the request does not match the order value, the POS can be used to take the payment via cash or a connected card machine.