2. Webhook topics

Recalling memory of setting scopes of app, what webhook events you can possibly receive depend on scopes of you app. Here is the full list of webhook you can register and the corresponding trigger scenarios.

List of webhook events

Webhook topics' tabs in DC Webhook Page	Topic in the webhook Payload you will receive	Required Scopes in DC App Scope page	Trigger scenarios
Application	application/install application/uninstall	no scope is required	application/install When a user installs an application When a user starts a free trial of an application application/uninstall When a user uninstalls an application When a user's SHOPLINE main subscription ends, and the application is not included in the next subscription
Access token	access_token/create access_token/revoke	no scope is required, but you need to enable this in OAuth Strategy
App Subscription	application_subscription/create application_subscription/update (merchant unsubscribe) application_subscription/delete (app removed when subscription end)	no scope is required	application_subscription/create When a user begins a paid app subscription When a user starts a free trial of an application When a user converts from the free trial to a paid app subscription When a user begins a custom subscription. application_subscription/update When a user unsubscribes/churns an ongoing app subscription When a user resubscribes/reactivates an unsubscribed app subscription application_subscription/delete When a user's SHOPLINE main subscription ends, and the application is not included in the next subscription When a user converts from the free trial to a paid app subscription When a free trial period of an application ends When main / app subscription grace period ends
Subscription Record	subscription_record/start subscription_record/end	no scope is required	subscription_record/start When a user begins a paid app subscription When a user converts from the free trial to a paid app subscription When a recurring app subscription starts a new iteration When a user begins a custom subscription. subscription_record/end When a recurring app subscription ends When main / app subscription grace period ends
Merchant Custom Order	patch	no scope is required, but you will need to apply with partnership team to enable the custom order feature for your app
Customer	customer/create customer/sign_in customer/update customer/mobile_sign_in customer/sign_in customer/membership_tier_update customer/remove customer/new_member	Customers - index, or; Customers - show, or; Customers - all;
Order	order/create order/cancel order/remove order/pending order/confirm order/complete order/update order/product_detail_notify_customer order/status_notify_customer	Orders - index, or; Orders - show, or; Orders - all;
Order Payment	order_payment/update order_payment/complete order_payment/refund order_payment/status_notify_customer	Order - index, or; Order - show, or; Order - all;
Order Delivery	order_delivery/update order_delivery/status_notify_customer	Order - index, or; Order - show, or; Order - all;
Product	product/create product/update product/remove product/back_in_stock	Products - index, or; Products - show, or; Products - all;
Member Point	member_point/create	Member Points - index, or Member Points - show; Member Points - all;
Invoice	invoice/create	Invoice - index, or Invoice - show; Invoice - all;
Merchant	merchant/update	Merchants - index, or Merchants - show; Merchants - all;
Bulk operation	bulk_operation/status_update	Bulk Operations - index, or Bulk Operations - show; Bulk Operations - all;
Tag	tag/create tag/remove	Tags - index, or Tags - all;
Persistent cart	persistent_cart/abandoned_cart	Persistent Carts - index, or Persistent Carts - all;
User Credit	user_credit/create user_credit/update	User Credits - index, or User Credits - all;
Flash price campaign	flash_price_campaign/activate flash_price_campaign/terminate flash_price_campaign/expire	Flash Price Campaigns - index, or Flash Price Campaigns - show; Flash Price Campaigns - all;
Comment	comment/payment_slip_upload	Comments - index, or Comments - all;
Product Review Comments	product_review_comments/create	Product Review Comments - index, or Product Review Comments - show; Product Review Comments - all;
Metafields	metafields/create metafields/update metafields/remove	Metafields - index, or; Metafields - show, or; Metafields - all;
Metafield Definitions	metafield_definitions/create metafield_definitions/remove	Metafield Definitions - index, or; Metafield Definitions - show, or; Metafield Definitions - all;
App Metafields	app_metafields/create app_metafields/update app_metafields/remove	App Metafields - index, or; App Metafields - show, or; App Metafields - all;

Payload

The payload of the webhook we send to you is in the following structure

Column	type	Description
event	string	the resource / event of this webhook, e.g. Application, Order, OrderPayment
merchant_id	string	ID of the merchant who owning this resource
topic	string	the topic of this webhook, shown in the table above e.g. application/install, order/update
resource	object	The structure of resource is different from resource to resource. You can refer to the [Shopline OpenAPI Documentation] (https://open-api.docs.shoplineapp.com/).

{
 "event": "Order",
 "merchant_id": "61235e00a6e4e8001c46d6ea",
 "topic": "order/update",
 "resource": {
   ...
 },
 "trace_id": "b45a92d2-55cf-4618-8df8-193f23efcff2",
 "ts": "1658890085251741700"
}

{
  "application_id": "63747f0004cdc7001d0e5866",
  "event": "ApplicationSubscription",
  "merchant_id": "634547547b8f480025fae480",
  "plan_information": {
    "plan_description": {
      "en": "Basic plan for merchants",
      "th": "",
      "vi": "",
      "zh-cn": "",
      "zh-hant": ""
    },
    "plan_key": "LGLO8PIS0LJ1F2E",
    "plan_name": {
      "en": "Basic",
      "th": "",
      "vi": "",
      "zh-cn": "",
      "zh-hant": ""
    }
  },
  "resource": {
    "_id": "657ad69588c1ef0f01b881f6",
    "application_id": "657ace90f78944c5fca96027",
    "merchant_id": "61ce729dc1da2a0007c96c00"
  },
  "status": "subscribed",
  "subscribed_by": "MERCHANT",
  "topic": "application_subscription/create",
  "trace_id": "38789e28-9c86-445f-ab28-8b36c052459d",
  "ts": "1702549256504615194"
}

{
  "application_id": "657ace90f78944c5fca96027",
  "billing_cycle": "1year",
  "charging_model": "standard",
  "event": "SubscriptionRecord",
  "merchant_id": "61ce729dc1da2a0007c96c00",
  "plan_snapshot": {
    "plan_key": "E9RL1Q4RD8W2FSP"
  },
  "resource": {
    "id": "657ad696ebf0c453d559f0eb"
  },
  "subscription_fees": {
    "plan_price": {
      "currency": "HKD",
      "price": 0
    }
  },
  "subscription_period": {
    "end_at": "2024-08-04T03:50:59Z",
    "start_at": "2023-12-21T10:19:02.139Z"
  },
  "topic": "subscription_record/start",
  "trace_id": "84a736f2-11af-4362-9f80-f7c9c79c2c5a",
  "ts": "1702549186250848975"
}

{
  "application_id": "65797c9dd4534fa04a22d801",
  "billing_cycle": "3year",
  "charging_model": "standard",
  "event": "SubscriptionRecord",
  "merchant_id": "6569780738b4c46f265ed58a",
  "plan_snapshot": {
    "plan_key": "I575EJ9T51NZ1JR"
  },
  "resource": {
    "id": "657aca081b103a7bbce36cd7"
  },
  "subscription_fees": {
    "plan_price": {
      "currency": "TWD",
      "price": 123
    }
  },
  "subscription_period": {
    "end_at": "2023-12-14T09:56:04.516Z",
    "start_at": "2023-12-14T09:25:28.297Z"
  },
  "topic": "subscription_record/end",
  "trace_id": "c5c9a986-de47-4132-9ee7-9aef05563f57",
  "ts": "1702547795157949442"
}

{
  "event": "MerchantCustomOrder",
  "merchant_handle": "abc1032879",
  "merchant_id": "651bb738ef795669b3f868f7",
  "merchant_name": "demo store",
  "order_number": "S202312181885932284",
  "resource": {
    "id": "657fc404f1bc72ef6da46a80"
  },
  "status": "completed",
  "topic": "merchant_custom_order/patch",
  "trace_id": "933a1a1c-5945-4a1d-98c0-96ee9d741b4d",
  "ts": "1702872166407092729"
}

// metafield_definitions/create
{
  "event": "MetafieldDefinitions",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "created_at": "2024-06-04T06:08:53.772+00:00",
    "description": "company name of customer",
    "field_type": "single_line_text_field",
    "id": "665eaf7550167f10030d35a2",
    "key": "company",
    "merchant_id": "6270db2f9ece2a1f1089d7ac",
    "metafield_type": "merchant",
    "name": "customer company",
    "namespace": "detail",
    "resource_type": "customer",
    "updated_at": "2024-06-04T06:08:53.772+00:00"
  },
  "topic": "metafield_definitions/create",
  "trace_id": "2234b243-99f7-4c47-b7c2-099492af0e51",
  "ts": "1717481333956755405"
}

// metafield_definitions/remove
{
  "event": "MetafieldDefinitions",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "id": "665eb80a50167f10030dd3f1"
  },
  "topic": "metafield_definitions/remove",
  "trace_id": "bddec884-5542-48ca-a5d1-672884985992",
  "ts": "1717483968779954523"
}

// metafields/create
{
  "event": "Metafields",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "created_at": "2024-06-04T06:45:30.349+00:00",
    "field_type": "single_line_text_field",
    "field_value": "Wonderful Company",
    "id": "665eb80a50167f10030dd3e0",
    "key": "company",
    "merchant_id": "6270db2f9ece2a1f1089d7ac",
    "metafield_type": "merchant",
    "namespace": "detail",
    "resource_id": "664c73b22ffa7a00437addce",
    "resource_type": "customer",
    "updated_at": "2024-06-04T06:45:30.349+00:00"
  },
  "topic": "metafields/create",
  "trace_id": "e3fb4d54-535e-4540-bbdf-664b5209f68e",
  "ts": "1717483530499060436"
}

// metafields/update
{
  "event": "Metafields",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "created_at": "2024-06-04T06:45:30.349+00:00",
    "field_type": "single_line_text_field",
    "field_value": "Amazing Company",
    "id": "665eb80a50167f10030dd3e0",
    "key": "company",
    "merchant_id": "6270db2f9ece2a1f1089d7ac",
    "metafield_type": "merchant",
    "namespace": "detail",
    "resource_id": "664c73b22ffa7a00437addce",
    "resource_type": "customer",
    "updated_at": "2024-06-04T06:47:11.670+00:00"
  },
  "topic": "metafields/update",
  "trace_id": "84e83095-9841-4ab0-ac49-30fb9b09e5a5",
  "ts": "1717483631771059943"
}

// metafields/remove
{
  "event": "Metafields",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "id": "665eb80a50167f10030dd3e0"
  },
  "topic": "metafields/remove",
  "trace_id": "bddec884-5542-48ca-a5d1-672884985883",
  "ts": "1717483968779954523"
}

// app_metafields/create
{
  "application_id": "65d2d6c049015fec833f7067",
  "event": "AppMetafields",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "application_id": "65d2d6c049015fec833f7067",
    "created_at": "2024-06-04T07:12:23.366+00:00",
    "field_type": "single_line_text_field",
    "field_value": "C8G40-8EX7U",
    "id": "665ebe5750167f10030e47b9",
    "key": "serial_number",
    "merchant_id": "6270db2f9ece2a1f1089d7ac",
    "metafield_type": "app",
    "namespace": "65d2d6c049015fec833f7067",
    "resource_id": "1316309-628c551b9a60220084c68b37",
    "resource_type": "cart_item",
    "updated_at": "2024-06-04T07:12:23.366+00:00"
  },
  "topic": "app_metafields/create",
  "trace_id": "4a95b6dc-9523-4530-a564-6a5a0dc01490",
  "ts": "1717485143536755054"
}

// app_metafields/update
{
  "application_id": "65d2d6c049015fec833f7067",
  "event": "AppMetafields",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "application_id": "65d2d6c049015fec833f7067",
    "created_at": "2024-06-03T16:32:44.630+00:00",
    "field_type": "single_line_text_field",
    "field_value": "5VX6F-K9R3L",
    "id": "665df02c50167f1003ff84a3",
    "key": "serial_number",
    "merchant_id": "6270db2f9ece2a1f1089d7ac",
    "metafield_type": "app",
    "namespace": "65d2d6c049015fec833f7067",
    "resource_id": "1316309-64f695f99313475e7f5a9160",
    "resource_type": "cart_item",
    "updated_at": "2024-06-04T07:12:23.366+00:00"
  },
  "topic": "app_metafields/update",
  "trace_id": "7ebe3f6a-2b6d-4c84-8099-e6d98476795d",
  "ts": "1717485143535799795"
}

// app_metafields/remove
{
  "application_id": "65d2d6c049015fec833f7067",
  "event": "AppMetafields",
  "merchant_id": "6270db2f9ece2a1f1089d7ac",
  "resource": {
    "id": "665ebe5750167f10030e47b9"
  },
  "topic": "app_metafields/remove",
  "trace_id": "e92455b5-df28-4e2e-be9f-847ea006baa3",
  "ts": "1717485523971891947"
}

📘
Open API
Shopline exposes our API in this open platform. In order to gain access to it, please refer to OpenAPI.

📘
More explanation on using webhook to track recurring subscription
Please refer to Faqs for more explanation like when to use "application_subscription/update", "subscription_record/start" & "subscription_record/end". Faqs