Update a topic subscription

Update a subscription by its unique identifier subscriptionIdOrIdentifier for a topic. You can update the preferences and name associated with the subscription.

PATCH
/v2/topics/{topicKey}/subscriptions/{subscriptionIdOrIdentifier}

Authorization

Authorization<token>

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

In: header

Request Body

application/jsonRequired
namestring

The name of the subscription

preferencesarray<string | object | object>

The preferences of the topic. Can be a simple workflow ID string, workflow preference object, or group filter object

Path Parameters

topicKeyRequiredstring

The key identifier of the topic

subscriptionIdOrIdentifierRequiredstring

The unique identifier of the subscription

Header Parameters

idempotency-keystring

A header for idempotency purposes

Response Body

OK

_idRequiredstring

The unique identifier of the subscription

identifierstring

The identifier of the subscription

namestring

The name of the subscription

topicRequiredobject

The topic information

subscriberRequiredobject

The subscriber information

preferencesarray<object>

The preferences for workflows in this subscription

createdAtRequiredstring

The creation date of the subscription

updatedAtRequiredstring

The last update date of the subscription

export interface Response {
  /**
   * The unique identifier of the subscription
   */
  _id: string;
  /**
   * The identifier of the subscription
   */
  identifier?: string;
  /**
   * The name of the subscription
   */
  name?: string;
  /**
   * The topic information
   */
  topic: TopicDto;
  /**
   * The subscriber information
   */
  subscriber: SubscriberDto;
  /**
   * The preferences for workflows in this subscription
   */
  preferences?: SubscriptionPreferenceDto[];
  /**
   * The creation date of the subscription
   */
  createdAt: string;
  /**
   * The last update date of the subscription
   */
  updatedAt: string;
}
export interface TopicDto {
  /**
   * The internal unique identifier of the topic
   */
  _id: string;
  /**
   * The key identifier of the topic used in your application. Should be unique on the environment level.
   */
  key: string;
  /**
   * The name of the topic
   */
  name?: string;
}
export interface SubscriberDto {
  /**
   * The identifier of the subscriber
   */
  _id: string;
  /**
   * The external identifier of the subscriber
   */
  subscriberId: string;
  /**
   * The avatar URL of the subscriber
   */
  avatar?: string | null;
  /**
   * The first name of the subscriber
   */
  firstName?: string | null;
  /**
   * The last name of the subscriber
   */
  lastName?: string | null;
  /**
   * The email of the subscriber
   */
  email?: string | null;
}
export interface SubscriptionPreferenceDto {
  /**
   * The unique identifier of the subscription
   */
  subscriptionId: string;
  /**
   * Workflow information if this is a template-level preference
   */
  workflow?: WorkflowDto;
  /**
   * Whether the preference is enabled
   */
  enabled: boolean;
  /**
   * Optional condition using JSON Logic rules
   */
  condition?: {
    [k: string]: unknown;
  };
}
export interface WorkflowDto {
  /**
   * Unique identifier of the workflow
   */
  id: string;
  /**
   * Workflow identifier used for triggering
   */
  identifier: string;
  /**
   * Human-readable name of the workflow
   */
  name: string;
  /**
   * Whether this workflow is marked as critical
   */
  critical: boolean;
  /**
   * Tags associated with the workflow
   */
  tags?: string[];
  /**
   * Custom data associated with the workflow
   */
  data?: {};
  /**
   * Severity of the workflow
   */
  severity: "high" | "medium" | "low" | "none";
}
 
curl -X PATCH "https://api.novu.co/v2/topics/string/subscriptions/string" \
  -H "idempotency-key: string" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Subscription",
    "preferences": [
      {
        "workflowId": "workflow-123",
        "condition": {
          "===": [
            {
              "var": "tier"
            },
            "premium"
          ]
        }
      }
    ]
  }'
{
  "_id": "64f5e95d3d7946d80d0cb679",
  "identifier": "tk=product-updates:si=subscriber-123",
  "name": "My Subscription",
  "topic": {
    "_id": "64f5e95d3d7946d80d0cb677",
    "key": "product-updates",
    "name": "Product Updates"
  },
  "subscriber": {
    "_id": "64da692e9a94fb2e6449ad07",
    "subscriberId": "user-123",
    "avatar": "https://example.com/avatar.png",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]"
  },
  "preferences": [
    {
      "subscriptionId": "64f5e95d3d7946d80d0cb679",
      "workflow": {
        "id": "64a1b2c3d4e5f6g7h8i9j0k1",
        "identifier": "welcome-email",
        "name": "Welcome Email Workflow",
        "critical": false,
        "tags": [
          "user-onboarding",
          "email"
        ],
        "data": {
          "category": "onboarding",
          "priority": "high"
        },
        "severity": "high"
      },
      "enabled": true,
      "condition": {
        "and": [
          {
            "===": [
              {
                "var": "tier"
              },
              "premium"
            ]
          }
        ]
      }
    }
  ],
  "createdAt": "2025-04-24T05:40:21Z",
  "updatedAt": "2025-04-24T05:40:21Z"
}

On this page

No Headings
Edit this page on GitHub