Subscription API - Update

Use this endpoint to update an existing subscription. You can update the name, group assignment, preference page access, display names, and display descriptions.

---

Endpoint

PATCH https://e1.envoke.com/v2/subscriptions/{ID}

Replace {ID} with the Envoke subscription ID you want to update. Authentication is via HTTP Basic Auth using your API ID and API Key. The request body must be JSON.

---

Request Body

At least one field must be provided.

Field	Type	Description
name	string	New subscription name.
group	string or integer	Group name or group ID to assign. Pass "" (empty string) or null to remove the group assignment.
prefpage_access	string	Preference page visibility: "public" or "private". Setting to "private" requires the private subscriptions feature.
display_names	object	Translated display labels keyed by ISO language code.
display_descriptions	object	Translated descriptions keyed by ISO language code.

external_id is silently ignored if included in the request body. If id is included, it must match the {ID} in the URL — if they differ, a validation error is returned: "Provided 'id': {url_id} does not match 'id' in request body ({body_id})".

---

Response

On success, the API returns the updated subscription object:

{
  "success": true,
  "result_text": "Updated",
  "result_data": {
    "id": "12",
    "external_id": "a1b2c3d4e5f6",
    "name": "Campus Weekly (Updated)",
    "group": "Student Communications",
    "prefpage_access": "public",
    "display_names": { "en": "Campus Weekly", "fr": "Campus hebdo" },
    "display_descriptions": { "en": "Updated description.", "fr": "" }
  }
}

---

Validation Errors

{
  "success": false,
  "result_text": "Validation failed, see 'result_data' -> 'errors'",
  "result_data": {
    "errors": [
      "Item with id '999999' not found"
    ]
  }
}

Common errors:

Error	Cause
Request body may not be empty	No JSON body was provided.
Item with id '{id}' not found	The {ID} in the URL does not match any subscription in your account.
Invalid 'group': '{value}'	The group was not found or is not of type subscription.
'prefpage_access' must be 'public' or 'private'	An unrecognised value was provided for prefpage_access.
Setting 'prefpage_access' to 'private' requires the private subscriptions feature	The account does not have the private subscriptions feature enabled.
Provided 'id': {url_id} does not match 'id' in request body ({body_id})	id in the request body differs from {ID} in the URL.

---

Examples

Rename a subscription

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Campus Weekly (Updated)"}' \
  "https://e1.envoke.com/v2/subscriptions/12"

Assign to a group

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group": "Student Communications"}' \
  "https://e1.envoke.com/v2/subscriptions/12"

Remove group assignment

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"group": ""}' \
  "https://e1.envoke.com/v2/subscriptions/12"

Update display names

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_names": {"en": "Campus Weekly", "fr": "Campus hebdo"}}' \
  "https://e1.envoke.com/v2/subscriptions/12"

Update display descriptions

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_descriptions": {"en": "Updated description for the weekly newsletter."}}' \
  "https://e1.envoke.com/v2/subscriptions/12"

Update multiple fields at once

curl -X PATCH -gs \
  -u "$API_ID:$API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "Campus Weekly (2025)", "group": "Student Communications", "display_names": {"en": "Campus Weekly 2025"}}' \
  "https://e1.envoke.com/v2/subscriptions/12"

---

Note: The curl examples above are formatted for readability. All requests must use properly encoded URLs.

Full reference, OpenAPI description, and Postman collection: developers.envoke.com.