8.3 KiB

Raw Blame History

How the Pricing Agent Works

A plain-English guide. No coding or Amazon knowledge needed.

Engineers: the detailed reference — data sources, formulas, file map, backtests — now lives in ARCHITECTURE-DETAIL.md.

What it is

We sell products on Amazon. Every product has a price, and the right price is a constant question: too high and we stop selling, too low and we lose money on every sale.

This tool looks at one product at a time, works out what its price should be, and shows a person the answer with the reasoning behind it.

It never changes a price. It makes a recommendation. A human reads it and clicks Approve, Modify, or Reject. Nothing is sent to Amazon.

The one-sentence version

It reads our real sales history, works out what each sale actually earns after all costs, checks whether we have too much or too little stock, looks at what rivals charge, and then suggests a price — showing its working, and refusing to suggest anything that would lose money.

Where the numbers come from

Everything starts from COSMOS, our internal system that already holds our Amazon data. The tool reads five things from it:

What	Why it matters
Fees and costs	What Amazon charges us per sale, plus what the product cost us
Sales history (6 months, daily)	What we charged, how many we sold, what we actually earned
Stock levels	How many units we have, and how long they'll last
Storage charges	What Amazon bills us to warehouse unsold stock
Advertising spend	What we paid in ads to make those sales

What the 6 months of history is for: it tells us which prices we have already tried and what each one really earned — so the tool can recommend a price we have proof about, instead of guessing. It also spots when sales have dropped well below normal, which is a signal something has changed.

What competitor prices are for: only two things. If Amazon has hidden our listing, stop and fix that. If a rival is meaningfully cheaper and it is visibly costing us sales, move toward their price — but never below the point where we lose money.

How it decides

The tool runs down a checklist, in order, and stops at the first thing that applies. This is deliberate — it means every recommendation traces back to exactly one reason, and you can always ask "why this price?" and get a single answer.

Roughly top to bottom:

#	If we find this…	…the answer is
1	Cost information is missing	Stop. Can't price a product without knowing what it cost. Go fill it in.
2	Amazon isn't showing our listing to buyers	Stop. A hidden listing sells nothing at any price. Fix the listing first.
3	We're selling below what it costs us	Raise the price. Every sale is losing money.
4	Ads are eating more than the sale earns	Raise the price.
5	We're about to run out of stock	Raise a little (5%) to slow sales until more arrives.
6	Sales dropped sharply and we don't know why	Stop and investigate. Don't guess with the price.
7	We have far too much stock sitting there	Lower a little (5%) to shift it before storage costs mount.
8	A rival is meaningfully cheaper and it's actually costing us sales	Lower toward their price — but never below our own break-even.
9	The sales data suggests a more profitable price	Move toward it.
10	None of the above	Leave it alone.

Notice that stock problems are ranked above competitor problems. Cutting price to chase a rival while the shelf is emptying just means selling out faster for less money.

The safety rails

These apply to every recommendation, no exceptions:

Never below break-even. However cheap a rival is, the tool will not suggest a price that loses money.
Never more than 5% at once. Big price jumps confuse both customers and our own measurements. Large moves happen over several steps, each one checked.
Never above 25% up from today, so a modelling error can't produce an absurd price.
A kill switch in the sidebar pauses all approvals instantly.

Two things it is careful about

A blank is better than a wrong number. If some piece of data is missing, the tool shows a dash and says why. It never quietly fills in a zero or a guess — a wrong number that looks confident is far more dangerous than an obvious gap.

It separates what happened from what it predicts. Rows showing real past results are labelled as facts. Rows showing "if we priced at X" are labelled as estimates. The tool also reports how wrong it has been on that specific product in the past, so you know how much to trust the estimate.

What it deliberately does not do

It does not set prices. Advisory only. Every change is a human decision.
It does not let the AI decide anything. An AI writes the plain-English summary you read — but every number and every recommendation comes from fixed arithmetic. The AI explains; it never calculates or chooses.
It does not guess at missing data.

Words you'll see

Term	Plain meaning
SKU	Our internal code for one specific product — e.g. a queen duvet in white
ASIN	Amazon's code for the same thing
Buy Box	The "Add to Cart" button. Several sellers can offer the same item; Amazon picks one to be the default. Win it and you get nearly all the sales. Lose it and sales collapse — so this matters enormously.
Suppressed	Amazon has hidden our listing entirely. Nobody can buy it.
Break-even	The price where we make exactly zero. Below it, every sale loses money.
Margin	What's left over from a sale after every cost
Cover days	How many days our current stock will last at the rate we're selling
Elasticity	How much sales volume changes when price changes. Some products lose lots of sales from a small rise; others barely notice.
TACoS	Advertising spend as a share of sales revenue
Backtest	Checking a method against past data to see how accurate it would have been

The whole flow, start to finish

flowchart TD
    COSMOS["<b>COSMOS</b><br/>sales history · costs<br/>stock · ad spend"]
    RIVALS["<b>Competitor prices</b><br/>checked on Amazon<br/><i>not in COSMOS</i>"]
    FACTS["<b>1 · Work out the facts</b><br/>what a sale really earns ·<br/>how long stock lasts ·<br/>best price we've run"]
    CHECK{"<b>2 · Run the checklist</b><br/>stop at the first match"}
    FIX["<b>Go fix something</b><br/>missing costs · hidden listing<br/>no price helps yet"]
    PRICE["<b>A suggested price</b><br/>up · down · leave alone"]
    RAILS["<b>3 · Safety rails</b><br/>never below break-even<br/>5% max per step<br/>25% max above today"]
    SCREEN["<b>4 · Show a person</b><br/>the price · the one reason<br/>the workings · our accuracy"]
    HUMAN{"<b>5 · A human decides</b>"}
    OK["✅ Approve"]
    MOD["✏️ Modify"]
    NO["✖️ Reject"]
    STOP["<b>Nothing is sent to Amazon</b><br/>a person makes every change by hand"]

    COSMOS --> FACTS
    RIVALS --> FACTS
    FACTS --> CHECK
    CHECK -->|"pricing can help"| PRICE
    CHECK -->|"something is broken"| FIX
    PRICE --> RAILS
    RAILS --> SCREEN
    FIX --> SCREEN
    SCREEN --> HUMAN
    HUMAN --> OK & MOD & NO
    OK & MOD & NO --> STOP

    style COSMOS fill:#d9eee9,stroke:#0c8276,color:#1b2030
    style RIVALS fill:#d9eee9,stroke:#0c8276,color:#1b2030
    style CHECK fill:#fbf6ee,stroke:#a89f8a,color:#1b2030
    style HUMAN fill:#fbf6ee,stroke:#a89f8a,color:#1b2030
    style RAILS fill:#fbe6df,stroke:#df4f33,color:#1b2030
    style FIX fill:#fbe6df,stroke:#df4f33,color:#1b2030
    style STOP fill:#f4f0e8,stroke:#22304e,color:#1b2030

Two things worth noticing in that picture:

Step 2 can decide that pricing is the wrong tool entirely. If the cost figures are missing, or Amazon has hidden our listing, no price change helps — so it says so instead of inventing a number.
The safety rails sit between the suggestion and the screen. Whatever the calculations produce, nothing that would lose money reaches a person as a recommendation.

Everything on the screen traces back to a specific number from COSMOS. Nothing is invented along the way.

8.3 KiB Raw Blame History