Skip to main content

Migration

Welcome to the Winston POS v2.0 API migration guide!

We're excited to announce version two of our API. This version update aims to be more predictable, robust, and developer-friendly. It includes stricter RESTful conventions, simplified payload structures, and it now relies on standard HTTP status codes for proper error handling.

This guide outlines all the breaking changes, endpoint relocations, and payload modifications you will need to update your integrations.

At a glance, the biggest changes include:

  • Bearer token authentication: API keys have moved from query parameters to the Authorization header.
  • Strict HTTP status codes: We have removed the redundant status: 'success' wrapper from almost all JSON responses. Success and failure are now strictly indicated by standard HTTP status codes (e.g., 200 OK, 400 Bad Request).
  • Unified collection routes: All collection-based endpoints have been centralized under the /list/ path.
  • Cleaner payloads: We've flattened unnecessary data objects and renamed fields to be more intuitive and consistent across the board.

We know migrations can be a chore, but we highly recommend updating your integrations as soon as possible to take advantage of the improved reliability.

Missing anything, or running into unexpected issues? Feel free to contact our API support team.

Authentication​

Authentication is no longer handled via query parameters. The new API requires that the API key is provided through the Authorization HTTP header as a Bearer token (Authorization: Bearer <api_key>).

This is the same API key as you would previously provide in the api_key query parameter (exception noted below). The app_name query parameter is no longer required.

Miscellaneous integrations​

The new API no longer supports API keys that had a corresponding app_name value of 'selforder'. The corresponding integration has also been marked as legacy in our backoffice.

The new API works with the new miscellaneous integration that requires you to sign up as an integrator before you can authenticate to our API. You can read here how that works.

If you are currently not using the 'selforder' app name, you don't have to do anything. The other integrations will still work with your existing API key.

Routes​

Below is the categorized list of route changes.

General / Collections​

  • Endpoint relocation: All collection routes are now nested under the /list/ route. In the V1 API, these were custom routes at the root (e.g., /bills is now /list/bills).
  • Response changes: The /list/ route no longer returns the status field.

Schemas​

  • /schemas/
    • The data key in the response payload has been renamed to collections.
    • The status field has been removed.
  • /schemas/:collection/
    • The data key in the response payload has been renamed to schema.
    • The status field has been removed.
    • Error handling: Now correctly returns a non-200 HTTP status code on error instead of a 200 OK with a failed status payload.

Tenants​

  • /tenants/
    • The endpoint to create a tenant has been moved to /tenants/create.
    • The status field in the response has been removed.

Categories​

  • /categories/vatList/
    • The status field in the response has been removed.

List​

  • /list/
    • The status field has been removed.
    • The data field has been renamed to collections.
  • /list/:collectionName/
    • The status field has been removed.

Sync​

  • Endpoint relocation: The /:collectionName/sync routes have been moved to /sync/:collectionName.
  • /sync/
    • The status field has been removed.
    • The data field has been renamed to collections.
  • /sync/:collectionName/
    • The status field has been removed.

Reservations​

  • Removed endpoints:
    • /reservations/get (Use the /reservations/list route instead).
    • /reservations/remove (Use the /reservations/delete route instead).
    • /reservations/list (Use the /list/reservations route instead).
  • Error handling & response changes: The following routes no longer return true or false booleans. Instead, if no entries are updated/removed, they will return a 400 HTTP error code:
    • /reservations/update
    • /reservations/delete
    • /reservations/assignTable
    • /reservations/removeTable
    • /reservations/checkIn

Tables​

  • /tables/order
    • The status field has been removed.
    • The data field has been removed; the order object is now part of the root response object.
  • /tables/order/verify
    • Endpoint relocation: Moved to /tables/verifyOrder.
    • The status field has been removed.
    • The data field has been renamed to order.
  • /tables/pay
    • Request body: The _id field has been renamed to id.
    • The status field in the response has been removed.
Last updated on