# Variants

## Filter Variants

 - [GET /Variants](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/filtervariantsasync.md): Filters the tenant's Variant resources 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
- Example: contains(frmt_ref, 'abc')
- Example: frmt_ref in ('A','B') and price gt 10
            
### $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.
- Example: frmt_ref 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.
            
## Error Responses
            
- 400 Bad Request — Invalid OData expression or query parameter.
- 401 Unauthorized — Missing or invalid API key.
- 404 Not Found — Tenant or resource not found.
- 500 Internal Server Error — Unexpected technical error.
            
## Example
            
Request:
http
GET /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

## Create Variant

 - [POST /Variants](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/createvariantasync.md): Creates a new Variant resource from the supplied JSON body and returns its location in the Location header.
            
## 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
/Variants/$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: /Variants({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 Product resource not found.
- 500 Internal Server Error — Unexpected technical error.
            
## Example
            
Request:
http
POST /Variants HTTP/1.1
X-API-KEY: your-api-key-here
Accept-Language: en-US
Content-Type: application/json
            
{
  "frmt_ref": "SKU-001-RED-M",
  "prod_id": 456
}

            
Response:
http
HTTP/1.1 201 Created
Location: /Variants(789)

## Get Variant

 - [GET /Variants({variantIdentifier})](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/searchvariantasync.md): Returns a single Variant resource identified by its identifier, 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 — Variant or tenant not found.
- 500 Internal Server Error — Unexpected technical error.
            
## Example
            
Request:
http
GET /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

## Update Variant

 - [PATCH /Variants({variantId})](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/updatevariantasync.md): Updates the writable fields of an existing Variant from the supplied JSON body using PATCH semantics (only the supplied fields are modified).
            
## 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
/Variants/$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.
            
## 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 — Variant with the given identifier does not exist.
- 500 Internal Server Error — Unexpected technical error.
            
## Example
            
Request:
http
PATCH /Variants(789) HTTP/1.1
X-API-KEY: your-api-key-here
Accept-Language: en-US
Content-Type: application/json
            
{
  "frmt_ref": "SKU-001-RED-L"
}

            
Response:
http
HTTP/1.1 200 OK

## Delete Variant

 - [DELETE /Variants({variantId})](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/deletevariantasync.md): Deletes the Variant resource identified by its identifier.
            
## Authentication
            
Requires a valid API key in the X-API-KEY header.
            
## Response
            
204 No Content — Variant deleted.
            
## Error Responses
            
- 401 Unauthorized — Missing or invalid API key.
- 404 Not Found — Variant with the given identifier does not exist.
- 500 Internal Server Error — Unexpected technical error.
            
## Example
            
Request:
http
DELETE /Variants(789) HTTP/1.1
X-API-KEY: your-api-key-here

            
Response:
http
HTTP/1.1 204 No Content

## Get Variants Changelog

 - [GET /Variants/Changelog](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/filtervariantschangelogasync.md): Returns the changelog entries recorded across the tenant's Variants, filtered and paged via 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 /Variants/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 Variant Changelog

 - [GET /Variants({variantIdentifier})/Changelog](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/filtervariantchangelogasync.md): Returns the changelog entries recorded for the Variant identified by its identifier, filtered and paged via 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 Variant.
            
## 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 /Variants(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 Variant Metadata

 - [GET /Variants/$metadata](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/getvariantmetadataasync.md): The metadata is a JSON Schema document that describes:
- The implicit and custom properties exposed by the Variant resource.
- The associated resources (Product) and their relationships.
            
The schema should be consulted to build requests against the other Variant 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 /Variants/$metadata HTTP/1.1
X-API-KEY: your-api-key-here

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