BizKitHub
DocsAPI ReferenceProduct/bff/product/product-detail
getProductAdmin BFF

/bff/product/product-detail

Returns full product detail including all editable fields, custom fields, field definitions, and linked events. Translatable fields (name, descriptions) are resolved from the translation table with locale fallback.

ProductgetBffProductProduct-detail

Parameters

2 query

Query parameters

· 2
productCodestringRequired

Unique product code.

Examplemy-product
localestringOptional

Locale code for translated fields. Falls back to primary locale if not provided.

Examplecs

Response schema

1 status code documented

200Success
idstringRequired

Product code (used as identifier).

codestringRequired

Unique product code.

namestringRequired

Product name (translated if locale is specified).

slugstringRequired

URL slug.

eanstringOptional

EAN barcode.

shortDescriptionstringRequired

Short HTML description.

longDescriptionstringRequired

Long HTML description.

internalNotestringRequired

Internal note (admin only).

activebooleanRequired

Whether the product is active.

deletedbooleanRequired

Whether the product is soft-deleted (legacy boolean — prefer deletedDate).

deletedDatestringOptional

ISO timestamp when the product was soft-deleted. Canonical signal for soft-delete; absent on live products.

b2bbooleanRequired

Whether the product is B2B only.

showInFeedbooleanRequired

Whether the product appears in product feeds.

soldOutbooleanRequired

Whether the product is sold out.

mainImageUrlstringOptional

URL of the main product image (source blob).

mainImageobjectOptional

Full main-image payload with all pre-rendered variants (issue #80).

Rendering contract for the FE: always paint lqip immediately as a CSS background, then progressively enhance with whichever sharp variant matches the intended display size — thumbUrl (≤ 128 px), cardUrl (≤ 480 px), heroUrl (≤ 1280 px), zoomUrl (≤ 2048 px). Fall back to originalUrl only for lightbox / download-as-image cases where the pre-rendered variants are insufficient.

Nullable slots vs. progressive rendering: every variant slot is present on the wire; null means scout hasn't rendered that particular size yet. The read model is rebuilt automatically the moment all four variants land, so a subsequent fetch will return the URLs — usually within seconds of a fresh upload, longer under scout backlog. Never fall back to originalUrl for a null variant in list UIs — that would defeat the whole point of pre-generating right-sized derivatives.

idstringRequired

External blob token of the source image (stable across variant regenerations). Use this to correlate frontend cache keys and re-request the payload after an update.

Examplea1b2c3d4e5f6g7h8
originalUrlstringRequired

Public CDN URL of the original upload — always present when the product has a main image.

Format: whatever the operator uploaded (typically JPEG or PNG, occasionally WebP or AVIF). Dimensions and byte size are unbounded and depend on the source; expect anywhere from 200 KB to several MB.

Use cases:

  • Lightbox / zoom UI that needs the highest fidelity available (fallback for zoom variant).
  • Downloadable "original" link.
  • Feeds for third parties that expect an unmodified source.

Do not use the original for above-the-fold rendering or list thumbnails — the pipeline exists precisely so those cases can bind to a pre-rendered, right-sized WebP variant instead.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.jpg
lqipstringRequired

needed to render it.

Intended use: paint immediately as a CSS background-image on the wrapper element. Once one of the sharp variants (thumbUrl, cardUrl, heroUrl, zoomUrl) finishes loading, fade it in on top; the LQIP remains behind and covers any transparent pixels.

Edge case: an empty string is possible only if the source blob was unreadable when the LQIP was generated (sharp threw and no fallback was stored). Treat empty as "no LQIP available" and skip the background paint.

Exampledata:image/webp;base64,UklGRi4AAABXRUJQVlA4ICI…
thumbUrlstring | nullRequired
One of 2:
Variant 1
string

Scout-generated 128×128 WebP thumbnail URL, or null while the variant hasn't been rendered yet (see § "When null" below).

Dimensions: 128×128 px, square, cover-cropped. Format: WebP q75. Byte range: ~4–14 KB per file.

Intended use: row-level thumbnails in lists, autocomplete dropdowns, chat message previews, notification cards, mobile grid cells (60–120 px). At this size no other variant is worth requesting.

When null: the source image has been uploaded but the scout worker on the Contabo VPS hasn't finished rendering this variant yet. Fall back to the LQIP blur alone (with an optional "processing" overlay for cells ≥ 80 px). The read model is rebuilt automatically the moment all four variants land, so a subsequent fetch will return a non-null URL — usually within seconds for a fresh upload, longer under scout backlog.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.thumb-webp.webp
Variant 2
null
cardUrlstring | nullRequired
One of 2:
Variant 1
string

Scout-generated 480×480 WebP URL, or null while the variant hasn't been rendered yet.

Dimensions: 480×480 px, square, cover-cropped. Format: WebP q80. Byte range: ~15–45 KB per file.

Intended use: medium-sized product previews — product-detail sidebar (240–520 px), category grid tiles on mobile / small desktop, storefront cards, hover popovers, e-mail template thumbnails. The single most-used variant in typical e-shop UI.

When null: same story as thumbUrl — variant not yet rendered by scout. Prefer thumbUrl (if available) as a temporary substitute over the LQIP blur alone.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.card-webp.webp
Variant 2
null
heroUrlstring | nullRequired
One of 2:
Variant 1
string

Scout-generated 1280×1280 WebP URL, or null while the variant hasn't been rendered yet.

Dimensions: 1280×1280 px, square, cover-cropped. Format: WebP q82. Byte range: ~50–150 KB per file.

Intended use: large product previews — desktop product-detail hero image (520–1280 px), homepage feature slots, campaign landing pages, retina 2× rendering for card-sized cells.

When null: same story as thumbUrl — variant not yet rendered by scout. If falling back, prefer cardUrl over thumbUrl when the intended display size is > ~480 px.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.hero-webp.webp
Variant 2
null
zoomUrlstring | nullRequired
One of 2:
Variant 1
string

Scout-generated 2048×2048 WebP URL, or null while the variant hasn't been rendered yet.

Dimensions: 2048×2048 px, square, cover-cropped. Format: WebP q82. Byte range: ~150–400 KB per file.

Intended use: lightbox / product-image zoom UI, retina 2× rendering for hero-sized cells, download-as-image feature. The largest pre-rendered variant — for anything sharper, fall back to originalUrl (unbounded, unmodified source).

When null: same story as thumbUrl — variant not yet rendered by scout. If a lightbox request comes in before zoomUrl is ready, use originalUrl as an interim fallback so the feature still works.

Examplehttps://storage.xhp.cz/org-slug/product/2026-08/abc123.zoom-webp.webp
Variant 2
null
mainCategoryIdnumberOptional

Internal ID of the main category.

brandIdnumberOptional

Internal ID of the brand.

defaultCurrencystringRequired

Default currency code (e.g. "CZK").

pricenumberRequired

Price with VAT as a number.

costnumberRequired

Internal cost in the organisation default currency. 0 when not set. Snapshotted onto shop__order_item.cost at order creation, FX-converted to the order currency.

standardPricePercentagenumberOptional

Standard price percentage for discount calculation.

vatnumberOptional

VAT rate percentage.

sizeWidthMmnumberOptional

Product width in millimeters.

sizeHeightMmnumberOptional

Product height in millimeters.

sizeDepthMmnumberOptional

Product depth in millimeters.

weightGramsnumberOptional

Product weight in grams.

warehouseAllQuantitynumberOptional

Total warehouse stock quantity.

warehouseLimitnumberOptional

Minimum stock level before reorder alert.

isVariantProductbooleanRequired

Whether the product has variants.

variantCountnumberRequired

Number of product variants.

customFieldsobject[]Required

Custom fields attached to the product.

Each array item:
keystringRequired

Custom field key identifier.

valuestringRequired

Custom field value.

activebooleanRequired

Whether the field is active.

insertedDateDate | string | string | numberRequired

Date when the field was created/updated.

One of 4:
Variant 1
Date

Date when the field was created/updated.

Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
customFieldsDefinitionobject[]Required

Available custom field definitions for the product category.

Each array item:
keystringRequired

Field key identifier.

typestringRequired

Field type: text, textarea, number, or boolean.

labelstringRequired

Display label for the field.

helperTextstringOptional

Helper text shown below the field.

placeholderstringOptional

Placeholder text for the input.

requiredbooleanRequired

Whether the field is required.

validationPatternstringOptional

Regex pattern for validation.

eventListobject[]Required

Calendar events linked to this product.

Each array item:
idstringRequired

Event code.

type"direct" | "eventType"Required

How the event is linked: directly or via event type.

titlestringRequired

Event title.

isStornobooleanRequired

Whether the event is cancelled.

startTimeDate | string | string | numberRequired

Event start time.

One of 4:
Variant 1
Date

Event start time.

Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
endTimeDate | string | string | numberRequired

Event end time.

One of 4:
Variant 1
Date

Event end time.

Variant 2
stringdate-time
Variant 3
stringdate
Variant 4
number
typeCodestringOptional

Event type code.

typeLabelstringOptional

Event type label.

typeColorstringOptional

Event type color (hex, e.g. "#FF5733").

translatedLocalesstring[]Required

Locales for which a translation exists in shop__product_translation.

Locale code (e.g. "cs", "en").

voucherTemplateCountnumberRequired

Number of voucher templates linked to this product.

subscriptionPlanCountnumberRequired

Number of subscription plans linked to this product.

pricelistRulesobject[]Required

Dynamic pricing rules. Empty array on products with static pricing.

Each array item:
idstringRequired

Stable UUID — preserved across edits.

namestringRequired

Human label shown in the rule grid.

enabledbooleanRequired

Whether the resolver considers this rule.

prioritynumberRequired

Higher value wins; ties broken by specificity.

validFromstring | nullRequired

Inclusive lower date bound (YYYY-MM-DD).

One of 2:
Variant 1
string
Variant 2
null
validTostring | nullRequired

Inclusive upper date bound (YYYY-MM-DD).

One of 2:
Variant 1
string
Variant 2
null
weekdaysnumber[] | nullRequired

Allowed ISO weekdays (Mon=1 … Sun=7), or null for every day.

One of 2:
Variant 1
number[]
Variant 2
null
timeFromstring | nullRequired

Inclusive lower time-of-day bound (HH:mm).

One of 2:
Variant 1
string
Variant 2
null
timeTostring | nullRequired

Inclusive upper time-of-day bound (HH:mm). When < timeFrom the window crosses midnight.

One of 2:
Variant 1
string
Variant 2
null
variantCodestring | nullRequired

Variant code scope, or null for all variants.

One of 2:
Variant 1
string
Variant 2
null
pricenumberRequired

Price applied when this rule wins.

Response example

application/json
{
  "id": "example_id",
  "code": "example_code",
  "name": "example_name",
  "slug": "example_slug",
  "ean": "example_ean",
  "shortDescription": "example_shortDescription",
  "longDescription": "example_longDescription",
  "internalNote": "example_internalNote",
  "active": false,
  "deleted": false,
  "deletedDate": "example_deletedDate",
  "b2b": false,
  "showInFeed": false,
  "soldOut": false,
  "mainImageUrl": "example_mainImageUrl",
  "mainImage": {
    "id": "a1b2c3d4e5f6g7h8",
    "originalUrl": "https://storage.xhp.cz/org-slug/product/2026-08/abc123.jpg",
    "lqip": "data:image/webp;base64,UklGRi4AAABXRUJQVlA4ICI…"
  },
  "mainCategoryId": 0,
  "brandId": 0,
  "defaultCurrency": "example_defaultCurrency",
  "price": 0,
  "cost": 0,
  "standardPricePercentage": 0,
  "vat": 0,
  "sizeWidthMm": 0,
  "sizeHeightMm": 0,
  "sizeDepthMm": 0,
  "weightGrams": 0,
  "warehouseAllQuantity": 0,
  "warehouseLimit": 0,
  "isVariantProduct": false,
  "variantCount": 0,
  "customFields": [
    {
      "key": "example_key",
      "value": "example_value",
      "active": false
    }
  ],
  "customFieldsDefinition": [
    {
      "key": "example_key",
      "type": "example_type",
      "label": "example_label",
      "helperText": "example_helperText",
      "placeholder": "example_placeholder",
      "required": false,
      "validationPattern": "example_validationPattern"
    }
  ],
  "eventList": [
    {
      "id": "example_id",
      "title": "example_title",
      "isStorno": false,
      "typeCode": "example_typeCode",
      "typeLabel": "example_typeLabel",
      "typeColor": "example_typeColor"
    }
  ],
  "translatedLocales": [
    "string"
  ],
  "voucherTemplateCount": 0,
  "subscriptionPlanCount": 0,
  "pricelistRules": [
    {
      "id": "example_id",
      "name": "example_name",
      "enabled": false,
      "priority": 0,
      "price": 0
    }
  ]
}

Request example

GET /bff/product/product-detail

get
curl -X GET "https://api.bizkithub.com/bff/product/product-detail?productCode=my-product&locale=cs" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY"

Need an API key?

All BizKitHub public API endpoints require authentication via API key.

Get API Key