Clarify that PUT to /api/subscribers/{id} without lists array removes all list memberships

[alanef]

Summary

When updating a subscriber via PUT /api/subscribers/{id}, omitting the lists array from the payload removes all list memberships. This behavior may be unexpected for API consumers who only want to update attributes.

Current Behavior

Subscriber has 3 list memberships
curl -X PUT /api/subscribers/123
-d '{"email": "user@example.com", "attribs": {"foo": "bar"}}'

Result: Subscriber now has 0 list memberships

Question

Is this the intended/expected behavior? If so, could a warning be added to the API documentation clarifying that:

1. PUT replaces the entire subscriber resource
2. Omitting lists is equivalent to setting lists: []
3. To preserve existing lists when updating attributes, callers must first fetch the subscriber and include the current list IDs in the PUT

Suggested Documentation Addition

Something like:

Warning: The lists field defaults to an empty array if not specified. To update subscriber attributes without modifying list memberships, you must include the current list IDs in your request.

Workaround

We now fetch the subscriber first and include existing list IDs in every PUT:

1. GET current subscriber
2. Extract list IDs from response
3. Include list IDs in PUT payload