promos

Invocation#

echo-cli promos list
echo-cli promos floor --price <stripe-price-id> --unit-cost <minor-units> --floor <percent> --by <name>
echo-cli promos create --price <stripe-price-id> --code <text> (--percent-off <percent> | --amount-off <minor-units>) [--max-uses <count>] [--expires <ISO time>] [--once-per-customer true|false] --by <name>
echo-cli promos deactivate --id <promo-code-id> --by <name>

Inputs and output#

list writes floors (price_id, unit_cost, currency, floor_percent, set_by, set_at) and codes, newest first: id, price_id, code, percent_off, amount_off, max_redemptions, expires_at, once_per_customer, margin_percent, stripe_coupon_id, stripe_promotion_code_id, created_by, created_at, deactivated_by, deactivated_at, and redemptions and active as Stripe answers them now. floor writes the floor; create and deactivate write the code.

State effect#

Every verb calls Echo Web's authenticated /api/analytics/promos with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; Echo Web reaches Stripe with its STRIPE_SECRET_KEY. The Promo codes section of the tracking screen and of Echo Desktop's GEO screen call the same operations, and echo-mcp lists floors and codes (echo_list_promos) and turns a code off (echo_promo_deactivate). The floor is a percent of the discounted price: create reads the price's unit amount from Stripe, takes the discount off it, and measures (discounted price − unit cost) ÷ discounted price. Only a code that keeps the floor reaches Stripe, as a coupon limited to the price's product and a promotion code with the use limit and expiry given. list asks Stripe for every code's promotion code each time — times_redeemed and active — and stores neither; deactivate sets the promotion code inactive in Stripe and records who did it and when (promo_codes.deactivated_by, deactivated_at). A code's redemptions are also counted per social post it was handed to (echo-cli social codes).

Refusals#

• A wrong invocation is refused before anything is sent: "promos takes <every verb's usage, separated by semicolons>; got <word>", "promos <verb> does not take <flag>; it takes …", "<flag> needs a value", "promos <verb> needs <flag>" for each flag the verb needs, "<field> must be a number; got <value>" for a numeric flag, and "--once-per-customer takes true or false: whether one person may redeem the code only once; got <value> (<reason>)".
• A code created with --once-per-customer true gets its shared Stripe promotion code turned off from the start, so nobody can type it: it is redeemed only through the personal promotion codes Echo issues when a product checks its user (echo-cli pricing codes), each bound to one Stripe customer and redeemable once. list counts such a code's redemptions over its personal codes and shows it active until deactivate, which also turns every personal code off. Echo Web refuses once_per_customer that is not true or false with "once_per_customer must be true or false: whether one person may redeem the code only once; got <value>", and deactivate fails naming the personal code Stripe could not turn off: "Stripe could not turn off the personal promotion code <id> of <code> held by <user>: <Stripe's message>".
• Echo Web answers a bad request with "price_id is required: …", "code is required: …", "<field> must be a number of at least 0: …", "floor_percent must be below 100; got <value>", "give exactly one of percent_off (a percent of the price) and amount_off (minor units of its currency)", "max_redemptions must be a whole number of at least 1; got <value>", "expires_at must be an ISO time in the future; got <value>", "price <id> has no fixed unit amount, so no margin can be measured on it", "the discount leaves price <id> at <amount> <currency>, which is no sale; the margin floor is <floor>%" or "the code would leave a <margin>% margin on price <id>, below its margin floor of <floor>%"; not found with "price <id> has no margin floor; echo-cli promos floor sets its unit cost and floor first" or "Stripe has no price <id> this account can read: <Stripe's message>"; and a conflict with "the code <code> already exists as promo <id>". The command prints Echo Web's sentence and exits non-zero.
• deactivate is refused with "deactivate is required: the promo code to turn off, as echo-cli promos list shows it", not found with "no promo code has id <id>", and a conflict with "the code <code> was deactivated by <name> at <time>". Stripe failing is the error "Stripe could not turn off promotion code <id> (<code>): <Stripe's message>", and list fails with "Stripe could not answer for promotion code <id> (<code>): <Stripe's message>" rather than print a stale count.