---
title: "Update a subscription"
method: PUT
path: "/v1/projects/{projectID}/subscriptions/{subscriptionID}"
tags: ["Subscriptions"]
---

# Update a subscription

`PUT /v1/projects/{projectID}/subscriptions/{subscriptionID}`

This endpoint updates a subscription

## Path parameters

- `projectID` string, required
- `subscriptionID` string, required

## Request body

- ModelsUpdateSubscription
  - `alert_config` ModelsAlertConfiguration
    - `count` integer — Count
    - `threshold` string — Threshold
  - `app_id` string — Deprecated but necessary for backward compatibility
  - `delivery_mode` 'at_least_once' | 'at_most_once' | ''
  - `endpoint_id` string — Destination endpoint ID
  - `filter_config` ModelsFilterConfiguration
    - `event_types` string[] — List of event types that the subscription should match
    - `filter` ModelsFS
      - `body` DatastoreM, nullable
      - `headers` DatastoreM, nullable
      - `path` DatastoreM, nullable
      - `query` DatastoreM, nullable
  - `function` string — Convoy supports mutating your request payload using a js function. Use this field to specify a `transform` function for this purpose. See this[https://docs.getconvoy.io/product-manual/subscriptions#functions] for more
  - `name` string — Subscription Nme
  - `rate_limit_config` ModelsRateLimitConfiguration
    - `count` integer
    - `duration` integer
  - `retry_config` ModelsRetryConfiguration
    - `duration` string — Used to specify a valid Go time duration e.g 10s, 1h3m for how long to wait between event delivery retries
    - `interval_seconds` integer — Used to specify a time in seconds for how long to wait between event delivery retries,
    - `retry_count` integer — Used to specify the max number of retries
    - `type` 'linear' | 'exponential' | ''
  - `source_id` string — Source Id

## Response `202`

Accepted

- object
  - `message` string
  - `status` boolean
  - `data` ModelsSubscriptionResponse
    - `alert_config` DatastoreAlertConfiguration
      - `count` integer
      - `threshold` string
    - `created_at` string
    - `deleted_at` string, nullable
    - `delivery_mode` 'at_least_once' | 'at_most_once' | ''
    - `device_metadata` DatastoreDevice
      - `created_at` string
      - `deleted_at` string, nullable
      - `endpoint_id` string
      - `host_name` string
      - `last_seen_at` string
      - `project_id` string
      - `status` 'offline' | 'online' | 'disabled' | ''
      - `uid` string
      - `updated_at` string
    - `endpoint_metadata` DatastoreEndpoint
      - `advanced_signatures` boolean
      - `authentication` DatastoreEndpointAuthentication
        - `api_key` DatastoreApiKey
          - `header_name` string
          - `header_value` string
        - `basic_auth` DatastoreBasicAuth
          - `password` string
          - `username` string
        - `oauth2` DatastoreOAuth2
          - `audience` string
          - `authentication_type` 'shared_secret' | 'client_assertion' | ''
          - `client_id` string
          - `client_secret` string — Encrypted at rest
          - `expiry_time_unit` 'seconds' | 'milliseconds' | 'minutes' | 'hours' | ''
          - `field_mapping` DatastoreOAuth2FieldMapping
            - `access_token` string — Field name for access token (e.g., "accessToken", "access_token", "token")
            - `expires_in` string — Field name for expiry time (e.g., "expiresIn", "expires_in", "expiresAt")
            - `token_type` string — Field name for token type (e.g., "tokenType", "token_type")
          - `grant_type` string
          - `issuer` string
          - `scope` string
          - `signing_algorithm` string
          - `signing_key` DatastoreOAuth2SigningKey
            - `crv` string — EC (Elliptic Curve) key fields
            - `d` string — Private key (EC only)
            - `dp` string — RSA first factor CRT exponent (RSA private key only)
            - `dq` string — RSA second factor CRT exponent (RSA private key only)
            - `e` string — RSA public exponent (RSA only)
            - `kid` string — Key ID
            - `kty` string — Key type: "EC" or "RSA"
            - `n` string — RSA key fields
            - `p` string — RSA first prime factor (RSA private key only)
            - `q` string — RSA second prime factor (RSA private key only)
            - `qi` string — RSA first CRT coefficient (RSA private key only)
            - `x` string — X coordinate (EC only)
            - `y` string — Y coordinate (EC only)
          - `subject` string
          - `url` string
        - `type` 'api_key' | 'oauth2' | 'basic_auth' | ''
      - `cb_state` string, nullable — CBState is the circuit breaker state ("open", "half-open", "closed") so the UI can reflect a tripped breaker on the endpoint status. Nil when CB is off/unlicensed or has no sample for this endpoint.
      - `content_type` string
      - `created_at` string
      - `deleted_at` string, nullable
      - `description` string
      - `events` integer
      - `failure_count` integer, nullable
      - `failure_rate` number, nullable — FailureRate is the circuit breaker's rolling failure rate for this endpoint. It is a pointer so the API can return null when no rate was computed (circuit breaker feature off, or sampler not running), distinct from a genuine 0%.
      - `http_timeout` integer
      - `mtls_client_cert` DatastoreMtlsClientCert
        - `client_cert` string — ClientCert is the client certificate PEM string
        - `client_key` string — ClientKey is the client private key PEM string
      - `name` string
      - `owner_id` string
      - `period_failure_rate` number, nullable — PeriodFailureRate is the period failure rate from event_deliveries, (Failure+Retry)/(Success+Failure+Retry). Retry counts as failed-so-far. Nil when the range has no counted deliveries; sibling counts are transient.
      - `project_id` string
      - `rate_limit` integer
      - `rate_limit_duration` integer
      - `retry_count` integer, nullable
      - `secrets` DatastoreSecret[]
        - `created_at` string
        - `deleted_at` string, nullable
        - `expires_at` string, nullable
        - `uid` string
        - `updated_at` string
        - `value` string
      - `slack_webhook_url` string
      - `status` 'active' | 'inactive' | 'paused' | ''
      - `success_count` integer, nullable
      - `support_email` string
      - `uid` string
      - `updated_at` string
      - `url` string
    - `filter_config` DatastoreFilterConfiguration
      - `event_types` string[]
      - `filter` DatastoreFilterSchema
        - `body` DatastoreM, nullable
        - `headers` DatastoreM, nullable
        - `is_flattened` boolean
        - `path` DatastoreM, nullable
        - `query` DatastoreM, nullable
    - `function` string, nullable
    - `name` string
    - `project_id` string
    - `rate_limit_config` DatastoreRateLimitConfiguration
      - `count` integer
      - `duration` integer
    - `retry_config` DatastoreRetryConfiguration
      - `duration` integer
      - `retry_count` integer
      - `type` 'linear' | 'exponential' | ''
    - `source_metadata` DatastoreSource
      - `body_function` string, nullable
      - `created_at` string
      - `custom_response` DatastoreCustomResponse
        - `body` string
        - `content_type` string
      - `deleted_at` string, nullable
      - `event_type_location` string
      - `forward_headers` string[]
      - `header_function` string, nullable
      - `idempotency_keys` string[]
      - `is_disabled` boolean
      - `mask_id` string
      - `name` string
      - `project_id` string
      - `provider` 'github' | 'twitter' | 'shopify' | ''
      - `provider_config` DatastoreProviderConfig
        - `twitter` DatastoreTwitterProviderConfig
          - `crc_verified_at` string, nullable
      - `pub_sub` DatastorePubSubConfig
        - `amqp` DatastoreAmqpPubSubConfig
          - `auth` DatastoreAmqpCredentials
            - `password` string
            - `user` string
          - `bindedExchange` string, nullable
          - `deadLetterExchange` string, nullable
          - `host` string
          - `port` string
          - `queue` string
          - `routingKey` string
          - `schema` string
          - `vhost` string, nullable
        - `google` DatastoreGooglePubSubConfig
          - `project_id` string
          - `service_account` string, byte — encoding/json marshals []byte as a base64 string on the wire.
          - `subscription_id` string
        - `kafka` DatastoreKafkaPubSubConfig
          - `auth` DatastoreKafkaAuth
            - `hash` string
            - `password` string
            - `tls` boolean
            - `type` string
            - `username` string
          - `brokers` string[]
          - `consumer_group_id` string
          - `topic_name` string
        - `sqs` DatastoreSQSPubSubConfig
          - `access_key_id` string
          - `default_region` string
          - `endpoint` string — Optional: for LocalStack testing
          - `queue_name` string
          - `secret_key` string
        - `type` 'sqs' | 'google' | 'kafka' | 'amqp' | ''
        - `workers` integer
      - `type` 'http' | 'rest_api' | 'pub_sub' | 'db_change_stream' | ''
      - `uid` string
      - `updated_at` string
      - `url` string
      - `verifier` DatastoreVerifierConfig
        - `api_key` DatastoreApiKey
          - `header_name` string
          - `header_value` string
        - `basic_auth` DatastoreBasicAuth
          - `password` string
          - `username` string
        - `hmac` DatastoreHMac
          - `encoding` 'base64' | 'hex' | ''
          - `hash` string
          - `header` string
          - `secret` string
        - `type` 'noop' | 'hmac' | 'basic_auth' | 'api_key' | ''
    - `type` 'cli' | 'api' | ''
    - `uid` string
    - `updated_at` string

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found

---

[API](https://skmtc.net/frain-dev/apis/convoy-api-reference.md) · [All operations](https://skmtc.net/frain-dev/apis/convoy-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/frain-dev/convoy-api-reference/versions/dbd5b4f9cf13/schema)