188 lines
8.3 KiB
Markdown
188 lines
8.3 KiB
Markdown
# 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["<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.
|