client-lifecycle

Call add_client with the inbound IDs, a unique email label, total_gb in gigabytes, and expiry_time as a Unix timestamp in milliseconds. A seconds-precision timestamp lands in 1970 and expires the client immediately, so always compute from now in milliseconds.

Use bulk_adjust_clients with a list of emails and add_days or add_gb deltas, which may be negative. Clients with unlimited expiry or traffic are skipped with reasons, so read the skipped list back rather than reporting a clean success.

A negative expiryTime stores a duration rather than a date, creating a start-after-first-use trial. The panel converts it to an absolute deadline of now plus the duration on the client's first traffic tick, so a 7-day trial starts whenever the user first connects.

It deletes only clients with reset equal to zero whose quota is exhausted or whose expiry has passed. Clients on a reset cycle, unlimited clients, and unstarted trials are never touched, so cyclical accounts survive cleanup runs.

Prefer the subscription URL from get_subscription_links, because the user's app refreshes it and picks up new inbounds or host changes automatically. Raw links from get_all_inbound_links suit one-off sharing, and both carry credentials so treat them as secrets.

Rebuilding a client with delete_client plus add_client issues a new UUID, which invalidates the user's existing configuration. Use update_client instead, which overlays only the fields passed and preserves the UUID and all other settings.