Subscription ID — subid

What it solves. When you hand a user a new subscription URL — a domain migration, a re-issued token, a move to another panel — the app has no way to tell it is the same subscription. It adds a second entry and the user ends up with two copies of the same thing.

Send a subid and that stops happening: the app treats a matching subid as the same subscription, replaces its URL with the new one and refreshes its servers in place.

Where it can come from (any one — same rules as the other metadata)

1. HTTP header — subid: my-sub-42
2. Body comment — a line #subid: my-sub-42 in the subscription body
3. URL query — …?subid=my-sub-42

An HTTP header wins over a body comment, which wins over the URL. Format: letters, digits, -, _ and spaces ([A-Za-z0-9 _-]+). Anything else is ignored — the value is simply not stored.

Situation	What the app does
Same URL already added	Updates that subscription (unchanged behaviour)
New URL, subid matches an existing subscription	Updates that one: new URL + fresh servers, keeps the user's custom name
New URL, subid is new or absent	Adds a new subscription (unchanged behaviour)

subid is optional. Without it everything works exactly as before — duplicates are detected by URL only. Sending it is simply a way to keep control of your users' entries when your addresses change.

Pick a value that never changes for a given user's subscription. It doesn't have to be secret — it is only compared with what the app already has — but it must be stable and unique per subscription. A UUID or your internal subscription id are both fine.

Example

subid: 8f3a91c2-4b77-4c1e-9a02-5e6d1f0b7c33

Available on all platforms: iOS, Android, macOS, Windows, Linux and Apple TV.