referrals

Invocation#

echo-cli referrals list --product <id>
echo-cli referrals set --product <id> --event <event-name> --reward <text> --by <name>
echo-cli referrals qualify --product <id>

Inputs and output#

list writes programme (product_id, qualifying_event, reward, set_by, set_at, or null when none is set) and referrals, newest first: id, product_id, code, referrer, referred, recorded_at, qualified_at and reward (both null until it qualifies). set writes the programme; qualify writes qualified, the referrals it qualified now.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/referrals with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Referral programme section of the tracking screen and of Echo Desktop's GEO screen calls the same operations, and echo-mcp reads the programme (echo_list_referrals). A signed-in user gets one code per product from GET /api/public/referrals?product_id=<id> and is referred with POST /api/public/referrals { code }, once per product. A referral is refused when the identity edges (see tracking identity show) link referrer and referred, naming the identifier they share. qualify resolves each open referral's referred user to every linked identifier, and when the programme's event is among their stored events, marks it qualified with the programme's reward; a referral qualifies once, so a second run grants nothing more. Echo Web also qualifies every product's open referrals daily at /api/cron/referrals-qualify (04:03 UTC), as qualify does, answering each product's qualified referrals or the error that stopped it.

Refusals#

• A wrong invocation is refused before anything is sent: "referrals takes <every verb's usage, separated by semicolons>; got <word>", "referrals <verb> does not take <flag>; it takes …", "<flag> needs a value" and "referrals <verb> needs <flag>" for each flag the verb needs.
• Echo Web answers a bad request with "product_id is required: …", "qualifying_event is required: the stored event a referred user must send to qualify", "reward is required: what the referrer earns for each qualified referral" or "set_by is required: an internal caller has no signed-in user, so it names who is acting"; not found with "no product has id <id>; echo-cli products lists the ones that exist" or "product <id> runs no referral programme; echo-cli referrals set starts one". The command prints Echo Web's sentence and exits non-zero.
• The signed-in endpoint answers unauthorized with "sign in first: referral codes and referrals belong to signed-in users", not found with "no referral code <code> exists", a conflict with "you were already referred to this product at <time>", and a bad request with "this referral resolves to the referrer's own identity: both are known as <identifier>".