--- title: API description: Documentation for the API endpoints is available at https://apidoc.thegoodtill.com Test accounts If you are building integration and you would like to test the API without affecting your live account, --- [Skip to content](https://support.thegoodtill.com/support/api#main-content) English Show submenu for translations ![sumup logo-modified.png\]](https://support.thegoodtill.com/hs-fs/hubfs/sumup%20logo-modified.png?height=40&name=sumup%20logo-modified.png) - [Default HubSpot Blog](https://thegoodtill-8238028.hs-sites.com/blog) Open main navigation Close main navigation - [Default HubSpot Blog](https://thegoodtill-8238028.hs-sites.com/blog) - English Show submenu for translations - Home Home Hello. How can we help you? - There are no suggestions because the search field is empty. 1. [Support Knowledge Base](https://support.thegoodtill.com/?hsLang=en) 2. [Integrations](https://support.thegoodtill.com/integrations?hsLang=en) 3. [Custom](https://support.thegoodtill.com/integrations?hsLang=en#custom) # API All SumUp POS stores have access to our API which can be used to: - Manage store data (products, customers, staff etc). - Download reporting data and sales history. - [**Create POS sales from third-party applications.**](https://support.thegoodtill.com/support/external-sale?hsLang=en) - **[Fetch customer loyalty data from your server.](https://support.thegoodtill.com/support/third-party-loyalty/?hsLang=en)** Documentation for the API endpoints is available at [**https://apidoc.thegoodtill.com**](https://apidoc.thegoodtill.com/) **Test accounts** If you are building integration and you would like to test the API without affecting your live account, or you are building integration on behalf of a SumUp POS customer, we'd recommend requesting a "demo mode" account from our CSM team at pos.cs.uk.ie@sumup.com. ### Authentication Authentication is handled by making a [login ](https://apidoc.thegoodtill.com/#api-Authentication-CreateToken)call with credentials (subdomain, username and password) for an administrator or store owner user within the SumUp POS store. This response will contain a [JSON Web Token (JWT)](https://jwt.io/introduction/) which can be used to authorize future requests by passing it in the Authorization header (eg "Authorization: Bearer token\_here"). Tokens are short lived and must be [refreshed](https://apidoc.thegoodtill.com/#api-Authentication-RefreshToken) to keep them active. Certain endpoints require an extra Vendor-Id token – please request this token from pos.support.uk.ie@sumup.com if you require access to these endpoints. ### Data format Requests bodies may be encoded as JSON or x-www-form-encoded, however JSON should be used if possible. Responses bodies are encoded as JSON. Dates and times included in responses will be returned in the timezone configured in the SumUp POS Store. ### Outlets Stores can be configured with multiple outlets, which allows segregating data such as sales, products and stock quantities in different locations. Data entities can be store-wide (such a customers), outlet specific (such as sales) or optionally store-wide (such as products, via the Shareable toggle). The endpoint documentation states whether the entity available via the endpoint is outlet specific or store wide. By default, all requests will fetch data from the outlet where the user account was created. It is possible to access data across multiple outlets using a single user account by specifying an outlet ID in the request, eg "Outlet-Id: outlet\_id\_here". This will change the outlet where data is accessed from if the user has been granted access to the selected outlet (eg via outlet tagging or when using the store owner account which has access to all outlets). A list of outlets (including IDs) that the user has access to can be obtained via the [outlets](https://apidoc.thegoodtill.com/#api-Outlet-GetOutlets) endpoint. ### Rate Limiting The API endpoints are not currently rate limited, however this is subject to change. ### Webhooks Your integration can get near real-time notifications of certain events in your SumUp POS store, such as new sales, using [webhooks](https://support.thegoodtill.com/support/webhook/?hsLang=en). ### Terms of use **All integrations must follow our terms of use** #### Contacting customers If you accessing customer data via the API for marketing purposes (eg to contact the customer via email, phone, post etc) you must exclude customers who have opted out. You should check the customer's opt\_in\_email setting at a regular basis. If this is false, the customer must not be contacted for marketing reasons (eg to notify them of promotions, request feedback etc). ### Support If you have any questions, please read through our document: https://apidoc.thegoodtill.com. If you have specific questions about the document please email pos.support.uk.ie@sumup.com.  ### Client libraries The following client libraries can be used to connect to the Goodtill API. For support, please contact the developer of the library. - [PHP – flairuk/good-till-system](https://github.com/FLAIRUK/good-till-system) ### Example Code The following is a minimal example of how you can fetch data using the Goodtill API using PHP. The code does the following: - Obtain a JWT for accessing the Goodtill API. - Fetches the sales for a date range using multiple requests (due to pagination). - Export the list of sales items in the sale as a CSV. You will need to enter the credentials for an admin or store owner and account and your verification token in the define() calls. In order to keep this example simple, we will call the POST api/login endpoint each time this script is called. Ideally you would save the token in your database allowing you to reuse it until it needs to be refreshed. ``` =7.1// Set Goodtill credentialsdefine('GOODTILL_SUBDOMAIN', '');define('GOODTILL_USERNAME', '');define('GOODTILL_PASSWORD', '');class GoodtillException extends \Exception { }class GoodtillClient { public $token = null; public $outletId = null; public $vendorId = null; public function request(string $url, string $method='GET', array $data=[]): array { $method = strtoupper($method); $request_url = 'https://api.thegoodtill.com/api/'.$url; if ($method == 'GET') $request_url .= '?'.http_build_query($data); $headers = [ 'Content-type: application/json', 'User-Agent: GoodtillPhpClient (+https://support.thegoodtill.com/support/api/)', ]; if ($this->token) $headers[] = 'Authorization: Bearer '.$this->token; if ($this->outletId) $headers[] = 'Outlet-Id: '.$this->outletId; if ($this->vendorId) $headers[] = 'Vendor-Id: '.$this->vendorId; // Make request $curl = curl_init(); curl_setopt($curl, CURLOPT_URL, $request_url); curl_setopt($curl, CURLOPT_HTTPHEADER, $headers); curl_setopt($curl, CURLOPT_RETURNTRANSFER, true); if ($method != 'GET'){ curl_setopt($curl, CURLOPT_CUSTOMREQUEST, $method); curl_setopt($curl, CURLOPT_POSTFIELDS, json_encode($data)); } $responseBody = curl_exec($curl); $responseCode = curl_getinfo($curl, CURLINFO_HTTP_CODE); $error = curl_error($curl); curl_close($curl); $parsedBody = json_decode($responseBody, true); // Check for errors if (empty($error) == false) throw new GoodtillException($error); if ($responseCode > 400){ $errorMessage = $parsedBody['message'] ?? $parsedBody['error'] ?? $responseBody; throw new GoodtillException($errorMessage, $responseCode); } // Return data return $parsedBody; } public function login(string $subdomain, string $username, string $password): array { $data = $this->request( 'login', 'POST', [ 'subdomain' => $subdomain, 'username' => $username, 'password' => $password, ] ); $this->token = $data['token']; return $data; }}try { // Login $goodtill = new GoodtillClient(); $goodtill->login(GOODTILL_SUBDOMAIN, GOODTILL_USERNAME, GOODTILL_PASSWORD); // Fetch the sales each page at a time and stop when we get to the end (no more sales returned). $sales = []; $limit = 50; $offset = 0; while (true) { $response = $goodtill->request('external/get_sales_details', 'GET', [ 'timezone' => 'local', 'from' => '2019-01-01', 'to' => '2019-01-08', 'limit' => $limit, 'offset' => $offset, ]); if (empty($response['data'])) break; $sales = array_merge($sales, $response['data']); $offset += $limit; } // Format the retrieved data as a CSV $handle = fopen('php://memory', 'rw+'); fputcsv($handle, ['product_id', 'product_name', 'quantity', 'line_total_after_discount']); foreach ($sales as $sale){ foreach ($sale['sales_details']['sales_items'] as $sale_item){ fputcsv($handle, [ 'product_id' => $sale_item['product_id'], 'product_name' => $sale_item['product_name'], 'quantity' => $sale_item['quantity'], 'line_total_after_discount' => $sale_item['line_total_after_line_discount'], ]); } } // Get CSV from stream fseek($handle, 0); $csv = stream_get_contents($handle); fclose($handle); echo $csv;} catch (GoodtillException $e) { echo 'Goodtill API exception: '.$e->getMessage();} catch (\Exception $e) { echo 'Generic exception: '.$e->getMessage();} ``` Example output: ``` product_id,product_name,quantity,line_total_after_discount50b2bd53-c0fe-43ca-a16e-f819be792421,Macchiato,1,2.008664c2e7-ecba-451c-a9f2-8f06790bcaf3,Cortado,1,2.20a4ad8d8a-0609-4741-b21f-354a3d896a42,Americano,1,2.80... ``` ### ![](https://support.thegoodtill.com/hubfs/Knowledge%20Base%20Import/thegoodtill.freshdesk.comsupportsolutionsarticles9000190890-apihit-1.gif)   - [Front End](https://support.thegoodtill.com/front-end?hsLang=en#main-content) - [Download And Login](https://support.thegoodtill.com/front-end?hsLang=en#download-and-login) - [Sales](https://support.thegoodtill.com/front-end?hsLang=en#sales) - [Tables](https://support.thegoodtill.com/front-end?hsLang=en#tables) - [Options](https://support.thegoodtill.com/front-end?hsLang=en#options) - [App Refresh](https://support.thegoodtill.com/front-end?hsLang=en#app-refresh) - [FAQ](https://support.thegoodtill.com/front-end?hsLang=en#faq) - [Tips](https://support.thegoodtill.com/front-end?hsLang=en#tips) - [Delivery](https://support.thegoodtill.com/front-end?hsLang=en#delivery) - [Refunds](https://support.thegoodtill.com/front-end?hsLang=en#refunds) - [Ticket/Receipt printouts](https://support.thegoodtill.com/front-end?hsLang=en#ticket-receipt-printouts) - [Back End](https://support.thegoodtill.com/back-end?hsLang=en#main-content) - [Dashboard](https://support.thegoodtill.com/back-end?hsLang=en#dashboard) - [Products](https://support.thegoodtill.com/back-end?hsLang=en#products) - [Ingredients](https://support.thegoodtill.com/back-end?hsLang=en#ingredients) - [Sales](https://support.thegoodtill.com/back-end?hsLang=en#sales) - [Customers](https://support.thegoodtill.com/back-end?hsLang=en#customers) - [Setup](https://support.thegoodtill.com/back-end?hsLang=en#setup) - [Users](https://support.thegoodtill.com/back-end?hsLang=en#users) - [Add-ons](https://support.thegoodtill.com/back-end?hsLang=en#add-ons) - [Settings](https://support.thegoodtill.com/back-end?hsLang=en#settings) - [Change Store](https://support.thegoodtill.com/back-end?hsLang=en#change-store) - [Logout](https://support.thegoodtill.com/back-end?hsLang=en#logout) - [Reports](https://support.thegoodtill.com/back-end?hsLang=en#reports) - [Hardware](https://support.thegoodtill.com/hardware?hsLang=en#main-content) - [Printer Setup](https://support.thegoodtill.com/hardware?hsLang=en#printer-setup) - [Printer Troubleshooting](https://support.thegoodtill.com/hardware?hsLang=en#printer-troubleshooting) - [SumUp](https://support.thegoodtill.com/hardware?hsLang=en#sumup) - [Zettle](https://support.thegoodtill.com/hardware?hsLang=en#zettle) - [PaymentSense](https://support.thegoodtill.com/hardware?hsLang=en#paymentsense) - [Supported Hardware](https://support.thegoodtill.com/hardware?hsLang=en#supported-hardware) - [Scanners](https://support.thegoodtill.com/hardware?hsLang=en#scanners) - [iPad](https://support.thegoodtill.com/hardware?hsLang=en#ipad) - [Modules](https://support.thegoodtill.com/modules?hsLang=en#main-content) - [Advanced Stock](https://support.thegoodtill.com/modules?hsLang=en#advanced-stock) - [Pro](https://support.thegoodtill.com/modules?hsLang=en#pro) - [Advanced Loyalty](https://support.thegoodtill.com/modules?hsLang=en#advanced-loyalty) - [KDS](https://support.thegoodtill.com/modules?hsLang=en#kds) - [Integrations](https://support.thegoodtill.com/integrations?hsLang=en#main-content) - [Built-In](https://support.thegoodtill.com/integrations?hsLang=en#built-in) - [Third Party](https://support.thegoodtill.com/integrations?hsLang=en#third-party) - [Custom](https://support.thegoodtill.com/integrations?hsLang=en#custom) - [Reporting](https://support.thegoodtill.com/reporting?hsLang=en#main-content) - [Advanced Reports](https://support.thegoodtill.com/reporting?hsLang=en#advanced-reports) - [Reports](https://support.thegoodtill.com/reporting?hsLang=en#reports) - [Reporting FAQs](https://support.thegoodtill.com/reporting?hsLang=en#reporting-faqs) - [Goodeats](https://support.thegoodtill.com/goodeats?hsLang=en#main-content) - [Goodeats - Table Ordering](https://support.thegoodtill.com/goodeats?hsLang=en#goodeats-table-ordering) - [Goodeats - Delivery](https://support.thegoodtill.com/goodeats?hsLang=en#goodeats-delivery) - [Fulfilment Options](https://support.thegoodtill.com/goodeats?hsLang=en#fulfilment-options) - [Stripe](https://support.thegoodtill.com/goodeats?hsLang=en#stripe) - [Goodeats](https://support.thegoodtill.com/goodeats?hsLang=en#goodeats) - [Payment Options](https://support.thegoodtill.com/goodeats?hsLang=en#payment-options) - [Extras](https://support.thegoodtill.com/extras?hsLang=en#main-content) - [Extras](https://support.thegoodtill.com/extras?hsLang=en#extras) - [Resources](https://support.thegoodtill.com/extras?hsLang=en#resources) - [Redirects](https://support.thegoodtill.com/extras?hsLang=en#redirects) - [MISC](https://support.thegoodtill.com/extras?hsLang=en#misc) - [Deposit Return Scheme](https://support.thegoodtill.com/extras?hsLang=en#deposit-return-scheme) - [System scenarios](https://support.thegoodtill.com/system-scenarios?hsLang=en) - [SumUp Connect](https://support.thegoodtill.com/sumup-connect?hsLang=en) - [Default HubSpot Blog](https://thegoodtill-8238028.hs-sites.com/blog) [![Chill listening crop-3](https://support.thegoodtill.com/hs-fs/hubfs/sumup%20logo-modified.png?width=24&height=24&name=sumup%20logo-modified.png "Chill listening crop-3")](http://thegoodtill.com) SumUp Point of Sale Support Copyright © 2026, SumUp