Retrieve a product

This endpoint returns the full product, with support for extended projections via ?extend=. This page also covers two related endpoints on a specific product: similar products via embeddings, and the variants/options summary.

Use it when you need to:

  • Display a product's full record in your application.
  • Bring in inventory per variant and location without an extra call (extend=inventory).
  • Suggest related products on a detail page.
  • Get only the variants/options structure of a product without pulling in the rest of its fields.

Endpoint

Retrieves a product by its ID or SKU

idstringrequired

ObjectId (_id) or SKU of the product. The endpoint automatically detects which one you sent.

extendstring

Comma-separated list: variants, options, description, bindings, metadata, inventory, dimensions, seo, all.

200
{
  "id": "65f3a1b2c4d5e6f7a8b9c0e1",
  "sku": "CAM-ROJO-M",
  "status": "active",
  "productType": "physical",
  "title": { "value": "Camisa Roja Talla M", "translations": [] },
  "description": { "value": "Camisa de algodón 100%, corte regular.", "translations": [] },
  "price": 499.00,
  "compareAtPrice": 599.00,
  "currency": "MXN",
  "taxable": true,
  "brand": "Fenicia Basics",
  "category": { "id": "cat-1", "name": "Playeras", "path": "ropa/playeras", "selectable": true },
  "tags": ["playeras", "temporada-verano"],
  "media": [
    {
      "id": "m1",
      "src": "https://cdn.fenicia.io/img/cam-rojo-m.jpg",
      "type": "image",
      "position": 0,
      "alt": { "value": "Camisa roja talla M", "translations": [] }
    }
  ],
  "variants": [
    {
      "id": "65f3a1b2c4d5e6f7a8b9c0f1",
      "sku": "CAM-ROJO-M-CH",
      "parentSku": "CAM-ROJO-M",
      "title": { "value": "Camisa Roja - Chica" },
      "price": 499.00,
      "position": 0,
      "taxable": true,
      "options": [{ "id": "opt-talla", "name": "Talla", "value": "CH" }],
      "bindings": []
    }
  ],
  "options": [],
  "attributes": [],
  "bindings": [],
  "seo": { "metaTitle": "Camisa Roja Talla M", "metaDescription": "Camisa de algodón para hombre.", "slug": "camisa-roja-talla-m" },
  "minAlertStock": 5,
  "sellIfOutOfStock": false
}
404
{ "code": "not-found", "message": "Product not found" }

Permission required: products:read

Path parameters

ParameterTypeDescription
idstringMongoDB _id (24 hex characters) or the product's SKU. The endpoint automatically detects which format you sent.

The extend parameter

extend accepts a comma-separated list of additional fields, from a closed set: variants, options, description, bindings, metadata, inventory, dimensions, seo, all.

extend=inventory and extend=all attach real stock

When you include inventory (or all) in extend, the response attaches available inventory per variant and per location — a variant's stock does not live in the product document (it's resolved by a join against the separate inventory collection), so without this extend the stock field simply doesn't appear.

curl "https://api.fenicia.io/products/CAM-ROJO-M?extend=inventory,seo" \
  -H "Authorization: Bearer fkapi_your_api_key"

Tip

For the full product data model (all fields, price/cost/media/binding sub-shapes, and the known divergences between the real schema and the public TS type), see the product data model.

Examples

curl https://api.fenicia.io/products/CAM-ROJO-M \
  -H "Authorization: Bearer fkapi_your_api_key"

Flat response, no data envelope

Unlike other domains of the Fenicia API, this endpoint responds with the Product object directly at the root of the JSON — not wrapped in {data: ...}.

Suggests similar products via semantic embeddings

skustringrequired

SKU of the reference product.

limitnumber

Number of results. Default: 10. Maximum: 50.

inStockboolean

Limits results to products with available stock.

200
{
  "products": [
    { "id": "65f3a1b2c4d5e6f7a8b9c0e2", "sku": "CAM-AZUL-M", "score": 0.87 }
  ],
  "count": 1,
  "sourceSku": "CAM-ROJO-M"
}
404
{ "code": "not-found", "message": "Product not found: CAM-ROJO-M" }

Permission required: products:read

Results use embeddings-based search with a minimum similarity threshold (minScore: 0.3) — products below that threshold don't appear, even if they belong to the same category. The 404 triggers when the internal error message contains the text "not found" (for example, when sourceSku doesn't exist).

Variants and options summary

Returns only the variants and options structure of a product, without the rest of its fields

skustringrequired

SKU of the parent product.

200
{
  "sku": "CAM-ROJO-M",
  "variants": [
    {
      "id": "65f3a1b2c4d5e6f7a8b9c0f1",
      "sku": "CAM-ROJO-M-CH",
      "title": { "value": "Camisa Roja - Chica" },
      "price": 499.00,
      "position": 0,
      "options": [{ "id": "opt-talla", "name": "Talla", "value": "CH" }]
    }
  ],
  "options": [{ "id": "opt-talla", "name": "Talla", "values": ["CH", "M", "G"] }],
  "hasVariants": true,
  "hasOptions": true
}
404
{ "code": "not-found", "message": "Product CAM-ROJO-M not found" }

Permission required: products:read

This same endpoint is also documented in Variants and media, together with the only write endpoint for existing variants.

Errors

CodeStatusDescription
not-found404No product resolves the given id/SKU in your tenant.

Authentication codes (invalid token, missing permission) are the same across the whole platform — see the full error catalog.

Tenant isolation

You can only query products from your own tenant. Attempting to access a product from another tenant returns 404, never cross-tenant information.

Next steps