affiliates

Invocation#

echo-cli affiliates programme --app <web source> --parameter <link parameter> --by <name>
echo-cli affiliates list --app <web source>
echo-cli affiliates add --app <web source> --code <code> --name <text> --share <fraction> --by <name>
echo-cli affiliates statement --affiliate <affiliate-id> --from <iso-time> --to <iso-time>
echo-cli affiliates settle --affiliate <affiliate-id> --from <iso-time> --to <iso-time> --by <name>
echo-cli affiliates settlements --affiliate <affiliate-id>

Inputs and output#

programme writes the programme (app_id, parameter, created_by, created_at). list writes programme and affiliates (id, app_id, code, name, commission_share, created_by, created_at). add writes the affiliate. statement writes affiliate_id, code, period_start, period_end, visitors, payers, revenue and commission (per currency) and event_ids; settle writes the same stored, with id, settled_by and settled_at; settlements writes them newest period first.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/affiliates with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Affiliates section of the tracking screen and of Echo Desktop's GEO screen call the same operation, and echo-mcp reads programmes and settlements as echo_affiliates. An affiliate link carries ?<parameter>=<code> to a page of the web source; the visitors it sent are the identifiers whose first stored page view carrying the parameter held its code. Their revenue is every stored event of theirs and of every identifier linked to them with a positive revenue and a currency, at or after that view and inside [--from, --to), each event once, summed per currency and never converted; the commission is that revenue times the share. statement stores nothing; settle stores it in affiliate_settlements. The parameter of a programme with affiliates is not changed under them. Paying the commission is left to the payout path, which reads the stored settlement.

Refusals#

• A wrong invocation is refused before anything is sent: "affiliates takes <every verb's usage, separated by semicolons>; got <word>", "affiliates <verb> does not take <flag>; it takes …", "<flag> needs a value", "affiliates <verb> needs <flag>" and "--share takes the fraction of attributed revenue the affiliate earns; got <value>".
• Echo Web answers a bad request with "app_id is required: …", "parameter is required: …", "code is required: …", "name is required: …", "commission_share must be a fraction above 0 and at most 1 of the revenue attributed to the affiliate; got <value>", "affiliate_id is required: …", "period_start must be an ISO 8601 instant: …", "period_end must be an ISO 8601 instant: …" or "period_end <instant> must come after period_start <instant>"; not found with "<source> has no affiliate programme; echo-cli affiliates programme --app <source> --parameter <name> sets one" or "no affiliate has id <id>; echo-cli affiliates list --app <source> shows them"; and a conflict with "<source> already has affiliate <name> with code <code>, <id>", "<source>'s affiliates are attributed by <parameter>; their links would stop counting under <parameter>" or "affiliate <code> is already settled for <start> to <end> as <id>; a period overlapping it would pay its revenue twice". The command prints Echo Web's sentence and exits 1.