# Products

## Filter Products

 - [GET /Products](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/filterproductsasync.md): 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](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/createproductasync.md): 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})](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/searchproductasync.md): 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})](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/updateproductasync.md): 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})](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/deleteproductasync.md): 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](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/filtervariantsinproductasync.md): 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})](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/searchvariantinproductasync.md): 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](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/filterproductschangelogasync.md): 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](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/filterproductchangelogasync.md): 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](https://docs.api.saleslayer.com/apis/catalog-v2.0/products/getproductmetadataasync.md): 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