Product specifications

Display the complete approved sale unit, its materials, size choices, and production estimate.

Both POST /v1/market/feeds/{feedId}/items/search and GET /v1/market/feeds/{feedId}/items/{listingId} return the same Product schema. These remain read-only endpoints. The partner API has no specification editing, checkout, order, or production-file endpoint.

Stable identity and reviewed facts

id remains your catalog key. sku is a stable public reference such as DYJ-M-1042. specificationVersion identifies the approved product specification; a price-only update keeps it unchanged. Every approved specification or price update advances updatedAt. Draft edits do not change the offer.

The specification, commercial terms, gallery, and Viewer references in one product response come from one publication. Separate requests can see different publications after an approval. Replace the complete stored product on each sync and remove it from sale when it leaves the feed.

Legacy unknowns

Legacy products keep their existing prices, facets, images and embeds. Their structured fields and price.costTerms are null until reviewed. Hide unknown details or say they are not specified. Never infer purity, origin, production days or tax treatment from a title, picture, or absent line.

stones: null means the supplied stone content is not yet reviewed. stones: [] explicitly confirms a stone-free product. A missing weight stays null, not zero.

Materials, stones and the sale unit

metalDetails records each metal and its confirmed fineness in parts per thousand: 750 is 18K gold, 925 is sterling silver. Finish and approximate metal weight can be unknown. Do not turn a qualitative appearance description into a gemological grade.

saleUnit states whether the offer is one piece, a pair, or a set. The unit price, approximate metal weights, each stone group count and each group total carat weight cover that complete unit. Stone dimensions describe individual stones only when the dimensions apply to the whole group. Component labels distinguish asymmetric pairs and sets.

includedComponents lists what the atelier supplies. Do not advertise an illustrative center stone as included unless it appears in the supplied groups and components. Each group keeps its type and origin together: natural sapphires with lab-grown diamond accents must not become “natural diamonds.”

Primary filters and detailed stone groups

The existing request filters stones and stoneOrigins still match the single primary stone represented by the response fields stone and stoneOrigin. The response array stones describes all supplied groups. Its first group is not necessarily the primary group.

One specification, approved sizes

Each reviewed listing offers one approved material-and-stone specification at one unit price. All exposed size options share that specification and price. The Marketplace Viewer shows the approved appearance and suppresses other material choices. Do not add store-side material options based on unrelated Viewer variations.

sizing.mode is ring_size, length, or fixed. Ring options retain exact labels and their EU, US or UK system; length options are numeric millimeters. Fixed-size pieces have no selectable options. Keep option IDs stable in your UI.

Nominal dimensions are per piece in millimeters. sizing.referenceOptionId identifies the size used for these dimensions and approximate metal weights. Dimensions that do not apply are omitted.

Production and supplier costs

production.leadTimeBusinessDays is the atelier estimate after payment and final specification confirmation. It excludes shipping transit. Display a business-day range; do not calculate a guaranteed delivery date from it.

price.listingPrice still includes the creator royalty. price.costTerms.taxTreatment and shippingTreatment are each included, excluded or quote_required. They describe DYJ's cost to your business, not your shopper tax or shipping policy. Keep supplier cost and these terms server-side. A quote-required component means this is not a final delivered cost.

Example additions

This example illustrates the contract, not a production commitment. The API reference includes complete search and detail responses.

{
  "sku": "DYJ-M-1042",
  "specificationVersion": 1,
  "metalDetails": [
    {
      "type": "white_gold",
      "fineness": 750,
      "finish": "polished",
      "approximateWeightGrams": null
    }
  ],
  "stones": [
    {
      "id": "center-1",
      "role": "center",
      "type": "sapphire",
      "origin": "natural",
      "shape": "oval",
      "count": 1,
      "totalCaratWeight": 1.5,
      "dimensionsMm": {
        "length": 8,
        "width": 6,
        "depth": null
      },
      "setting": "prong",
      "component": null
    }
  ],
  "saleUnit": {
    "type": "piece",
    "pieceCount": 1
  },
  "includedComponents": [
    "mounting",
    "center_stones"
  ],
  "sizing": {
    "mode": "ring_size",
    "system": "EU",
    "unit": null,
    "options": [
      {
        "id": "eu-54",
        "value": "54"
      }
    ],
    "referenceOptionId": "eu-54"
  },
  "dimensions": {
    "bandWidthMm": 2.1
  },
  "production": {
    "mode": "made_to_order",
    "leadTimeBusinessDays": {
      "min": 15,
      "max": 20
    }
  },
  "price": {
    "listingPrice": 1500,
    "totalPrice": 1815,
    "discount": 0,
    "totalPriceInEur": 1815,
    "costTerms": {
      "taxTreatment": "quote_required",
      "shippingTreatment": "excluded"
    }
  }
}