Products

Filter Products

• GET /Products: Filters and returns a paginated collection of Product resources using OData query options.

Authentication

Requires a valid API key in the X-API-KEY header.

Headers

Accept-Language

Indicates the preferred natural language and locale for localized content.

• omitted / null: content in the tenant's default culture.
• culture-code (e.g. en-US, es): content localized in the specified culture.
• • and q-factor weighting are currently not supported.

OData Query Support

$select

Comma-separated list of root-resource property names to include in the response. See /Products/$metadata for the available properties. Selecting properties of embedded resources is not supported.

Example: $select=prod_description,prod_tags

$expand

Comma-separated list of embedded collections to include (e.g. Variants). By default, embedded collections are not included. Only embedded collections (not embedded resources) are supported.

Example: $expand=Variants

$filter

OData v4.01 URI conventions. Filtering is restricted to properties of the root resource (Product).

Comparison operators: eq, ne, gt, ge, lt, le

Logical operators: and, or, not

Set operator: in

String functions: contains, startswith, endswith

Examples:

• $filter=prod_ref eq 'SKU-001'
• $filter=contains(prod_description, 'pro')
• $filter=prod_id in (1, 2, 3)
• $filter=prod_id gt 100 and contains(prod_description, 'pro')

$orderby

Single property, ascending by default. Multi-property ordering and ordering on embedded properties are not supported.

Examples:

• $orderby=prod_description (asc by default)
• $orderby=prod_description asc
• $orderby=prod_ref desc

Pagination — $top, $skip, $skipToken

• $top — maximum number of items returned.
• $skip — number of items to skip (offset paging).
• $skipToken — continuation-token paging. Recommended when no $orderby is applied (faster than offset paging).

Paging applies only to the root resource (Product), never to embedded collections.

Response

200 OK — CollectionRepresentation with the matching Product resources, pagination metadata (Count, Skip, Top, HasNext, continuation token) and the cultures echoed from Accept-Language.

Error Responses

• 400 Bad Request — Invalid OData expression or unsupported $orderby/$filter field (returns ValidationFailureRepresentation).
• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Tenant or model not found.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products?$filter=contains(prod_description,'pro')&$orderby=prod_description asc&$top=20 HTTP/1.1 X-API-KEY: your-api-key-here Accept-Language: en-US

Response: http HTTP/1.1 200 OK Content-Type: application/json

Create Product

• POST /Products: Creates a new Product resource from the supplied JSON body and returns its location.

Authentication

Requires a valid API key in the X-API-KEY header.

Headers

Accept-Language

Culture used to interpret the localized field values supplied in the request body.

• omitted / null: tenant's default culture.
• culture-code (e.g. en-US, es): the specified culture.

Request Body

A single JSON object whose properties match the writable fields published by /Products/$metadata. The body is normalized before reaching the application layer:

• Must be a non-empty JSON object.
• A JSON array is accepted only if it contains exactly one element.
• Values are coerced to CLR primitives (string, long, double, bool, null), nested objects and arrays.

Response

201 Created — The Location header points to the new resource: /Products({id}). No response body.

Error Responses

• 400 Bad Request — Payload normalization or validation failure (empty body, multi-element array, invalid field values, etc.). Validation errors are returned as ValidationFailureRepresentation.
• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Tenant or referenced resource not found.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http POST /Products HTTP/1.1 X-API-KEY: your-api-key-here Accept-Language: en-US Content-Type: application/json

{ "prod_ref": "SKU-001", "prod_description": "New product", "cat_id": 123 }

Response: http HTTP/1.1 201 Created Location: /Products(456)

Get Product

• GET /Products({productIdentifier}): Returns a single Product resource by its identifier.

Authentication

Requires a valid API key in the X-API-KEY header.

Headers

Accept-Language

Indicates the preferred natural language and locale for localized content.

• omitted / null: content in the tenant's default culture.
• culture-code (e.g. en-US, es): content localized in the specified culture.
• • and q-factor weighting are currently not supported.

OData Query Support

$select

Comma-separated list of root-resource property names to include in the response. See /Products/$metadata for the available properties. Selecting properties of embedded resources is not supported.

Example: $select=prod_description,prod_tags

$expand

Comma-separated list of embedded collections to include (e.g. Variants). By default, embedded collections are not included. Only embedded collections (not embedded resources) are supported.

Example: $expand=Variants

Response

200 OK — EntityRepresentation with the Product resource.

Error Responses

• 400 Bad Request — Invalid OData expression (returns ValidationFailureRepresentation).
• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Product with the given identifier does not exist.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products(456)?$select=prod_description,prod_tags&$expand=Variants HTTP/1.1 X-API-KEY: your-api-key-here Accept-Language: en-US

Response: http HTTP/1.1 200 OK Content-Type: application/json

Update Product

• PATCH /Products({productId}): Updates an existing Product resource, applying only the fields supplied in the JSON body (PATCH semantics).

Authentication

Requires a valid API key in the X-API-KEY header.

Headers

Accept-Language

Culture used to interpret the localized field values supplied in the request body.

• omitted / null: tenant's default culture.
• culture-code (e.g. en-US, es): the specified culture.

Request Body

A single JSON object with the subset of writable fields to update (PATCH semantics — only the supplied fields are modified). Field names must match those published by /Products/$metadata. Normalization rules:

• Must be a non-empty JSON object.
• A JSON array is accepted only if it contains exactly one element.
• Values are coerced to CLR primitives, nested objects and arrays.
• The cat_id field is accepted as either a single integer or an array of integers to assign the product to one or several categories.

Response

200 OK — Update applied.

Error Responses

• 400 Bad Request — Payload normalization or validation failure (returns ValidationFailureRepresentation for validation errors).
• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Product with the given identifier does not exist.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http PATCH /Products(456) HTTP/1.1 X-API-KEY: your-api-key-here Accept-Language: en-US Content-Type: application/json

{ "prod_description": "Updated description", "cat_id": [123, 124] }

Response: http HTTP/1.1 200 OK

Delete Product

• DELETE /Products({productId}): Deletes the Product resource identified by the given identifier.

Authentication

Requires a valid API key in the X-API-KEY header.

Response

204 No Content — Product deleted.

Error Responses

• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Product with the given identifier does not exist.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http DELETE /Products(456) HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 204 No Content

Filter Product Variants

• GET /Products({productIdentifier})/Variants: Filters the Variant resources nested within the specified Product using OData query options and returns the matching collection.

Authentication

Requires a valid API key in the X-API-KEY header.

Headers

Accept-Language

Indicates the preferred natural language and locale for the localized content:

• culture-code (e.g. es, en-us) — returns content localized in the specified culture.
• null / not set — returns content localized in the default culture.
• • — currently disabled.

Multiple culture codes or q-factor weighting are not supported.

OData Query Support

The endpoint supports a subset of OData v4.01 URI conventions. The full list of available properties can be obtained from GET /Variants/$metadata.

$select

Comma-separated list of Variant properties (implicit or custom) to include in the result. Selection of properties inside embedded resources/collections is not supported.

• Example: frmt_ref
• Example: frmt_ref,frmt_tags

$expand

Comma-separated list of embedded collections to include in the result. By default, embedded collections are not included. Only embedded collections are supported (not embedded resources).

$filter

Boolean expression applied on root resource properties. Filtering on nested resource properties is not supported.

• Logical operators: eq, ne, gt, lt, ge, le, or, and, in
• String functions: contains, startswith, endswith
• Supported value types: integer, big integer, double, decimal, string, date, datetimeoffset

$orderby

Sorting expression on a single root resource property. Multiple properties and embedded properties are not supported. Format: PROPERTY (asc|desc). Default direction is asc.

$top

Page size. Maximum and default is 100 items.

$skip

Offset for the limit-and-offset paging strategy (used together with $top). Recommended when $orderby is required.

$skipToken

Continuation token for the continuation-token paging strategy. Faster than limit-and-offset but does not support $orderby.

Response

200 OK — Returns a CollectionRepresentation with the matching Variant resources associated to the Product.

Error Responses

• 400 Bad Request — Invalid OData expression or query parameter.
• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Product or tenant not found.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products(987)/Variants?$select=frmt_ref&$top=10 HTTP/1.1 X-API-KEY: your-api-key-here Accept-Language: es

Response: http HTTP/1.1 200 OK Content-Type: application/json

Get Product Variant

• GET /Products({productIdentifier})/Variants({variantIdentifier}): Returns a single Variant resource nested within the specified Product, with the published fields selected via OData query options.

Authentication

Requires a valid API key in the X-API-KEY header.

Headers

Accept-Language

Indicates the preferred natural language and locale for the localized content:

• culture-code (e.g. es, en-us) — returns content localized in the specified culture.
• null / not set — returns content localized in the default culture.
• • — currently disabled.

Multiple culture codes or q-factor weighting are not supported.

OData Query Support

The endpoint supports a subset of OData v4.01 URI conventions. The full list of available properties can be obtained from GET /Variants/$metadata.

$select

Comma-separated list of Variant properties (implicit or custom) to include in the result. Selection of properties inside embedded resources/collections is not supported.

• Example: frmt_ref
• Example: frmt_ref,frmt_tags

$expand

Comma-separated list of embedded collections to include in the result. By default, embedded collections are not included. Only embedded collections are supported (not embedded resources).

Response

200 OK — Returns an EntityRepresentation with the requested Variant.

Error Responses

• 400 Bad Request — Invalid OData expression or query parameter.
• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Product, Variant or tenant not found.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products(987)/Variants(12345)?$select=frmt_ref HTTP/1.1 X-API-KEY: your-api-key-here Accept-Language: es

Response: http HTTP/1.1 200 OK Content-Type: application/json

Get Products Changelog

• GET /Products/Changelog: Returns a paginated collection of changelog entries recording changes to Products, filterable with OData query options.

Authentication

Requires a valid API key in the X-API-KEY header.

OData Query Support

Supports $filter, $orderby, $top, $skip over the changelog fields. $select, $expand and $skipToken are not supported by this endpoint.

Response

200 OK — Collection of changelog entries (CollectionRepresentation).

Error Responses

• 400 Bad Request — Invalid OData expression.
• 401 Unauthorized — Missing or invalid API key.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products/Changelog?$orderby=changedAt desc&$top=50 HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 200 OK Content-Type: application/json

Get Product Changelog

• GET /Products({productIdentifier})/Changelog: Returns a paginated collection of changelog entries for a single Product, filterable with OData query options.

Authentication

Requires a valid API key in the X-API-KEY header.

OData Query Support

Supports $filter, $orderby, $top, $skip over the changelog fields. $select, $expand and $skipToken are not supported by this endpoint.

Response

200 OK — Collection of changelog entries for the specified Product.

Error Responses

• 400 Bad Request — Invalid OData expression.
• 401 Unauthorized — Missing or invalid API key.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products(123)/Changelog?$top=20 HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 200 OK Content-Type: application/json

Get Product Metadata

• GET /Products/$metadata: The metadata is a JSON Schema document that describes:
• The implicit and custom properties exposed by the Product resource.
• The associated resources (Category, Attribute Set, Variant) and their relationships.

The schema should be consulted to build requests against the other Product endpoints (which fields can be used in $select, $filter, $orderby, request bodies, etc.).

Authentication

Requires a valid API key in the X-API-KEY header.

Response

200 OK — Returns the JSON Schema as a ServiceDocumentRepresentation.

Error Responses

• 401 Unauthorized — Missing or invalid API key.
• 404 Not Found — Tenant or model not found.
• 500 Internal Server Error — Unexpected technical error.

Example

Request: http GET /Products/$metadata HTTP/1.1 X-API-KEY: your-api-key-here

Response: http HTTP/1.1 200 OK Content-Type: application/json