Variant and option models

Models for product variants, options and option values. Inspect variant prices, option assignments and create or update payloads.

Data schemas

List product variants — Response

ApiResponse_list_ProductVariantData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <ProductVariantData > Required: Response example · ApiResponse_list_ProductVariantData__.

Example: [{"active":true,"created_at":"2026-01-01T12:00:00Z","id":"example","is_default":true,"media_ids":["example"],"position":1,"pricing":{"base_adjustment":{"amount":"0.00","currency":"PLN","minor_units":2},"market_price":null,"price":{"amount":"0.00","currency":"PLN","minor_units":2,"tax_included":true},"product_version":1,"version":1},"primary_media_id":"example","product_id":"example","sku":"example","updated_at":"2026-01-01T12:00:00Z","values":[{"option_id":"example","option_name":"example","value":"example","value_id":"example"}],"version":1}]
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

List variant options — Response

ApiResponse_list_VariantOptionData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <shopently_engine__domains__catalog__adapters__public_http__dictionaries__schemas__VariantOptionData > Required: Response example · ApiResponse_list_VariantOptionData__.

Example: [{"created_at":"2026-01-01T12:00:00Z","id":"example","name":"Example","number":"example","position":1,"selection_type":"button","updated_at":"2026-01-01T12:00:00Z","value_presentation_type":"text","version":1}]
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

List variant option values — Response

ApiResponse_list_VariantValueData__ · Fields, types and constraints of data accepted or returned by the API.

dataArray <VariantValueData > Required: Response example · ApiResponse_list_VariantValueData__.

Example: [{"color_hex":"#008855","created_at":"2026-01-01T12:00:00Z","id":"example","image_media_id":null,"number":"example","option_id":"example","position":1,"sku_code":"example","updated_at":"2026-01-01T12:00:00Z","value":"example","version":1}]
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","pagination":{"has_more":false,"limit":20,"next_cursor":null},"request_id":"example"}

Additional fields: No

Get a product variant — Response

ApiResponse_ProductVariantData_ · Fields, types and constraints of data accepted or returned by the API.

dataProductVariantData Required: Response example · ProductVariantData.

Example: {"active":true,"created_at":"2026-01-01T12:00:00Z","id":"example","is_default":true,"media_ids":["example"],"position":1,"pricing":{"base_adjustment":{"amount":"0.00","currency":"PLN","minor_units":2},"market_price":null,"price":{"amount":"0.00","currency":"PLN","minor_units":2,"tax_included":true},"product_version":1,"version":1},"primary_media_id":"example","product_id":"example","sku":"example","updated_at":"2026-01-01T12:00:00Z","values":[{"option_id":"example","option_name":"example","value":"example","value_id":"example"}],"version":1}
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","request_id":"example"}

Additional fields: No

Get a variant option — Response

ApiResponse_VariantOptionData_ · Fields, types and constraints of data accepted or returned by the API.

datashopently_engine__domains__catalog__adapters__public_http__dictionaries__schemas__VariantOptionData Required: Response example · shopently_engine__domains__catalog__adapters__public_http__dictionaries__schemas__VariantOptionData.

Example: {"created_at":"2026-01-01T12:00:00Z","id":"example","name":"Example","number":"example","position":1,"selection_type":"button","updated_at":"2026-01-01T12:00:00Z","value_presentation_type":"text","version":1}
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","request_id":"example"}

Additional fields: No

Get a variant option value — Response

ApiResponse_VariantValueData_ · Fields, types and constraints of data accepted or returned by the API.

dataVariantValueData Required: Response example · VariantValueData.

Example: {"color_hex":"#008855","created_at":"2026-01-01T12:00:00Z","id":"example","image_media_id":null,"number":"example","option_id":"example","position":1,"sku_code":"example","updated_at":"2026-01-01T12:00:00Z","value":"example","version":1}
metaContextPageMeta ContextMeta PageMeta RequestMeta Required: Response metadata.

Example: {"locale":"en","market_code":"PL","market_id":"example","request_id":"example"}

Additional fields: No

Get a variant option — Response

shopently_engine__domains__catalog__adapters__public_http__dictionaries__schemas__VariantOptionData · Fields, types and constraints of data accepted or returned by the API.

created_atStringRequired

Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

idStringRequired

Resource identifier; preserve it as returned. (shopently_engine__domains__catalog__adapters__public_http__dictionaries__schemas__VariantOptionData).

Example: "example"

nameString nullRequired

Resource name in the relevant context.

Example: "Example"

numberStringRequired

Human-facing order or request number.

Example: "example"

positionIntegerRequired

Position in the ordered collection.

Example: 1

selection_typeStringRequired

Allowed feature-value selection mode.

Constraints

enum: ["button", "dropdown"]

Example: "button"

updated_atStringRequired

Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"

value_presentation_typeStringRequired

How dictionary values are presented.

Constraints

enum: ["text", "color", "image"]

Example: "text"

versionIntegerRequired

Resource version used for concurrency control.

Example: 1

Additional fields: No

Get a product variant — Response

ProductVariantData · Fields, types and constraints of data accepted or returned by the API.

activeBooleanRequired: Whether the resource is active.

Example: true
created_atStringRequired: Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"
idStringRequired: Resource identifier; preserve it as returned. (ProductVariantData).

Example: "example"
is_defaultBooleanRequired: Whether this is the default choice.

Example: true
media_idsArray <String> Required: Identifiers of already existing media assets.

Example: ["example"]
positionIntegerRequired: Position in the ordered collection.

Example: 1
pricingVariantPricingData Required: Price configuration and its concurrency versions.

Example: {"base_adjustment":{"amount":"0.00","currency":"PLN","minor_units":2},"market_price":null,"price":{"amount":"0.00","currency":"PLN","minor_units":2,"tax_included":true},"product_version":1,"version":1}
primary_media_idString nullRequired: Primary media asset identifier.

Example: "example"
product_idStringRequired: Product identifier.

Example: "example"
skuStringRequired: Stock keeping unit code.

Example: "example"
updated_atStringRequired: Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"
valuesArray <VariantChoiceData > Required: Dictionary values.

Example: [{"option_id":"example","option_name":"example","value":"example","value_id":"example"}]
versionIntegerRequired: Resource version used for concurrency control.

Example: 1

Additional fields: No

Dictionary values

VariantChoiceData · Schema · Variant and option models

option_idStringRequired: Variant option identifier.

Example: "example"
option_nameString nullRequired: Variant option name.

Example: "example"
valueString nullRequired: Value described by the surrounding schema.

Example: "example"
value_idStringRequired: Dictionary value identifier.

Example: "example"

Additional fields: No

Create a product variant — Request body

VariantCreate · Fields, types and constraints of data accepted or returned by the API.

activeBooleanOptional

Whether the resource is active.

Default: true

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

is_defaultBooleanOptional

Whether this is the default choice.

media_idsArray <String> Optional

Identifiers of already existing media assets.

maxItems: 20

Array:minLength: 1maxLength: 63

pricingVariantPrice Optional

Price configuration and its concurrency versions.

skuStringOptional

Stock keeping unit code.

minLength: 1maxLength: 100

Constraints

pattern: "^\\S+$"

value_idsArray <String> Required

Identifiers of dictionary values.

minItems: 1maxItems: 250

Array:minLength: 1maxLength: 63

Example: ["example"]

Additional fields: No

Create a variant option — Request body

VariantOptionCreate · Fields, types and constraints of data accepted or returned by the API.

nameStringRequired

Resource name in the relevant context.

minLength: 1maxLength: 120

Constraints

pattern: "^[^\\x00]*$"

Example: "Example"

selection_typeStringOptional

Allowed feature-value selection mode.

Constraints

enum: ["button", "dropdown"]

Default: "button"

value_presentation_typeStringOptional

How dictionary values are presented.

Constraints

enum: ["text", "color", "image"]

Default: "text"

Additional fields: No

Update a variant option — Request body

VariantOptionUpdate · Fields, types and constraints of data accepted or returned by the API.

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

nameString nullOptional

Resource name in the relevant context.

String:minLength: 1maxLength: 120

Constraints · String 1

pattern: "^[^\\x00]*$"

Example: "Example"

selection_typeStringOptional

Allowed feature-value selection mode.

Constraints

enum: ["button", "dropdown"]

value_presentation_typeStringOptional

How dictionary values are presented.

Constraints

enum: ["text", "color", "image"]

Additional fields: No

Price configuration and its concurrency versions

VariantPrice · Schema · Variant and option models

amountString nullRequired

Decimal amount encoded as a JSON string; null only where allowed.

String:maxLength: 20

Constraints · String 1

pattern: "^-?(0|[1-9][0-9]{0,13})(\\.[0-9]{1,4})?$"

Example: "0.00"

currencyStringRequired

Currency code for the amount.

Constraints

pattern: "^[A-Z]{3}$"

Example: "PLN"

expected_price_list_versionIntegerRequired

Previously read price-list version required for this write.

minimum: 1maximum: 9223372036854775807

Example: 1

expected_product_versionIntegerRequired

Previously read product version required for this write.

minimum: 0maximum: 9223372036854775807

Example: 1

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 0maximum: 9223372036854775807

Example: 0

kindStringRequired

Variant of the data structure described by its allowed values.

Constraints

enum: ["base_adjustment", "market_fixed"]

Example: "base_adjustment"

price_list_idStringRequired

Price-list identifier.

minLength: 1maxLength: 63

Example: "example"

Additional fields: No

Price configuration and its concurrency versions

VariantPricingData · Schema · Variant and option models

base_adjustmentMoneyData Required: Price adjustment relative to the base price.

Example: {"amount":"0.00","currency":"PLN","minor_units":2}
market_priceMoneyData nullRequired: Price for the selected market.

Example: null
pricePriceData nullRequired: Price information in the selected context.

Example: {"amount":"0.00","currency":"PLN","minor_units":2,"tax_included":true}
product_versionIntegerRequired: Current product version for concurrency control.

Example: 1
versionIntegerRequired: Resource version used for concurrency control.

Example: 1

Additional fields: No

Update a product variant — Request body

VariantUpdate · Fields, types and constraints of data accepted or returned by the API.

activeBooleanOptional

Whether the resource is active.

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

is_defaultBooleanOptional

Whether this is the default choice.

media_idsArray <String> Optional

Identifiers of already existing media assets.

maxItems: 20

Array:minLength: 1maxLength: 63

pricingVariantPrice Optional

Price configuration and its concurrency versions.

Example:

{"amount":"0.00","currency":"PLN","expected_price_list_version":1,"expected_product_version":1,"expected_version":0,"kind":"base_adjustment","price_list_id":"example"}

skuStringOptional

Stock keeping unit code.

minLength: 1maxLength: 100

Constraints

pattern: "^\\S+$"

Example: "example"

Additional fields: No

Create a variant option value — Request body

VariantValueCreate · Fields, types and constraints of data accepted or returned by the API.

color_hexString nullOptional

Colour represented by a hexadecimal code.

Constraints · String 1

pattern: "^#[0-9A-Fa-f]{6}$"

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

valueStringRequired

Value described by the surrounding schema.

minLength: 1maxLength: 180

Constraints

pattern: "^[^\\x00]*$"

Example: "Example"

Additional fields: No

Get a variant option value — Response

VariantValueData · Fields, types and constraints of data accepted or returned by the API.

color_hexString nullRequired: Colour represented by a hexadecimal code.

Example: "#008855"
created_atStringRequired: Creation time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"
idStringRequired: Resource identifier; preserve it as returned. (VariantValueData).

Example: "example"
image_media_idString nullRequired: Identifier of the selected image asset.

Example: null
numberStringRequired: Human-facing order or request number.

Example: "example"
option_idStringRequired: Variant option identifier.

Example: "example"
positionIntegerRequired: Position in the ordered collection.

Example: 1
sku_codeStringRequired: Stock keeping unit code.

Example: "example"
updated_atStringRequired: Most recent update time.

format: "date-time"

Example: "2026-01-01T12:00:00Z"
valueString nullRequired: Value described by the surrounding schema.

Example: "example"
versionIntegerRequired: Resource version used for concurrency control.

Example: 1

Additional fields: No

Update a variant option value — Request body

VariantValueUpdate · Fields, types and constraints of data accepted or returned by the API.

color_hexString nullOptional

Colour represented by a hexadecimal code.

Constraints · String 1

pattern: "^#[0-9A-Fa-f]{6}$"

expected_versionIntegerRequired

Version read before the write; a mismatch rejects the update.

minimum: 1maximum: 9223372036854775807

Example: 1

valueString nullOptional

Value described by the surrounding schema.

String:minLength: 1maxLength: 180

Constraints · String 1

pattern: "^[^\\x00]*$"

Example: "Example"

Additional fields: No