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