Notifications

Koywe emits notifications to keep merchant users informed about order events — separately from webhooks, which are meant for server-to-server integrations.

There are two independent channels, configured per merchant:

• In-app notifications: delivered to users signed into the Koywe dashboard. Always on.
• Email notifications: opt-in. Off by default; enable and choose recipients per merchant.

In-App Notifications

In-app notifications are generated automatically for order events only — eventType uses the order.* subset of the webhook taxonomy (e.g., order.completed, order.failed) and does not cover merchant.*, policy.*, webhook.ping, or other families. Each notification is scoped to a single merchant and can be listed, counted, and marked as read through the API that powers the dashboard notification center.

Notification Object

{
  "id": "d2dd8481-3552-4466-b99e-a7caad69a302",
  "merchantId": "koywe-3-sys",
  "orderId": "ord_abc123",
  "orderType": "PAYIN",
  "eventType": "order.completed",
  "title": "Your payment completed",
  "body": "Your payment of $500 USD was processed successfully.",
  "read": false,
  "readAt": null,
  "createdAt": "2026-04-13T18:00:00.000Z",
  "metadata": null
}

List Notifications

GET /api/v1/merchants/{merchantId}/notifications/inapp

Paginated, newest first.

Query parameters

const response = await axios.get(
  `https://api.koywe.com/api/v1/merchants/${merchantId}/notifications/inapp`,
  {
    params: { page: 1, limit: 50 },
    headers: { Authorization: `Bearer ${token}` }
  }
);
 
const { data, total, page, limit } = response.data;

Unread Count

GET /api/v1/merchants/{merchantId}/notifications/inapp/unread-count

Returns { "count": 3 }. Use this for the badge on your bell icon — it’s cheaper than paginating the full list.

Mark One as Read

PATCH /api/v1/merchants/{merchantId}/notifications/inapp/{notificationId}/read

Returns { "ok": true }.

Mark All as Read

PATCH /api/v1/merchants/{merchantId}/notifications/inapp/read-all

Returns { "updated": 5 } — the number of notifications that transitioned from unread to read.

Email Notification Settings

Email notifications are off by default. Enable them per merchant and provide a list of recipient addresses. Koywe then emails the recipients on order events alongside the in-app notification and webhook.

Get Settings

GET /api/v1/merchants/{merchantId}/notification-settings

Returns the configured settings, or the defaults if nothing has been set yet:

{
  "emailEnabled": false,
  "recipients": []
}

Update Settings

PUT /api/v1/merchants/{merchantId}/notification-settings

{
  "emailEnabled": true,
  "recipients": ["ops@merchant.com", "finance@merchant.com"]
}

Rules:

• emailEnabled is required.
• When emailEnabled is true, at least one valid email address must be provided in recipients.
• When emailEnabled is false, recipients may be omitted and the existing recipient list is preserved until you explicitly clear it.
• When recipients is sent, it replaces the entire existing list. To clear all recipients, send an empty array (recipients: []); omitting the field does not clear previously configured recipients.

await axios.put(
  `https://api.koywe.com/api/v1/merchants/${merchantId}/notification-settings`,
  {
    emailEnabled: true,
    recipients: ['ops@merchant.com', 'finance@merchant.com']
  },
  { headers: { Authorization: `Bearer ${token}` } }
);

When to Use What

The three channels are independent — an order event fires all three where configured.

Next Steps