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
• Feature Flag to Enable: sync_sku_metadata
• Default Value: false

​

Example Request

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
• Get Offer By Id
• Get SKU By Id

​

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

{
  "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

{
  "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.