# 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:

```json
{
  "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

```json
{
  "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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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

```bash
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](https://developers.envoke.com).*