Overview


To start building an EasyStore App, normally we will start with app installation.

App installation helps you to get the access token that can read or write the store’s data using EasyStore API. It is also important to handle the app uninstallation so that when the store reinstall your app again, it can be install successfully again.

You can freely implement your creativity using EasyStore API to build the additional functionality. Here is some common functionalities that can spark your ideas.

App Installation


EasyStore use OAuth 2.0’s Authorization Code Grant to allow merchant grant permissions for the EasyStore App to read or write the store data. If merchant consent the requested permissions of the EasyStore App, an permissions scoped access token will be issued to EasyStore App. The tokens can access to the permitted resources inside API.

App installation process will utilise the “App URL” and “Redirection URL” that setup inside app details page inside EasyStore partner portal. You might need to update them to latest URL before start.

Untitled

Installation steps:

  1. Merchant request to install app.

  2. EasyStore redirect merchant to App URL with query params with a GET request below:

    Query params Description
    shop The online store hostname, also is the unique identifier of the store.
    Example value: example.easy.co
    host_url The store’s admin panel URL.
    hmac The HMAC-SHA256 hash result that use to verify the authenticity of request
    timestamp The request’s timestamp in Unix format.

    You should verify the request authenticity using the HMAC value.

  3. If the request is verified, utilize the shop parameter to check if the store installed this app before or not. For instance, the app can verify the existence of records in database using the shop as a unique identifier.

  4. If the store is new, redirect the request to EasyStore App Installation Authorization page URL.

    The structure of URL will be: {host_url}/oauth/authorize?client_id={client_id}&scope={scope}&redirect_uri={redirect_uri}

    Example: https://admin.easystore.co/oauth/authorize?client_id=app9a11dfd3d9aca1ef&scope=read_products,write_products&redirect_uri=https://apps.yourapps.com/auth/callback

    Components Description
    host_url The store’s admin panel URL.
    client_id The app’s unique Client ID, can be found in app details page at EasyStore Partner Portal.
    scope The API access scopes or the permission that the app wish to request. Separated by comma. Possible scope can refer here.
    redirect_uri The URL that will redirect merchant to after authorize the app installation. Required to be whitelisted in app details page at EasyStore Partner Portal.
  5. EasyStore will show an app installation consent page based on the scope requested in previous step.

    Screenshot 2023-10-08 at 12.08.13 PM.png