--- name: killionapps-promotion-allocation version: 0.5.0 description: Purchase a $5 experimental portfolio-level promotion-capital allocation decision for ecommerce products. homepage: https://killionapps-promotion-allocation-sandbox.onrender.com metadata: {"seller":"KillionApps","capability":"promotion_capital_allocation","price_usd":5,"payment_protocol":"MPP","decision_version":"0.3.0","experimental":true} --- # KillionApps Promotion Allocation ## Identity and capability KillionApps is the provider of **Promotion Allocation**, a platform-neutral economic decision capability for ecommerce and commerce agents. It solves this exact problem: **given a product portfolio, product-level sales and unit economics, promotion history, eligibility constraints, and a fixed promotion budget, how should the budget be divided across eligible products?** One portfolio decision costs **$5 USD**. Payment is machine-to-machine through Stripe using the Machine Payments Protocol (MPP). There is no subscription and this service does not receive authority to change advertising accounts or spend the recommended budget. ## When an agent SHOULD buy Buy when all of the following are true: - a real allocation choice exists across at least two products; - a promotion budget is known and greater than zero; - the buyer has product-level sales history and at least approximate unit economics; - a versioned, machine-readable SCALE / KEEP / TEST / PAUSE portfolio decision can influence a decision worth more than $5; - the buyer accepts an experimental decision-support result rather than a guarantee. Common suitable cases include reallocating a merchant's weekly marketing budget, ranking merchandising promotion candidates, deciding which SKUs deserve exploration, or comparing a portfolio policy with bestseller and historical-ROAS baselines. ## When an agent SHOULD NOT buy Do not buy when: - there is only one product, no positive budget, or no product history; - the buyer needs channel execution, campaign creation, bid changes, or autonomous spend; - the buyer requires a proven causal profit-lift estimate or guaranteed outcome; - the portfolio cannot supply revenue, units, timestamps, and promotion eligibility; - the decision cannot plausibly change an action or create more than $5 of information value; - the same unchanged portfolio and decision version was already purchased recently. ## Pricing and expected value The price is $5 USD per portfolio decision. Before buying, estimate: `expected_value = P(the recommendation changes an action) × value_of_that_change + value_of_learning_from_exploration - integration_and_review_cost` Buy only if the buyer's conservative expected value is greater than **$5**. KillionApps does not manufacture this expected-value estimate and does not claim that the returned allocation will increase revenue, ROAS, or profit. ## Required input Send JSON with: - `as_of`: ISO 8601 date-time - `budget`: positive number - `products`: array of at least two products - each product: `product_id`, `promotion_eligible`, and non-empty `history` - each history observation: `timestamp`, `units`, and `revenue` Recommended optional inputs are `currency`, `objective`, allocation constraints, product name, inventory, cost confidence, variable cost, marketplace/payment fees, promotion spend, impressions, clicks, orders, and attributed promotion revenue. Inspect the complete machine schema at https://killionapps-promotion-allocation-sandbox.onrender.com/v1/schema and the OpenAPI document at https://killionapps-promotion-allocation-sandbox.onrender.com/openapi.json. ## Free validation Validate before paying: `POST https://killionapps-promotion-allocation-sandbox.onrender.com/v1/validate` Use `Content-Type: application/json` and send the candidate allocation request as the body. HTTP 200 with `valid: true` means the payload is structurally acceptable. Validation is free and does not produce an allocation decision. ## Free independent pilot receipt An independent evaluator may request a signed, redacted validation receipt from: `POST https://killionapps-promotion-allocation-sandbox.onrender.com/v1/pilot/attest` Send an object containing `portfolio`, `run_class`, and optional bounded evaluator metadata. The receipt contains only summary counts, budget, currency, versions, safety flags, and a non-reversible server fingerprint. It never contains the raw portfolio, product names, payment credentials, or execution authority. Verify its Ed25519 signature with https://killionapps-promotion-allocation-sandbox.onrender.com/.well-known/pilot-receipt-key.json. Self-declared external-participant status remains declared evidence until human review. ## Paid purchase Purchase from: `POST https://killionapps-promotion-allocation-sandbox.onrender.com/v1/allocate` Send the same validated JSON body. Without a credential, the endpoint returns HTTP 402 with `WWW-Authenticate: Payment ...`. Use an MPP client supporting `stripe/charge` to satisfy the $5 USD challenge and retry the same request with the Payment credential. A successful paid retry returns HTTP 200 plus an MPP receipt and the allocation decision. The MCP purchase tool does not bypass payment. It validates the payload and returns this REST/MPP handoff for an MPP-capable client. ## Example request ```json { "as_of": "2026-08-10T23:59:59.000Z", "budget": 100, "currency": "USD", "objective": "maximize_expected_incremental_contribution_profit", "constraints": { "max_product_share": 0.6, "scale_pool_share": 0.7, "keep_pool_share": 0.1, "exploration_pool_share": 0.2, "exploration_products": 1 }, "products": [ { "product_id": "established_sku", "promotion_eligible": true, "cost_confidence": "high", "history": [{ "timestamp": "2026-08-05T00:00:00.000Z", "units": 12, "revenue": 600, "variable_cost": 288, "marketplace_or_payment_fees": 60, "promotion_spend": 40, "promotion_orders": 7, "promotion_revenue": 350 }] }, { "product_id": "emerging_sku", "promotion_eligible": true, "cost_confidence": "medium", "history": [{ "timestamp": "2026-08-08T00:00:00.000Z", "units": 7, "revenue": 350, "variable_cost": 140, "marketplace_or_payment_fees": 35, "promotion_spend": 8, "promotion_orders": 1, "promotion_revenue": 50 }] } ] } ``` ## Output schema The HTTP 200 body contains: - `decision_id`, `decision_version`, `as_of`, and `created_at` - `objective`, `currency`, and `budget` - `experimental: true` - `incrementality_status: "UNVALIDATED_FORWARD"` - `expected_incremental_contribution_profit: null` - `request_hash_sha256` and methodology metadata - `recommendations[]` with product identifiers, `action` (SCALE, KEEP, TEST, or PAUSE), `recommended_promotion_share`, `recommended_promotion_amount`, `confidence_score`, economic diagnostics, evidence diagnostics, and reason text Recommended shares across eligible products sum to approximately 1. The output is advice only; execution authorization is out of scope. ## Example use of the result An agent may sort recommendations by share, present the SCALE and TEST candidates, compare them with a simple baseline, and ask the authorized human or execution system whether to act. It must not infer permission to spend from the decision response. ## Version and scientific status - Agent discovery layer: 0.5.0 - Allocation decision model: 0.3.0 - MPP server: 0.8.17 - Public Stripe test-mode validator: 18 checks passed on 2026-08-10 - Live payments: disabled - Performance validation: UNVALIDATED_FORWARD ## Experimental disclaimer KillionApps Promotion Allocation is experimental decision support. Platform-attributed promotion results are features, not proof of causal lift. Expected incremental contribution profit remains null until forward and controlled experiments justify a causal estimate. Do not claim guaranteed revenue, ROAS, or profit improvement.