Skip to main content
PATCH
/
v1
/
tenant
/
{tenant_id}
/
preference
/
category
/
{category}
/
Update Tenant Preference Single Category
curl --request PATCH \
  --url https://hub.suprsend.com/v1/tenant/{tenant_id}/preference/category/{category}/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "preference": "opt_in",
  "digest_schedule": {
    "options": [
      {
        "id": "daily-summary",
        "time": {
          "default_value": "09:00"
        },
        "is_default": true
      }
    ]
  },
  "properties": [
    {
      "key": "threshold",
      "value": "100"
    }
  ]
}
'
{
  "name": "Weekly Activity Digest",
  "category": "weekly-activity-digest",
  "description": "Summary of recent activity in your workspace",
  "tags": [
    "digest",
    "activity"
  ],
  "effective_tags": [
    "digest",
    "activity"
  ],
  "root_category": "transactional",
  "default_preference": "opt_in",
  "default_mandatory_channels": null,
  "default_opt_in_channels": null,
  "enabled_for_tenant": true,
  "visible_to_subscriber": true,
  "preference": "opt_in",
  "mandatory_channels": null,
  "opt_in_channels": null,
  "blocked_channels": null,
  "updated_at": "2026-06-29T19:09:04.796887Z",
  "digest_schedule": {
    "options": [
      {
        "id": "daily-summary",
        "label": "Daily summary at 9:00 AM",
        "frequency": "daily",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "09:00"
        },
        "is_default": true
      }
    ],
    "original_options": [
      {
        "id": "instant",
        "label": "Instant",
        "frequency": "instantly",
        "is_default": true
      },
      {
        "id": "daily-summary",
        "label": "Daily summary at 9:00 AM",
        "frequency": "daily",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "00:00"
        },
        "is_default": false
      },
      {
        "id": "weekly-on-weekdays",
        "label": "Every week on Mon–Fri · time set by recipient (default: 9:00 AM)",
        "frequency": "weekly_mo2fr",
        "interval": 1,
        "time": {
          "edit_policy": "editable",
          "default_value": "09:00"
        },
        "weekdays": {
          "edit_policy": "locked",
          "default_value": [
            "mo",
            "tu",
            "we",
            "th",
            "fr"
          ]
        },
        "is_default": false
      },
      {
        "id": "monthly-1st",
        "label": "Every month on the 1st at 9:00 AM",
        "frequency": "monthly",
        "interval": 1,
        "time": {
          "edit_policy": "locked",
          "default_value": "09:00"
        },
        "monthdays": {
          "edit_policy": "locked",
          "default_value": [
            {
              "pos": 1
            }
          ]
        },
        "is_default": false
      }
    ]
  },
  "properties": [
    {
      "key": "threshold",
      "label": "Minimum activity count",
      "value_type": "string",
      "default_value": "10",
      "is_optional": false,
      "edit_policy": "editable",
      "is_overridden": true,
      "value": "100"
    }
  ]
}

Authorizations

​
Authorization
string
header
required

Pass as Bearer <API_KEY>. Get API Key from SuprSend dashboard Developers -> API Keys section.

Path Parameters

​
tenant_id
string
required

unique identifier of the tenant you want to update preferences for

​
category
string
required

notification category slug. You can get this from Notification Categories page on SuprSend dashboard -> Settings page

Body

application/json
​
preference
enum<string>

set opt_in to turn on notifications on all or selected channels by default, opt_out to turn-off notifications by default, cant_unsubscribe if you do not want users to completely opt-out from this category

Available options:
opt_in,
opt_out,
cant_unsubscribe
​
visible_to_subscriber
boolean

set it false to hide a category from user's preference page

​
mandatory_channels
string[]

Add mandatory channels that the user can't unsubscribe from if preference is cant_unsubscribe.

​
opt_in_channels
string[]

List of channels to opt-in for this category. Only applicable when preference is opt_in.

​
digest_schedule
object

Tenants can modify some parameters (time, weekdays, monthdays, dtstart, is_default) of existing digest schedules. Users will see merged digest-schedule options (original options + tenant-modified options merged by id).

​
properties
object[]

Override default values for category condition properties. Tenants can change the default value shown to their users.

Response

200

​
name
string
​
category
string
​
description
string | null
​
tags
string[] | null
​
effective_tags
string[] | null
​
root_category
enum<string>

Root category (system, transactional, or promotional) this sub-category belongs to.

Available options:
system,
transactional,
promotional
​
default_preference
enum<string>

Category-level default preference, inherited when the tenant has not overridden it.

Available options:
opt_in,
opt_out,
cant_unsubscribe
​
default_mandatory_channels
string[] | null

Category-level mandatory channels (applies when the default preference is cant_unsubscribe).

​
default_opt_in_channels
string[] | null

Category-level opt-in channels, used when only selective channels are opted in by default.

​
enabled_for_tenant
boolean

Whether the category is enabled for this tenant. When false, the category is hidden from the tenant's users and notifications are not sent in it.

​
visible_to_subscriber
boolean

Whether the category appears on the tenant users' preference page.

​
preference
enum<string> | null

Tenant's overridden preference for this category. null if the tenant has not overridden the category default.

Available options:
opt_in,
opt_out,
cant_unsubscribe
​
mandatory_channels
string[] | null

Channels the user cannot unsubscribe from (when preference is cant_unsubscribe), as overridden for this tenant.

​
opt_in_channels
string[] | null

Channels opted in by default for this category, as overridden for this tenant.

​
blocked_channels
string[] | null

Channels opted out across all categories for this tenant.

​
updated_at
string<date-time> | null

Timestamp when the tenant preference for this category was last updated.

​
digest_schedule
object

Digest schedule configuration with tenant overrides and original options

​
properties
object[] | null

Category condition properties with tenant overrides