price-optimization-tool

# Price Optimization Tool

Build an evidence-bounded price decision from seller economics and observed behavior, then recommend a reversible test or rollout with explicit uncertainty.

## Installation

```bash
npx skills add nexscope-ai/eCommerce-Skills --skill price-optimization-tool -g
```

## Capabilities

- Audit price, demand, traffic, promotion, cost, and inventory data for comparability.
- Calculate contribution economics and hard candidate-price constraints.
- Estimate directional or numeric elasticity only when the evidence supports it.
- Compare price candidates under base, downside, and upside demand scenarios.
- Optimize regular, promotional, bundle, quantity, and good-better-best price candidates.
- Design controlled price tests with hypotheses, guardrails, confounder controls, and decision rules.
- Produce a recommendation with uncertainty, approval requirements, and a reversible rollout.

## Usage Examples

```text
Evaluate these five price candidates using my cost and sales history.
```

```text
Can this dataset support a price-elasticity estimate, and what should I test next?
```

```text
Build a price experiment for my top five Shopify SKUs without misleading customers.
```

```text
Compare separate-item, bundle, and quantity-tier pricing for these products.
```

## Inputs and Collection

Use seller-supplied and inspected evidence first. Collect:

- SKU, variant, channel, market, currency, tax treatment, fulfillment method, lifecycle stage, and business objective;
- timestamped regular price, realized selling price, list or compare-at price, coupons, promotions, and seller-funded discounts;
- timestamped sessions or impressions, orders, units, net revenue, cancellations, returns, and inventory availability;
- COGS, inbound freight, duties, packaging, fulfillment, payment, referral, affiliate, ad, return, and other variable costs;
- traffic source, ad spend, content or listing changes, stock status, seasonality, events, and promotion windows;
- comparable competitor offers with source, capture time, variant, pack size, availability, shipping, seller, and fulfillment;
- bundle components, attach rates, cannibalization risks, tier thresholds, and operational constraints;
- target metric, approved floor and ceiling, test duration constraints, platform rules, approver, and risk tolerance.

If material inputs are missing, ask one consolidated follow-up. If they remain unavailable, provide a provisional candidate framework and test plan, not a fabricated optimal price.

## Workflow

### 1. Define the Decision and Evidence Boundary

State the SKU, market, channel, objective, candidate range, time horizon, and decision owner. List inspected sources and label inputs:

- **Confirmed:** supported by inspected evidence.
- **Assumption:** an explicit scenario input, not an observed fact.
- **Unknown:** missing information that blocks a calculation or conclusion.

Choose one primary objective, such as contribution dollars, contribution per visitor, cash recovery, revenue, sell-through, launch learning, or a constrained balance. Do not silently optimize revenue when the seller asked for profit, or units when inventory is limited.

### 2. Audit and Align the Data

Build a time-aligned dataset at the most reliable common granularity. Check:

- realized price rather than list price alone;
- seller-funded discount and promotion stacking;
- currency, tax, pack size, product version, channel, and market consistency;
- stockouts, suppressed listings, missing traffic, cancellations, and returns;
- changes in ads, traffic mix, content, reviews, fulfillment, competitors, and seasonality;
- sufficient observations and meaningful price variation.

Exclude or flag non-comparable periods. Do not interpret a price-demand correlation as causal when other material variables changed.

### 3. Calculate Unit Economics and Constraints

For each observed or candidate price:

```text
Net Revenue = Selling Price - Seller-Funded Discounts - Refund Allowance
Contribution $ = Net Revenue - COGS - Variable Selling Costs
Contribution % = Contribution $ / Net Revenue
```

When percentage fees apply to selling price:

```text
Price Floor = (Unit Cost + Fixed Variable Costs + Target Contribution $) / (1 - Variable Fee Rate)
```

Run base, high-return, high-ad-cost, fee-change, and promotion-stack scenarios. Keep gross margin, markup, contribution margin, and net profit distinct. Remove candidates that violate approved economics, legal or contractual constraints, platform rules, or customer-trust limits.

### 4. Assess Whether Elasticity Is Estimable

Use a numeric estimate only when there is sufficient clean price variation, comparable exposure, reliable quantity or conversion data, and manageable confounding. A simple midpoint diagnostic is:

```text
Price Elasticity = ((Q2 - Q1) / ((Q2 + Q1) / 2)) / ((P2 - P1) / ((P2 + P1) / 2))
```

Report the observation window, units, exclusions, uncertainty, and whether the result is descriptive or plausibly causal. Segment only when sample size and decision relevance justify it.

If evidence is weak:

- state that elasticity is not reliably estimable;
- use a range of explicitly labeled demand-response scenarios;
- recommend the smallest useful controlled test;
- never substitute an unverified category benchmark and call it product evidence.

### 5. Model Candidate Prices

Create a candidate grid that includes the current price, economically meaningful lower and higher options, and any approved bundle or tier. For each candidate, calculate:

```text
Expected Units = Baseline Units × Demand Response Scenario
Expected Revenue = Candidate Realized Price × Expected Units
Expected Contribution = Contribution per Unit × Expected Units
Break-Even Unit Change = Baseline Total Contribution / Candidate Contribution per Unit - Baseline Units
```

Show base, downside, and upside cases. If elasticity is supported, translate the estimate into a bounded scenario rather than presenting a sin