Stock Feed Specification

This page describes the stock feed format Scooter125 accepts. It is written for dealers and for the vendors who build their dealer management systems. If your DMS already produces a vehicle feed, send us the URL and we will map it — you do not need to build anything new.

How it works

You publish one file at one HTTPS address. That file lists your complete current stock, every time it is requested. We read it on a schedule you choose — hourly, every four hours, or daily — and update your listings to match.

• One URL, returning your whole stock list. No pagination, no “changes since” parameters.
• HTTPS only.
• Optional HTTP Basic authentication, a bearer token, or a key in the URL.
• Gzip is supported and encouraged.
• Maximum 25MB, maximum 60 seconds to respond.

Why a full list rather than changes? Because a full list repairs itself. If we miss a run, or your server has a bad morning, the next good run puts everything right. A feed of changes silently loses stock forever the first time a run is missed.

Your stock reference is the important part

Every bike needs a ref — your own stock number. It must be unique within your stock and it must stay the same for as long as that bike is with you. This is how we know that the bike in row 40 today is the same bike that was in row 12 yesterday.

Two things to avoid. Do not reuse a stock number after a sale — if A-1042 is a Honda in March and a Yamaha in June, we will treat them as two different bikes rather than change a live page into a different machine. And do not regenerate references on every export, because then every bike looks new to us every night.

Required fields

Field	Example	Notes
ref	A-1042	Your stock number. Unique and stable.
brand	Honda	Free text. We map it to our brand list.
model	Ace 125	Free text.
year	2024	Four digits.
price	24000	Rands. No symbol, no separators, no decimals.
engine_cc	125	Engine size as a number.
condition	Used	New, used, or damaged.
city	Johannesburg	Where the bike physically is.
images	list of URLs	At least one. The first becomes the main photo.

Optional fields

mileage, transmission, colour, description, vin, suburb, province, service_history, body_type, sold, image_hash.

Send province if you like, but we work it out from the city, because that is more reliable. Send vin if you have it — we store it and never publish it. Send image_hash per image if your system can, because it lets us skip re‑downloading photos that have not changed.

Formatting values

• Price. We accept R 24 000, 24,000 and 24000.00 and reduce them all to a number. A price of 0 or 1 meaning “call us” is rejected rather than published as free.
• Engine size. 125 or 125cc both work. A zero is rejected, because a bike with no engine size cannot appear on any capacity page.
• Year. Four digits between 1970 and next year.
• Text encoding. UTF‑8 preferred. We detect and convert Windows‑1252 exports, which is what Excel usually produces.

Accepted formats

XML, JSON or CSV. Your field names do not need to match ours — we map them once when you are set up. Nested structures are fine.

<stock>
  <bike>
    <StockNo>A-1042</StockNo>
    <Make>Honda</Make>
    <ModelDesc>Ace 125</ModelDesc>
    <Year>2024</Year>
    <SellingPrice>24000</SellingPrice>
    <EngineSize>125</EngineSize>
    <Condition>Used</Condition>
    <Branch>Johannesburg</Branch>
    <Photos>
      <Photo>https://example.co.za/img/a1042-1.jpg</Photo>
      <Photo>https://example.co.za/img/a1042-2.jpg</Photo>
    </Photos>
  </bike>
</stock>

[
  {
    "StockNo": "A-1042",
    "Make": "Honda",
    "ModelDesc": "Ace 125",
    "Year": 2024,
    "SellingPrice": 24000,
    "EngineSize": 125,
    "Condition": "Used",
    "Branch": "Johannesburg",
    "Photos": { "Photo": [
      "https://example.co.za/img/a1042-1.jpg",
      "https://example.co.za/img/a1042-2.jpg"
    ] }
  }
]

For CSV, use a header row. Semicolon and comma delimiters are both detected. Put image URLs in one column separated by pipes.

When a bike sells

Simply drop it from the feed, or send sold: true if your system can. If you send it explicitly we act immediately. If a bike just disappears, we wait until it has been absent from two consecutive successful runs before marking it sold — that protects your stock from a temporary glitch at either end.

Sold bikes keep their page, marked as sold, showing three similar bikes you still have. Those pages carry rankings and continue to send you enquiries, so we do not delete them.

If something goes wrong

If a run returns far fewer bikes than the last one, we stop and ask a human rather than marking your floor sold. If we cannot recognise a value — a brand spelled in a way we have not seen before — we hold that one bike and tell you, rather than guessing.

You get a weekly email, but only when there is something worth telling you: what went live, what sold, and any rows we could not import, each quoted by your own stock number so you can find it.

Getting started

Send us your feed URL and any credentials it needs. We run it without writing anything, show you exactly what would happen, agree the mapping with you, then switch it on. Nothing goes live on your name until you have seen that report.