Question types & answer schemas

Questions are typed rather than free text, which is what makes the answers machine-readable: packed_weight always comes back as a number plus a unit, never as “about 1.2 kilos I think”.

Asking a question

{
  "type": "packed_weight",
  "note": "Weight including the retail box"
}

Rules: 1–10 questions per message; a standard type may appear only once per message (INVALID_QUESTION_SCHEMA otherwise); other may repeat because each one is a different question. On standard types a question field is ignored — put the context in note.

Answer envelope

Every answer carries a status:

Only answered carries a value — the other three always return value: null.

{
  "question_id": "sqst_...",
  "type": "packed_weight",
  "status": "answered",
  "value": 1250,
  "unit": "g",
  "provider_note": null,
  "answered_at": "2026-05-20T11:40:00.000Z"
}

The ten types

packed_weight

Weight of one unit as packed by the supplier.

{
  "status": "answered",
  "value": 1250,
  "unit": "g"
}

value is a positive number, unit is g or kg.

package_dimensions

Outer dimensions of a single packed unit.

{
  "status": "answered",
  "value": {
    "length": 32,
    "width": 24,
    "height": 12,
    "unit": "cm"
  }
}

All three are positive numbers; unit is cm, mm or in.

carton_info

Master carton specification — the one that decides your freight cost.

{
  "status": "answered",
  "value": {
    "quantity_per_carton": 24,
    "gross_weight": 14.5,
    "weight_unit": "kg",
    "length": 60,
    "width": 40,
    "height": 35,
    "dimension_unit": "cm"
  }
}

quantity_per_carton is a positive integer; the rest are positive numbers with g/kg and cm/mm/in units.

stock

{
  "status": "answered",
  "value": {
    "availability": "in_stock",
    "quantity": 800
  }
}

availability is in_stock, out_of_stock, partial or unknown. quantity is optional and may be null.

lead_time

Production or restock time in days.

{
  "status": "answered",
  "value": {
    "min_days": 7,
    "max_days": 15
  }
}

Both are integers and max_days must be greater than or equal to min_days.

moq

{
  "status": "answered",
  "value": {
    "quantity": 100,
    "unit": "pieces"
  }
}

unit is the supplier’s own wording (pieces, sets, cartons, …), max 32 characters.

neutral_packaging

Whether the supplier ships without their own branding.

{
  "status": "answered",
  "value": {
    "support": "conditional",
    "note": "Free above 200 units"
  }
}

support is yes, no, conditional or unknown; note is optional free text.

customization

Logo printing, custom colour, custom packaging.

{
  "status": "answered",
  "value": {
    "support": "yes",
    "moq": 500,
    "note": "One-colour logo print, plate fee applies"
  }
}

moq and note are both optional.

product_details

Anything descriptive — material, certification, voltage, model differences.

{
  "status": "answered",
  "value": {
    "text": "304 stainless steel, 1.2 mm wall"
  }
}

other

The escape hatch. question is required when asking; the answer is free text, max 4000 characters.

{
  "status": "answered",
  "value": {
    "text": "Yes, they can ship on Saturdays."
  }
}

Weight and dimension answers are reused

Answers to packed_weight, package_dimensions and carton_info are recorded as supplier-confirmed logistics observations against channel + source_product_id + sku. That makes them available for freight estimation on later orders for the same product. Only the physical attributes are kept — never your questions, notes or business context.