Webhook Topics

LaunchMyStore supports 43 webhook topics that notify your app when events occur in the merchant’s store. Subscribe to these topics with POST /api/v1/webhooks.json to receive real-time notifications. This page is the authoritative topic list.

Available Topics

Orders

Topic	Description
`orders/create`	Fired when a new order is created. Payload includes a standard `shipping_lines[]` array with `source` (the app handle the customer’s shipping rate came from) — see orders/create payload.
`orders/updated`	Fired when an order is updated
`orders/paid`	Fired when an order payment is completed
`orders/cancelled`	Fired when an order is cancelled
`orders/fulfilled`	Fired when all items in an order are fulfilled

orders/create payload

{
  "order": {
    "orderId":      "5c02f40b-aca3-...",
    "invoiceId":    "A0XJ12K",
    "status":       "pending",
    "email":        "buyer@example.com",
    "name":         "Live Buyer",
    "address":      "1 MG Road",
    "addressLine2": "Building A",
    "city":         "New Delhi",
    "state":        "DL",
    "country":      "India",
    "pinCode":      "110011",
    "mobileNumber": "9876543210",
    "currency":     "INR",
    "finalPrice":   8160,
    "shippingPrice": 8085,
    "paymentMethod": "COD",
    "createdAt":    "2026-06-01T22:51:50.123Z",
    "shippingMethod": {
      "appId":       "0524d70f-...",
      "appHandle":   "shiprocket",
      "serviceCode": "shiprocket-1",
      "serviceName": "Blue Dart Air",
      "price":       8085,
      "currency":    "INR"
    }
  },
  "orderProducts": [
    {
      "orderProductId": "...",
      "productId":      "...",
      "varientId":      "...",
      "name":           "Slipper M",
      "quantity":       1,
      "price":          75
    }
  ],
  "shop": {
    "storeId":    "ef10744c-5c4a-4f47-85fc-062ba44afb5f",
    "domainSlug": "raja337276"
  },
  "shipping_lines": [
    {
      "title":    "Blue Dart Air",
      "code":     "shiprocket-1",
      "source":   "shiprocket",
      "price":    "8085",
      "currency": "INR"
    }
  ]
}

shipping_lines[].source is the routing key for shipping apps. When a merchant has multiple shipping apps installed, every app receives every orders/create webhook. Each app inspects source against its own handle and only acts when it matches — this is how your app distinguishes “the customer picked MY rate” from “the customer picked another app’s rate”. See Live Rate Providers for the full handler pattern. source values:

"<app_handle>" (e.g. "shiprocket") — customer picked this app’s live rate at checkout
null — customer picked a merchant ShippingZone or a local-delivery rule (no app should auto-push)

code carries your app’s service_code from the live-rate response. Convention is <app_handle>-<carrier_id> so apps can strip the prefix to recover their carrier’s internal identifier.

Products

Topic	Description
`products/create`	Fired when a new product is created
`products/update`	Fired when a product is updated
`products/delete`	Fired when a product is deleted

Collections

Topic	Description
`collections/create`	Fired when a new collection is created
`collections/update`	Fired when a collection is updated
`collections/delete`	Fired when a collection is deleted

Customers

Topic	Description
`customers/create`	Fired when a customer record is created
`customers/update`	Fired when a customer is updated
`customers/delete`	Fired when a customer is deleted

Discounts

Topic	Description
`discounts/create`	Fired when a discount code is created
`discounts/update`	Fired when a discount code is updated
`discounts/delete`	Fired when a discount code is deleted

Blogs

Topic	Description
`blogs/create`	Fired when a blog is created
`blogs/update`	Fired when a blog is updated
`blogs/delete`	Fired when a blog is deleted

Inventory

Topic	Description
`inventory/update`	Fired when an inventory level changes at any location

Fulfillments

Topic	Description
`fulfillments/create`	Fired when a fulfillment is created
`fulfillments/update`	Fired when a fulfillment is updated

Refunds

Topic	Description
`refunds/create`	Fired when a refund is processed (includes refunds on subscription orders)

Subscriptions

Recurring product subscriptions sold through selling plans. The underlying recurring billing is handled by the merchant’s Stripe subscription; these topics fire as the Stripe subscription moves through its lifecycle.

Topic	Description
`subscriptions/create`	Fired on the first successful charge — a new subscription has started (Stripe `invoice.payment_succeeded`, `billing_reason: subscription_create`).
`subscriptions/renew`	Fired on each automatic renewal charge (Stripe `invoice.payment_succeeded`, `billing_reason: subscription_cycle`).
`subscriptions/update`	Fired when the subscription changes — plan/quantity change, status change, or trial→active (Stripe `customer.subscription.updated`).
`subscriptions/payment_failed`	Fired when a renewal charge fails (Stripe `invoice.payment_failed`). The subscription enters Stripe’s dunning/retry flow.
`subscriptions/cancelled`	Fired when the subscription ends — cancelled by the merchant/customer, or expired at period end (Stripe `customer.subscription.deleted`).

There is no separate subscriptions/expired topic. An expired subscription ends as customer.subscription.deleted in Stripe and is delivered as subscriptions/cancelled. A refund on a subscription order is delivered via refunds/create, not a subscription topic.

Lifecycle order

A typical subscription fires these topics in order over its lifetime:

checkout ──▶ subscriptions/create        (first charge succeeds, access granted)
         ──▶ subscriptions/update         (e.g. trial → active, plan change)   [0..n]
         ──▶ subscriptions/renew          (each automatic renewal charge)      [0..n]
         ──▶ subscriptions/payment_failed (a renewal charge fails)             [0..n]
         ──▶ subscriptions/cancelled      (ends — cancelled or expired)        (terminal)

subscriptions/renew and subscriptions/payment_failed can repeat for the life of the subscription. subscriptions/cancelled is terminal — no further events fire for that subscription afterwards.

subscription payload

All five subscription topics share the same payload shape:

{
  "orderId":              "5c02f40b-aca3-...",
  "invoiceId":            "A0XJ12K",
  "storeId":              "ef10744c-5c4a-4f47-85fc-062ba44afb5f",
  "subscriptionId":       "sub_1QabcdEFgh...",
  "customerId":           "cus_QabcdEF...",
  "customerEmail":        "buyer@example.com",
  "status":               "active",
  "planName":             "Coffee Club — Monthly",
  "amount":               24.0,
  "currency":             "usd",
  "billingInterval":      "month",
  "billingIntervalCount": 1,
  "currentPeriodStart":   1717286400,
  "currentPeriodEnd":     1719878400,
  "trialEnd":             null
}

Field	Type	Description
`orderId`	string	The LaunchMyStore order the subscription was created from. Stable across the whole subscription lifecycle — use it as your local correlation key.
`invoiceId`	string	Human-readable invoice/order reference.
`storeId`	string	The merchant store the subscription belongs to.
`subscriptionId`	string	The recurring subscription identifier (`sub_…`). Unique per subscription.
`customerId`	string	The billing customer identifier (`cus_…`).
`customerEmail`	string	Buyer email — handy for provisioning access on an external system.
`status`	string	Current subscription status (see below).
`planName`	string	The plan/product name shown to the buyer.
`amount`	number	Charge amount per billing cycle, in major units (e.g. `24.0` = $24.00).
`currency`	string	ISO-4217 currency code, lowercase.
`billingInterval`	string	`day` \| `week` \| `month` \| `year`.
`billingIntervalCount`	number	Number of intervals between charges (e.g. `3` + `month` = quarterly).
`currentPeriodStart`	number	Unix timestamp (seconds) — start of the current paid period.
`currentPeriodEnd`	number	Unix timestamp (seconds) — when the next renewal is due.
`trialEnd`	number \| null	Unix timestamp (seconds) when the trial ends, or `null` if no trial.

status mirrors the underlying subscription status. The value you can expect per topic:

Topic	Typical `status`
`subscriptions/create`	`active`, or `trialing` if the plan has a trial
`subscriptions/renew`	`active`
`subscriptions/update`	any — `trialing`, `active`, `past_due`, `canceled`
`subscriptions/payment_failed`	`past_due`
`subscriptions/cancelled`	`canceled`

Example handler

Grant access on the first charge and each renewal, pause on a failed charge, and revoke on cancellation:

app.post('/webhooks/subscriptions', verifyHmac, (req, res) => {
  const topic = req.headers['x-lms-topic'];
  const s = req.body; // the subscription payload above

  switch (topic) {
    case 'subscriptions/create':
    case 'subscriptions/renew':
      grantAccess(s.customerEmail, { until: s.currentPeriodEnd });
      break;
    case 'subscriptions/payment_failed':
      pauseAccess(s.customerEmail);          // card retry in progress
      break;
    case 'subscriptions/cancelled':
      revokeAccess(s.customerEmail);         // terminal
      break;
    case 'subscriptions/update':
      syncPlan(s.customerEmail, s.planName, s.status);
      break;
  }
  res.sendStatus(200); // ack within 10s
});

Idempotency & ordering: deliveries are at-least-once and may arrive out of order or be retried, so key your handler on subscriptionId + currentPeriodStart and make access changes idempotent. The topic is in the X-LMS-Topic header; verify the X-LMS-Hmac-SHA256 signature (see Webhook Verification) before acting.

Carts

Topic	Description
`carts/create`	Fired when a new cart is created
`carts/update`	Fired when a cart is modified (line add/remove/qty change)

Checkouts

Topic	Description
`checkouts/create`	Fired when a checkout begins
`checkouts/update`	Fired when a checkout step is updated

Themes

Topic	Description
`themes/publish`	Fired when a theme is published as the active theme
`themes/update`	Fired when theme files or settings change

Shop

Topic	Description
`shop/update`	Fired when shop settings are updated

App Lifecycle

Topic	Description
`app/installed`	Fired when your app is installed into a store
`app/uninstalled`	Fired when your app is uninstalled from a store

app/installed and app/uninstalled are dispatched to your app’s configured webhook URL regardless of whether you explicitly subscribed to them — they are platform-level lifecycle events you should always handle.

Storefront Forms

Topic	Description
`newsletter/create`	Fired when a visitor subscribes via a storefront newsletter form
`contact_form/create`	Fired when a storefront contact form is submitted

Topic	Description
`customers/data_request`	Merchant or customer requested their data export. Your app must return all stored personal data for the customer within 30 days.
`customers/redact`	A customer has been deleted; redact (or hash) any data your app stores about them within 30 days.
`shop/redact`	A store has uninstalled your app for 48+ hours; permanently delete all merchant data within 30 days.

GDPR webhooks are mandatory for app-store listing. See GDPR compliance for the payload contract and deadlines.

Subscribing to Webhooks

Create a webhook subscription using the API:

curl -X POST "https://api.launchmystore.io/api/v1/webhooks.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "orders/create",
    "address": "https://your-app.com/webhooks/orders",
    "format": "json"
  }'

Webhook Subscription Parameters

topic

string

required

The webhook topic to subscribe to. Must be one of the 43 topics above.

address

string

required

HTTPS URL where webhook payloads are POSTed.

format

string

default:"json"

Payload format: json (default) or xml.

fields

array

Specific top-level fields to include in the payload. Omit to receive the full payload object.

Webhook Delivery

Property	Value
HTTP Method	`POST`
Content-Type	`application/json`
Timeout	10 seconds
Retry policy	3 attempts: 60s → 300s → 900s with ±10% jitter
Signature header	`X-LMS-Hmac-SHA256`

Your endpoint must return a 2xx status code within 10 seconds to acknowledge receipt. Anything else is treated as a failure and retried per the policy above. After 3 failed attempts the delivery is moved to the delivery-log error state — inspect via Webhook Delivery Logs. See Webhook Verification for the HMAC contract.

Listing Subscriptions

curl -X GET "https://api.launchmystore.io/api/v1/webhooks.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Deleting a Subscription

curl -X DELETE "https://api.launchmystore.io/api/v1/webhooks/{id}.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​Webhook Topics

​Available Topics

​Orders

​orders/create payload

​Products

​Collections

​Customers

​Discounts

​Blogs

​Inventory

​Fulfillments

​Refunds

​Subscriptions

​Lifecycle order

​subscription payload

​Example handler

​Carts

​Checkouts

​Themes

​Shop

​App Lifecycle

​Storefront Forms

​GDPR (Mandatory)

​Subscribing to Webhooks

​Webhook Subscription Parameters

​Webhook Delivery

​Listing Subscriptions

​Deleting a Subscription

Webhook Topics

Available Topics

Orders

orders/create payload

Products

Collections

Customers

Discounts

Blogs

Inventory

Fulfillments

Refunds

Subscriptions

Lifecycle order

subscription payload

Example handler

Carts

Checkouts

Themes

Shop

App Lifecycle

Storefront Forms

GDPR (Mandatory)

Subscribing to Webhooks

Webhook Subscription Parameters

Webhook Delivery

Listing Subscriptions

Deleting a Subscription