SHOPLINE Integration Explained

Introduction

💡 Overview
Natively integrating SHOPLINE with your external platform involves two primary parts:

1. Creating a private application in SHOPLINE to register your platform.

2. Creating a Webhook for each event you want to monitor.

Once these are set up, your integration is ready.

Part 1: Create a Private Application

1. Navigate to the App Marketplace: Go to App -> Develop Apps -> Create an App.

2. Input the following three fields for your new app:
• App name: A unique identifier for administrative purposes.
• App developer: The creator responsible for the app and its maintenance.
• App contact email: An email for user communication and support.

3. After creation, the new app will show a "not installed" status. You must configure its permissions before you can install it and receive an access token.

4. To manage permissions, click "Edit" under the operate column. (See official documentation for detailed permission scopes).

5. After setting permissions, switch to the "API Credentials" tab and click "Install Application" to link the store with your app.

6. The app is now installed, and you are ready to create webhooks.

Part 2: Create a Webhook

1. Click "Edit" on your app again, then click the "Configuration" tab.

2. Scroll to the bottom, past the permissions list, to the "WebHook subscription" section and click "Create a webhook".

3. Input the following three fields:
• Event: Select the event you want to subscribe to (e.g., Order Update).
• Notification URL: The endpoint on your platform where SHOPLINE will send the event data via a POST request.
• Webhook API version: Select the desired version. Deprecated event versions will default to the oldest available version.

4. Click "Create". The webhook will be active immediately.

⚠️ Important Notes

1. No Custom Headers: SHOPLINE does not provide a field to add custom headers (e.g., for an API key) to webhook requests. This means your notification URL must either be an auth-less endpoint (like those from Make.com) or a URL without specific header parameters, which may require additional development effort to secure.

2. Creation Order: You can create the webhook both before and after installing the application.

3. Request Method: SHOPLINE sends all webhook events using the POST method with a Content-Type of application/json.

4. Acknowledgement Required: Your system must respond with a success status code (e.g., 200 OK) to acknowledge receipt of the webhook. If SHOPLINE does not receive this acknowledgement, it will consider the delivery a failure and may disable the webhook after multiple failed retries.

5. Sample Payload: Below is a sample header and body for an Order Update event.
• Sample HeaderJSON

{
  "X-Shopline-Topic": "*****/****",
  "X-Shopline-Hmac-Sha256": "e.g. XWmrwMey6OsLMeiZKwP4FppHH3cmAiiJJAweH5Jo4bM=",
  "X-Shopline-Shop-Domain": "e.g. shophub.myshopline.com",
  "X-Shopline-Shop-Id": "e.g. 1610418123456",
  "X-Shopline-Merchant-Id": "e.g. 2000001234",
  "X-Shopline-API-Version": "e.g. v20210901",
  "X-Shopline-Webhook-Id": "e.g. b54557e48a5fbf7d70bcd043"
}

• Sample BodyJSON

{
  "total_spent": "0",
  "addresses": [ { "...address_details..." } ],
  "gender": "others",
  "last_order_id": "1001",
  "created_at": "2023-05-10T17:00:01+08:00",
  "updated_at": "2023-05-26T19:25:47+08:00",
  "accepts_marketing": true,
  "email_subscribe_flag": 1,
  "nick_name": "test1",
  "currency": "CLP",
  "id": "421475190",
  "state": 3,
  "first_name": "test1",
  "email": "test1@joyy.com",
  "mobile_subscribe_flag": 2
}

6. Other Applications: Similar processes apply when calling the SHOPLINE API or creating public/custom applications, though they involve more complex authorization methods.

📚 References

• SHOPLINE Developer Docs: Private App

• SHOPLINE Developer Docs: Webhook

• SHOPLINE Developer Docs: Event Notification Protocol

• SHOPLINE API Docs: Webhook Topics & Payloads