Listing kinds: vehicles, homes, services and tickets

Every listing has a kind. Most are GOODS — an item you can hand over — and need nothing new. Vehicles, homes and property, services and tickets carry their own details, so people can find and compare them, and so matching can pair them.

Send kind and details with POST /merchant/listings, PUT /merchant/listings/{id} or POST /v1/listings/individual, or in your catalog feed as a kind column and detail_<field> columns (see Catalog feed). Fields a kind doesn't define are dropped. A missing required field, or a value that isn't allowed, is 422 LISTING_DETAILS_INVALID, with details.fields naming each one.

Each kind sets the listing's category itself, and some details fill other fields, so search and matching work the same for every kind:

Kind	Category	Filled from details	Condition
GOODS	yours	—	yes
VEHICLE	Vehicles	subcategory ← type, brand ← make, model, year	yes
PROPERTY	Real estate	subcategory ← property type, year ← year built	no
SERVICE	Services	subcategory ← kind of service	no
TICKET	Tickets & events	—	no

Details by kind

GOODS (all optional): size, color, dimensions, quantity (1–10,000).

VEHICLE:

• required: vehicleType (Car, Truck, SUV, Van, Motorcycle, Scooter, Bicycle (electric), Boat, RV / camper, Trailer, Other vehicle), make, model, year (1900 to next year);
• optional: mileage and mileageUnit (km or mi), transmission (Automatic, Manual, Other), fuel (Petrol / gasoline, Diesel, Hybrid, Electric, Other), drive (Front-wheel, Rear-wheel, All-wheel, 4x4), color, titleStatus (Clean, Rebuilt, Salvage, Has a lien, No title), owners, vin (up to 17 characters).

PROPERTY:

• required: offering (For sale, For rent, Home swap), propertyType (House, Apartment / condo, Townhouse, Room, Land, Commercial, Parking / storage);
• optional: bedrooms, bathrooms, area and areaUnit (sq ft or m²), lotSize, yearBuilt, furnished (true/false), parking, neighborhood, availableFrom (YYYY-MM-DD), minimumStay.

For rent, originalPrice is the rent per month. A home's street address is never shown — send neighborhood instead.

SERVICE:

• required: serviceType (Lessons & tutoring, Repairs & handywork, Design & creative, Tech & IT, Cleaning & home, Beauty & wellness, Events & photography, Moving & delivery, Other service), delivery (In person, Online, Either);
• optional: duration (what the price covers), experience, availability.

TICKET:

• required: eventName, eventDate (YYYY-MM-DD, not in the past), quantity (1–50);
• optional: venue, section, transfer (Mobile transfer, Paper tickets, PDF / email).

Example

curl -X POST https://api.tbbnetwork.com/merchant/listings \
  -H "Authorization: Bearer sk_live_..." -H "Content-Type: application/json" \
  -d '{
    "merchantId": "MERCHANT_ID",
    "merchantListingRef": "car-1042",
    "title": "2019 Toyota Corolla LE",
    "kind": "VEHICLE",
    "details": { "vehicleType": "Car", "make": "Toyota", "model": "Corolla", "year": 2019,
                 "mileage": 48000, "mileageUnit": "mi", "transmission": "Automatic" },
    "condition": "Used - Good",
    "originalPrice": 14500,
    "currency": "USD",
    "visibility": "GLOBAL",
    "listingType": "BOTH"
  }'

A suggested meeting place

Any listing can suggest a TBBN Space for the meetup or drop-off with preferredSpaceId (an active, public Space). Members see it on the item and can accept it, or suggest another, when they propose a swap; the offer carries meetupSpaceId. When the offer is accepted, the trade starts with that Space agreed as its meeting place — nothing is booked until the traders reserve it.

Finding them

GET /v1/directory/listings takes kind, and for vehicles make, minYear and maxYear, and for homes offering and minBedrooms. Public listings return kind and details.