client-lifecycle

Client lifecycle

Clients in 3x-ui are email-keyed entities, not properties of an inbound: one client can be attached to several inbounds and moved between them without being recreated. email is just a unique label — it need not be an address.

Units, which cause most of the mistakes

Field	Unit
expiry_time (tool parameter)	Unix milliseconds. 0 = never
expiryTime (stored)	Same. A negative value is a duration, not a date — "start after first use"
total_gb (tool parameter)	GB, converted for you
totalGB (stored)	Bytes, despite the name
limit_ip	Simultaneous source IPs. 0 = unlimited
reset	Traffic reset cycle in days. 0 = no cycle

A seconds-precision timestamp passed as expiry_time lands in 1970 and the client is born expired. When someone asks for "30 days", compute from now in milliseconds.

Negative expiry is the right tool for prepaid trials. Store the duration as a negative number of milliseconds and the panel converts it to an absolute deadline of now + duration on the client's first traffic tick — so a 7-day trial handed out in March still gives seven days to someone who first connects in June. The conversion is computed once per email, so a client attached to several inbounds lands on one consistent deadline.

Onboarding

add_client inbound_ids=[7] email="alice" total_gb=100 expiry_time=<now+30d in ms> limit_ip=3

The UUID is generated by the panel when omitted — do not invent one. For Trojan/Shadowsocks the panel generates the key server-side the same way.

sub_id groups clients under one subscription URL: clients sharing a sub_id share a subscription. Give each user their own unless you deliberately want a shared link. group is a free label the client-group tools operate on later, and is worth setting at creation — retrofitting groups across hundreds of clients is the tedious version of the same job.

For many at once, bulk_create_clients creates across the same inbounds, and bulk_attach_clients attaches existing clients to more inbounds afterwards.