# Variants

## Filter Variants

- **Endpoint**: [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.
  - 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.

### $filter

- Boolean expression applied on root resource properties.
  - 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. 
  - 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).

### $skipToken

- Continuation token for the continuation-token paging strategy.

## 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:
```
GET /Variants?$select=frmt_ref&$top=10 HTTP/1.1
X-API-KEY: your-api-key-here
Accept-Language: es
```
Response:
```
HTTP/1.1 200 OK
Content-Type: application/json
```

## Create Variant

- **Endpoint**: [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.

## 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.
- 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:
```
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/1.1 201 Created
Location: /Variants(789)
```

## Get Variant

- **Endpoint**: [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.

### Request:
```
GET /Variants(12345)?$select=frmt_ref HTTP/1.1
X-API-KEY: your-api-key-here
Accept-Language: es
```
### Response:
```
HTTP/1.1 200 OK
Content-Type: application/json
```

## Update Variant

- **Endpoint**: [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.

## Request Body

A single JSON object with the subset of writable fields to update. Field names must match those published by /Variants/$metadata.

## Response

200 OK — Update applied.

## Error Responses

- 400 Bad Request — Payload normalization or validation failure.
- 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:
```
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/1.1 200 OK
```

## Delete Variant

- **Endpoint**: [DELETE /Variants({variantId})](https://docs.api.saleslayer.com/apis/catalog-v2.0/variants/deletevariantasync.md)
    - Deletes the Variant resource identified by its identifier.

## Response

204 No Content — Variant deleted.

## Example

Request:
```
DELETE /Variants(789) HTTP/1.1
X-API-KEY: your-api-key-here
```
Response:
```
HTTP/1.1 204 No Content
```

## Get Variants Changelog

- **Endpoint**: [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.

## Response

200 OK — Collection of changelog entries (CollectionRepresentation).

## Example

Request:
```
GET /Variants/Changelog?$orderby=changedAt desc&$top=50 HTTP/1.1
X-API-KEY: your-api-key-here
```
Response:
```
HTTP/1.1 200 OK
Content-Type: application/json
```

## Get Variant Metadata

- **Endpoint**: [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.

## Response

200 OK — Returns the JSON Schema as a ServiceDocumentRepresentation.