What Problem This API Solves

In today's retail SaaS world deeply coupled with the WeChat ecosystem, answering "is the same WeChat user one person or several across official accounts, mini-programs, and malls" is almost a must for every integration project. Youzan Cloud's "User union_id Query" API exists precisely for this: it first uses the main API to paginate and pull a customer list by time window, then uses a lookup API to fetch each customer's WeChat union_id and open_id, ultimately delivering a "WeChat-aware" customer master data record for cross-system user unification and member master data synchronization.

API Capability Overview

System: Youzan Cloud SCRM.
Main API: /youzan.scrm.customer.list.1.0.0, GET, paginates customers by created_at_start / created_at_end (second-level timestamps), default page size 50; business data lives in data.record_list, pagination key is page_no.
Lookup API: /youzan.user.weixin.openid.get.3.0.0, takes yz_open_id from the main record as input and returns union_id and open_id merged back into the main record.
Authentication: Youzan Cloud Open Platform OAuth (app-level access_token); in multi-tenant private deployments, credentials must be configured per tenant.
Incremental Mode: The typical approach is to use {{LAST_SYNC_TIME}} and {{CURRENT_TIME}} as a rolling time window based on created_at; you can also apply has_mobile=true to filter out invalid records.
Strategy Type: QUERY_ONLY, read-only, usually acts as the preparation stage for downstream write APIs.

Typical Field Mappings

Field Name	Type	Meaning	Practical Notes
yz_open_id	string	Youzan user unique identifier; serves as both primary key and lookup input	Bind to `id` in metadata; records with empty or invalid values should be discarded
show_name	string	User nickname / display name	Bind to `number` in metadata; used for business display
union_id	string	WeChat Open Platform unified user identifier	Key for cross-app unification; requires the mall to be bound to a verified service account
open_id	string	WeChat user identifier within the current app	Returned alongside union_id; varies across apps
mobile	string	Mobile phone number	Combine with `is_mobile_auth` for deduplication and authenticity checks
gender	string	Gender enum (0/1/2)	Pass-through; watch out for enum differences
is_member	string	Whether a member	Combined with `created_member_at`, distinguishes member lifecycle stages
trade_count	string	Cumulative transaction count	Used for member tier determination
created_at	string	Customer creation time (seconds)	Time anchor field for incremental sync
created_member_at	string	Member creation time (seconds)	Suggested time window for member-related downstream
is_mobile_auth	string	Whether mobile is verified	Data quality flag, affects downstream reachability
points	string	Points balance	Often passed as string in the Qeasy platform

How to Configure on Qeasy

On the Qeasy Data Integration Platform, this strategy is usually modeled as a "QUERY_ONLY source strategy + lookup sub-flow". On the source side, select the "Youzan Cloud SCRM" adapter, configure the paginator with page_no / page_size and time-window variables. The lookup node is attached after the main loop, with both detailkey1 and detailkey2 set to yz_open_id, and the response fields union_id and open_id are written back. Qeasy's field mapper automatically binds id to yz_open_id and number to show_name based on metadata, and maps to the downstream OtOCustomer's CustomerId / Name / MobilePhone / Unionid. Time-window variables {{LAST_SYNC_TIME}} and {{CURRENT_TIME}} can be referenced directly from Qeasy's scheduling context, eliminating the need for handwritten scripts.

Cross-Solution Practical Highlights

"Main API + Lookup" is the norm: don't try to get union_id from a single API; always split into two steps—list first, then lookup—or fields will be lost.
Time window is the lifeline of incremental sync: created_at is the preferred anchor; if a customer was created before system onboarding, set a fixed created_at_start fallback so historical data is not permanently missed.
Binding status decides whether union_id exists: customers without a verified service account or unfinished WeChat authorization may return empty lookups; handle nulls at the mapping layer instead of throwing errors.
Balance between pagination and rate limiting: default page_size=50 is stable under multi-customer concurrency; you can raise it to 100 in Qeasy, but pair it with Youzan Cloud QPS rate-limiting backoff.
Primary key stability trumps everything: yz_open_id is the only reliable identifier in this dataset; do not use mobile or show_name as dedup keys downstream—they collide easily.
Pure query strategies should reserve a downstream write slot: QUERY_ONLY itself does not write the target system; in real projects it is typically followed by an EXECUTE strategy that writes OtOCustomer. Wire them together with depends_on into an ordered chain.

Pitfall Retrospective

Pitfall 1: A whole batch fails because union_id is empty. In one integration, a customer had not completed WeChat authorization, so the lookup returned null; the upstream script threw an error without handling nulls, breaking the entire batch. The safe approach is to set "null-tolerant + default empty string" on union_id in Qeasy's field mapper and let downstream decide whether to write.
Pitfall 2: Time window drifts across time zones. created_at is a second-level timestamp but Youzan Cloud stores it in UTC+8; in UTC projects, {{CURRENT_TIME}} without time-zone conversion will miss same-day data. The recommendation is to explicitly add +8h using Qeasy's localized time helper.
Pitfall 3: Misconfigured pagination key. Treating the response's total as the loop termination condition while the actual termination signal is page_no and empty page causes an infinite loop. The safe approach is "page number + empty list" double termination.
Pitfall 4: Inconsistent mobile number format. Youzan Cloud may return mobile numbers as plain text, with area code, or partially masked; normalize them with a field converter in Qeasy before writing downstream.
Pitfall 5: Cross-tenant token reuse. In private deployments with multiple customers sharing one integration config, mixing up access_tokens will trigger auth failures. Always maintain credentials per tenant in Qeasy's tenant dimension.

When to Use

This API is suitable for scenarios that need to unify Youzan customers with WeChat ecosystem users—such as member middle platforms, cross-channel user profiles, and unified authentication. It is not suitable for scenarios that simply need to sync mobile numbers without WeChat identity; in those cases, direct SCRM customer sync is lighter.

Youzan Cloud User union_id Query API Field Manual: A Practical Guide from Customer List to WeChat union_id Lookup