WatchTraderHub to Chrono24 XML feed: field mapping reference

Prepared for the Chrono24 import team.

This document lists every element and every value the WatchTraderHub (WTH) feed can send, so the feed can be mapped to your import schema without opening a single sample file. Every value list in it is checked against the feed code by an automated build check, so the document and the feed cannot drift apart.

How to read this

We built our inventory fields against your dealer listing form, so for nearly every dropdown we already send your exact label as a plain string, for example Yellow gold, Sapphire crystal or 10 ATM. Those need no translation.

Three fields are not labels and are spelled out below: condition is an integer, original_box and original_papers are yes/no flags, and year_is_approximate is a yes flag that only ever appears next to a year.

Where a table says a field is omitted when the value is off-list, it means the value we hold is not on the list printed underneath that table: a colour or a material typed free-hand into an older record, or carried in by a spreadsheet import before we offered a dropdown for it. We leave the element out rather than send the raw text, because every one of these is a closed dropdown on your side and a string outside the list is discarded on import anyway.

Where a section header says a value is our proposal, it means your published import schema has no element for it and we picked a name. Tell us what you would rather receive and we will change it.

Element names in this feed are the ones your import team already mapped when the feed went live. We have deliberately not renamed anything to match your XML template, because that would break the existing mapping. A few of our names differ from the template on purpose: we send glass where the template says crystal, clasp where it says clasp_type, bracelet_width where it says lug_width, and other where it says other_attributes.

Fetching the feed

The configuration id is a UUID. Each dealer generates their own URL, username and password in WatchTraderHub and sends all three to you; the password is a random string we hash on our side and cannot recover, so a dealer who has lost it regenerates rather than looks it up.

A wrong or missing credential returns 401 with a WWW-Authenticate: Basic header. Every request, successful or not, is logged and shown to the dealer, which is how they confirm the import is running.

The response is one articles root element containing zero or more article elements. Watches and accessories arrive in the same document and are told apart by the type element inside basic_information:

Watch, Accessory

An article is only present while the dealer has it published, listed on the Chrono24 channel, and passing the exclusion rules at the end of this document. An article that disappears from the feed has been sold, unpublished or delisted.

Watch article

Structure

<article>
  <basic_information>
    <article_id>SN-10482</article_id>
    <type>Watch</type>
    <price>8500</price>
    <currency>EUR</currency>
    <brand>Rolex</brand>
    <model>Submariner Date</model>
    <reference_number>126610LN</reference_number>
    <condition>2</condition>
    <taxation_scheme>margin</taxation_scheme>
    <item_location>Germany</item_location>
    <item_location_region>Munich, Bavaria</item_location_region>
    <description>Full set, purchased 2021, serviced 2025.</description>
    <handling_time>1-3 days</handling_time>
    <gender>mens</gender>
  </basic_information>
  <images>
    <image>https://www.watchtraderhub.com/api/img/inventory/.../1.jpg</image>
    <image>https://www.watchtraderhub.com/api/img/inventory/.../2.jpg</image>
    <image>https://www.watchtraderhub.com/api/img/inventory/.../3.jpg</image>
  </images>
  <case>
    <case_material>Steel</case_material>
    <case_diameter>41</case_diameter>
    <case_thickness>12.5</case_thickness>
    <dial_color>Black</dial_color>
    <glass>Sapphire crystal</glass>
    <bezel_material>Ceramic</bezel_material>
    <dial_numerals>No numerals</dial_numerals>
  </case>
  <caliber>
    <movement_type>Automatic</movement_type>
    <caliber>3235</caliber>
    <power_reserve>70 hours</power_reserve>
  </caliber>
  <bracelet>
    <bracelet_material>Steel</bracelet_material>
    <bracelet_color>Steel</bracelet_color>
    <bracelet_width>20</bracelet_width>
    <clasp>Fold clasp</clasp>
    <clasp_material>Steel</clasp_material>
  </bracelet>
  <miscellaneous>
    <year>2021</year>
    <year_is_approximate>yes</year_is_approximate>
    <original_box>yes</original_box>
    <original_papers>yes</original_papers>
    <warranty_months>12</warranty_months>
    <water_resistance>30 ATM</water_resistance>
    <functions>Chronograph, Date</functions>
    <other>Screw-Down Crown, Luminous hands</other>
  </miscellaneous>
</article>

The four optional sections (case, caliber, bracelet, miscellaneous) are omitted entirely when the dealer filled in none of the fields inside them. basic_information and images are always present.

basic_information

article_id

The value is decided once, the first time an article is served to you, and then frozen on our side. It is, in order of preference: the dealer's stock number, or our internal item id prefixed with WTH- when they keep no stock numbers.

Freezing matters because you match a feed entry to an existing listing by article_id. A dealer who later edits their stock number, or a bulk backfill that assigns stock numbers to old items, does not change the id of anything you are already carrying. A delisted and re-listed item starts fresh and will arrive under whatever its stock number is at that point.

When a dealer holds several identical units of one watch, we expand it into one article per unit and suffix each id with a hyphen and the unit number, for example SN-10482-1, SN-10482-2, SN-10482-3. The base id is never sent on its own in that case.

Condition

condition carries a single integer, aligned one to one with the six grades on your conditions page. The second column is our own stored value, shown so a support conversation about one listing can be traced back through our system.

Two notes. Our worst grade is "Poor", which lands in your "Incomplete" slot; some watches a dealer grades Poor are heavily worn but complete and running, so the description is the place to confirm whether parts are actually missing.

And because you do not accept 0 on a margin-scheme listing, a watch graded New whose effective tax treatment is margin is sent as 1, not 0. That floor is applied only to the value in this feed. The watch's stored condition, and what every other sales channel sees, is unchanged.

Taxation

taxation_scheme carries margin for an item under the margin scheme, and regular for everything else. The item's own tax treatment wins; where the item has none, the dealer's organization default applies. In full:

Handling time

1-3 days, 4-7 days, 8-14 days, 15-30 days, more than 30 days

Gender

mens, ladies

These are tokens rather than the labels your listing form shows. If you would rather receive the form labels, say so and we will switch.

images

images holds one image element per photo, in the order the dealer arranged them, so the first is the one they chose as the main picture. At most 16 are sent, which is the number your form accepts; a dealer with more photos has the rest dropped from the tail of their order.

Every URL is an absolute https link on our domain under /api/img/, ending in .jpg. Our storage holds WebP originals, and we convert on the way out because your importer green-tints WebP when it converts YCbCr to RGB. The URLs are public and need no authentication, so an import worker can fetch them directly.

Photos a dealer has marked internal (purchase receipts, service invoices, authentication paperwork) are never sent, and they are not counted towards the three-photo minimum either.

case

case_material

Rose gold, Yellow gold, Steel, Titanium, Aluminum, Platinum, White gold, Gold/Steel, Silver, Plastic, Ceramic, Palladium, Tungsten, Tantalum, Carbon, Bronze, Brass, Gold-plated, Sapphire crystal

Nineteen values, matching your case material dropdown exactly. Our own form offers red gold as a separate case material, but your case list does not have it (red gold appears only on your bracelet, bezel and clasp lists), so a red gold case is sent as Rose gold.

dial_color

White, Black, Gold (solid), Silver (solid), Mother of pearl, Silver, Champagne, Blue, Bordeaux, Bronze, Yellow, Gold, Grey, Green, Orange, Red, Purple, Pink, Brown, Turquoise, Meteorite, Skeletonized

glass

Sapphire crystal, Mineral Glass, Plexiglass, Glass, Plastic

bezel_material

Aluminum, Carbon, Ceramic, Gold/Steel, Palladium, Rose gold, Plastic, Platinum, Red gold, Silver, Steel, Tantalum, Titanium, Tungsten, White gold, Yellow gold, Bronze, Gem-set, Brass, Gold-plated, Rubber

dial_numerals

Arabic numerals, Roman numerals, No numerals, Gemstones, Lines

caliber

movement_type

Automatic, Manual winding, Quartz, Solar, Smartwatch

Our own form offers three movement types your list does not have. All three regulate with a quartz crystal, so they collapse onto Quartz rather than being dropped:

If you would rather have Spring Drive, Meca-Quartz and Tuning Fork arrive as their own strings, tell us and we will stop collapsing them.

bracelet

bracelet_material

Calf skin, Ostrich skin, Crocodile skin, Leather, Snake skin, Plastic, Steel, Titanium, Gold/Steel, Rose gold, Red gold, Yellow gold, Aluminium, Platinum, White gold, Silver, Rubber, Shark skin, Satin, Ceramic, Lizard skin, Silicon, Alligator skin, Brass, Gold-plated, Textile

bracelet_color

Black, Brown, Silver, Gold, Steel, Beige, Blue, Bordeaux, Bronze, Yellow, Grey, Green, Orange, Red, Purple, White, Pink, Gold/Steel

clasp

Fold clasp, Fold clasp, hidden, Double-fold clasp, Buckle, Jewelry clasp, No clasp

clasp_material

Plastic, Steel, Silver, Titanium, Gold/Steel, Rose Gold, Red gold, Yellow gold, Aluminum, Platinum, White Gold, Bronze

Note the casing of Rose Gold and White Gold in this list. It is the casing your clasp material dropdown uses, and it differs from the case and bezel lists, where the same two materials are lower case. We follow each list as published.

miscellaneous

Scope of delivery

We store scope of delivery as one field and send it as your two flags. Both are always present, because scope of delivery is one of your required fields:

An item too old to carry the field at all, imported before we added it, is sent as watch only, which is the claim least likely to disappoint a buyer.

Year

year_is_approximate never appears on its own. It is sent only next to a year, and only with the value yes. Where the dealer ticked "year unknown" we omit year entirely rather than send a guess, on the understanding that your importer reads an absent year as unknown.

water_resistance

Not water resistant, 1 ATM, 2 ATM, 2.5 ATM, 3 ATM, 4 ATM, 5 ATM, 6 ATM, 7 ATM, 8 ATM, 9 ATM, 10 ATM, 15 ATM, 20 ATM, 30 ATM, 40 ATM, 50 ATM, 60 ATM, 70 ATM, 80 ATM, 90 ATM, 100 ATM, 110 ATM, 120 ATM, Over 120 ATM

functions and other

Our form offers one combined list of features. We split it on the way out along the same line your form does: the 21 complications go in functions, and the 30 remaining characteristics go in other. Both are comma-and-space separated in a single element.

functions:

Chronograph, Double chronograph, Flyback, Panorama date, Repeater, Tourbillon, Annual calendar, 4-year calendar, Perpetual calendar, Alarm, Chiming clock, Moon phase, Minute repeater, Date, Weekday, Month, Year, Tachymeter, Jumping hour, Equation of time, GMT

other:

Central seconds, Small seconds, Guilloché dial, Gemstones and/or diamonds, Luminous numerals, Genevian Seal, Chronometer, Rotating Bezel, Limited Edition, Crown Left, Screw-Down Crown, Guilloché dial (handwork), Tempered blue hands, Luminous hands, Display back, Skeletonized, Power Reserve Display, Helium Valve, Quick Set, Screw-Down Push-Buttons, Only Original Parts, Luminous indices, PVD/DLC coating, World time watch, Master Chronometer, Smartwatch, Solar watch, One-hand watches, Vintage, Special Edition

Both lists are sent with the accents your form uses, so the two Guilloché entries carry a UTF-8 e-acute. The document is served as UTF-8 and so is the feed.

Accessory article

Accessories are watch parts and related goods: dials, movements, bracelets, boxes, tools, winders. On your side they are a listing whose "Style of watch" is Parts/Accessories, with an "Ad type" naming the kind of part.

Your published XML template has no element for either of those, so the two elements below are our proposal: accessory_type inside basic_information, carrying your Ad type label verbatim, and quantity for the stock flag. If your accessory import expects different element names, or a different place in the tree, tell us and we will change the feed. Nothing else about an accessory article is invented; every other element is the one the watch articles already use.

Structure

<article>
  <basic_information>
    <article_id>WTH-PART-2f5c9d61-4f0a-4a1e-9d63-6f5d1c2b7a90</article_id>
    <type>Accessory</type>
    <accessory_type>Dial</accessory_type>
    <price>250</price>
    <currency>EUR</currency>
    <brand>Rolex</brand>
    <model>Submariner 16610 dial, tritium</model>
    <condition>2</condition>
    <taxation_scheme>margin</taxation_scheme>
    <item_location>Germany</item_location>
    <item_location_region>Munich, Bavaria</item_location_region>
    <description>Original dial, light patina, no cracks.</description>
    <quantity>12</quantity>
  </basic_information>
  <images>
    <image>https://www.watchtraderhub.com/api/img/spare-parts/.../1.jpg</image>
  </images>
  <miscellaneous>
    <year>1998</year>
  </miscellaneous>
</article>

accessory_type

Bracelet/strap, Link/Bar, Buckle, Dial, Bezel, Crown/Pusher, Hand(s), Movement (parts), Movement (complete), Case, Glass/Crystal, Box, Watch Winders, Tools, Cleaning, Books/Calendars, Other

These are the labels on your Ad type dropdown, spelled exactly as it spells them. A part whose type we cannot place is sent as Other.

What an accessory does not carry

An accessory article has no reference_number, and no case, caliber or bracelet section. Your Parts/Accessories form does not ask for any of it, and we do not hold it against a part.

Two more differences from watches worth knowing. Accessories have no internal photo concept, so every photo a dealer attached to a part is sent. And an accessory needs only one photo to be eligible, against three for a watch.

Unlike watches, an accessory held in several units is one article with a quantity, not one article per unit. We did not want to invent a suffixed article_id scheme for a listing type whose schema is still open. Say the word if you would rather have them expanded the way watches are.

Exclusion rules

A published, Chrono24-listed item that fails any of these is left out of the feed. The dealer sees the reason in their WatchTraderHub channel page and can fix it themselves, so an item missing from your import is usually about to reappear.

The strings below are what a dealer is shown, word for word, which makes them useful in a support conversation.

Watches

A watch is excluded when:

• Brand, model or reference number is missing: Missing required field (brand, model, or reference number)
• The condition is not one we can grade: Invalid or missing condition: "none"
• It has no photo the public may see: No public photos, minimum 3 required
• It has one: Only 1 public photo, minimum 3 required
• It has two: Only 2 public photos, minimum 3 required
• The price after markup is not positive: Calculated feed price is zero or negative

The photo minimum counts only photos the dealer has left public. A watch with five photos of which three are internal paperwork is excluded at two.

Accessories

An accessory is excluded when:

• The manufacturer is missing: Manufacturer is missing
• The name is missing or too long for your Model field: Part name is missing or exceeds the 90 character limit
• The condition is not one we can grade: Invalid or missing condition: "none"
• It has neither a production year nor the "year unknown" flag: Year of production is missing, and it is not marked unknown
• The price is not positive, or the stock is below one: Price must be positive and quantity must be at least 1
• It has no photo: No photos, minimum 1 required

Limits

Questions

Reply to the dealer who sent you this feed and they will pass it on, or answer in the thread you already have with them. Anything about element names, missing fields, or the two proposed accessory elements is worth asking; the feed is ours to change.

Every value list in this document is checked against the feed code by an automated build check, and the document is republished whenever the feed changes. The current version is always at https://www.watchtraderhub.com/docs/chrono24-feed-mapping, with a PDF at https://www.watchtraderhub.com/docs/chrono24-xml-feed-mapping.pdf