App Installation Token and Link Account

Objective

This guide provides instructions on connecting third-party web service with SHOPLINE. By establishing this integration, your web service can:

1. obtain “app installation token” to access Open API on behalf of merchants.
2. prompt clients to link their account in your web service with SHOPLINE.

After completing these 2 steps, your app will able to collect information as shown in the figure:

General Steps

Step 1: Obtain App Installation Token

To integrate your web app with SHOPLINE, you will need an app installation token. This token grants your app access to Open API on behalf of the client.

When a client installs your app through our app store, a webhook containing the app installation token will be sent to your service (access_token/app_installation_token_create). The webhook payload includes the merchant ID and token. Your app should store both in a database (e.g. shopline_merchant_id and shopline_open_api_token field).

For more detail, please consult this document App Installation Token.

Step 2: “Link SHOPLINE Account” through OAuth2.0

At this point, your service doesn't know which account in your system corresponds to the provided merchant ID. To link our merchant ID to your service's account ID, prompt your clients to complete the "Link Account" process.

The "Link Account" process connects a merchant account on SHOPLINE with their account on your service.

1. The client logs into your third-party web app.
2. The client clicks the "Link Account" button on your web app.
3. Clicking "Link Account" initiates an OAuth2.0 authorization flow. Your web app should redirect to https://developers.shoplineapp.com/oauth/authorize to perform OAuth. Afterward, it will redirect back to your web app for OAuth2.0 token exchange.
4. After obtaining a token, your web app should call https://developers.shoplineapp.com/oauth/token/info to retrieve the current merchant.
5. Your web app can now access the client's account information (current user from session in your website), as well as the merchant ID from SHOPLINE. Store this information in your database to establish a connection between the client's account on your service and their merchant account on SHOPLINE. (account_id and shopline_merchant_id field)

For more detail, please consult this document OAuth2

Additional Steps

Re-authorize

When your app requires additional app scopes, merchant should perform a re-authroization. New token will be generated and will be sent through webhook (access_token/app_installation_token_create) , while old tokens with fewer app scopes remain valid.

You may replace the shopline_open_api_token in your database with latest scope.

App Uninstall / Token Revoke

If you need to perform cleanup when merchant uninstall app, you may listen to the application/uninstall webhook.

Furthermore, when tokens are revoked, your app should remove token from your database.

App uninstallation and revoking app secret will trigger token revocations.

Unlink Account

You may consider adding an “Unlink Account” button to allow clients to unlink SHOPLINE account.