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
- Feature Flag to Enable:
sync_sku_metadata
- Default Value:
false
Example Request
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
Supported Endpoints
The following endpoints support the inclusion of SKU metadata:
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 (currently1.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
Handling JSON Metadata
If the type
property is JSON
, the value
property will contain a serialized JSON string.
Example JSON Metadata
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
, andvalue
). - For JSON metadata, ensure that the
value
property contains a valid serialized JSON string.
Best Practices
- 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.
- Test Thoroughly: Before deploying changes, test the integration with all relevant endpoints to confirm that metadata is included and correctly formatted.
- 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.