# Syncing SKU Metadata

This guide provides a detailed walkthrough for enabling and utilizing SKU metadata through the Violet API. Metadata provides custom data applied by merchants to their products and is accessible through the Violet Offer and SKU objects. By following this guide, you will be able to enable SKU metadata syncing and include it in your API responses.

***

## **Step 1: Enable Metadata Syncing**

To enable the syncing of SKU metadata, you must use the **Toggle Global Feature Flag** endpoint in the Merchant Configuration API. Metadata syncing must be enabled for each merchant individually to avoid performance issues for merchants that do not use metadata.

* **Endpoint**: [Toggle Global Feature Flag](/api-reference/merchants/configuration/toggle-merchant-configuration-global-feature-flag.md)
* **Feature Flag to Enable**: `sync_sku_metadata`
* **Default Value**: `false`

### **Example Request**

```json
POST /v1/merchants/{merchant_id}/configuration/global_feature_flags/sync_sku_metadata
{
  "enabled": true
}
```

### **Key Notes**

* Enabling this flag allows SKU metadata to be included during catalog syncing.
* Be aware that enabling this feature may increase the time it takes to sync a merchant's catalog, as additional API calls are required to access metadata.

***

## **Step 2: Adding Metadata to API Responses**

### **Including SKU Metadata in Responses**

By default, SKU metadata is not included in the API responses. To include metadata, use the `include` query parameter with the value `sku_metadata`.

* **Query Parameter**: `include`
* **Value**: `sku_metadata`

### **Example Request**

```
GET /v1/catalog/skus/{sku_id}?include=sku_metadata

```

### **Supported Endpoints**

The following endpoints support the inclusion of SKU metadata:

* [Get All Merchant Offers](/api-reference/catalog/offers/get-all-merchant-offers.md)
* [Get Offer By Id](/api-reference/catalog/offers/get-offer-by-id.md)
* [Get SKU By Id](/api-reference/catalog/skus/get-sku-by-id.md)

***

## **Step 3: Understanding Metadata Schema**

When SKU metadata is included in the API response, it will be provided in the `metadata` property of the `Sku` object. The metadata will include the following fields:

### **Metadata Fields**

* **`version`**: The schema version for the metadata (currently `1.0`).
* **`type`**: The type of metadata value (e.g., `STRING`, `JSON`, `INTEGER`, `BOOLEAN`).
* **`external_type`**: The raw value type from the external commerce platform.
* **`key`**: The key or name representing the metadata.
* **`value`**: The value of the metadata.
* **`source`**: Source of the metadata (`EXTERNAL` for all current metadata).

### **Example Metadata Object**

```json
{
  "version": "1.0",
  "type": "STRING",
  "external_type": "text",
  "key": "custom_label",
  "value": "Limited Edition",
  "source": "EXTERNAL"
}
```

### **Handling JSON Metadata**

If the `type` property is `JSON`, the `value` property will contain a serialized JSON string.

### **Example JSON Metadata**

```json
{
  "type": "JSON",
  "key": "product_details",
  "value": "{\\"color\\":\\"red\\",\\"size\\":\\"M\\"}"
}
```

***

## **Step 4: Testing and Validation**

### **Testing Metadata Inclusion**

After enabling metadata syncing and adding the appropriate query parameter (`include=sku_metadata`), test the API responses to ensure that metadata is included.

### **Validation Checklist**

* Verify that the `metadata` property is present in the response.
* Confirm that the metadata fields match the expected schema (e.g., `version`, `type`, `key`, and `value`).
* For JSON metadata, ensure that the `value` property contains a valid serialized JSON string.

***

## **Best Practices**

1. **Enable Metadata Only If Necessary**: Since enabling metadata increases the time required for catalog syncing, it should only be enabled for merchants who specifically require it.
2. **Test Thoroughly**: Before deploying changes, test the integration with all relevant endpoints to confirm that metadata is included and correctly formatted.
3. **Monitor Performance**: Keep track of sync performance for merchants with metadata enabled to ensure that the additional API calls do not significantly impact overall performance.

***

By following these steps, you can successfully implement SKU metadata using the Violet API and provide merchants with access to their custom product data.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.violet.io/prism/catalog/metadata-syncing/sku-metadata.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.