Merchant Configurations
This page describes the available configuration options for merchants, including feature flags, store settings, order behaviors, shipping configuration, and catalog sync policies. Feature flags are organized into two categories: Global flags that apply regardless of commerce platform, and Platform-specific flags that only apply when using certain commerce platforms.
Managing Feature Flags via API
Merchant configuration can be retrieved and managed programmatically using the following API endpoints:
Get Merchant Config - Retrieve the current configuration for a merchant, including all feature flags
Toggle Global Feature Flag - Enable or disable a global feature flag for a merchant
Merchant Configuration is currently in beta. These properties may change at any time.
Global Feature Flags
These flags apply to a merchant globally, regardless of their commerce platform. Set these in the global_feature_flags map. Global feature flags can be toggled using the Toggle Global Feature Flag API endpoint.
sync_metadata
Disabled
When enabled, synchronizes product-level metadata (custom fields, tags, vendor info) from the commerce platform. Requires explicit true.
sync_sku_metadata
Disabled
When enabled, synchronizes SKU-level metadata including variant-specific custom fields. Also triggers expanded SKU data collection for richer variant information. Requires explicit true.
sync_taxonomy
Enabled
When enabled, synchronizes product taxonomy and category hierarchies from the commerce platform. Set to false to disable.
sync_collections
Disabled
When enabled, synchronizes product collections/groupings (e.g., Shopify collections, Wix collections). Requires explicit true.
truify_offer_visibility
Disabled
When enabled, forces offer visibility to true during catalog sync, overriding the source platform's visibility settings. Requires explicit true.
disable_hidden_offers
Disabled
When enabled, sets hidden/draft products to disabled status rather than syncing their original visibility. Requires explicit true.
auto_publish_offers
Enabled
When enabled, automatically publishes offers after creation or update. Set to false to require manual publishing.
sync_offer_sale_price
Enabled
When enabled, synchronizes sale/promotional prices alongside regular prices. Set to false to ignore sale prices.
sync_offer_shipping
Disabled
When enabled, synchronizes product-level shipping data including weight, dimensions, and shipping class. Requires explicit true.
use_contextual_prices
Disabled
When enabled, fetches and stores region or customer-segment specific pricing. Also triggers expanded SKU data collection. Requires explicit true.
log_ecom_service_client
Disabled
When enabled, activates detailed trace logging for all commerce platform API calls including request/response bodies. Useful for debugging. Requires explicit true.
exclude_hidden_offers
Disabled
When enabled, completely excludes hidden/draft products from catalog sync rather than syncing them as disabled. Requires explicit true.
bypass_inventory_policies
Disabled
When enabled, ignores commerce platform inventory policies and availability rules. Products are considered in-stock if purchasable, regardless of inventory tracking settings. Requires explicit true.
proxy_original_customer_email
Disabled
When enabled, forwards the original customer email address during order submission rather than using a proxy email. Requires explicit true.
enable_addon_sku_injection
Disabled
When enabled, automatically injects addon SKUs into orders based on configured rules in orders_config.conventions.addon_sku_config. Requires explicit true.
Platform Feature Flags
These flags apply to a merchant depending on their commerce platform. Set these in the platform_feature_flags map.
Shopify
use_custom_shipping_rates
Enabled
When enabled, allows custom shipping rates via the DraftOrders API. Set to false to disable.
filter_by_collections
Disabled
When enabled, filters product sync to only include products from collections specified in shopify_config.enabled_collection_ids. Requires explicit true.
use_graph_products
N/A
Legacy flag for GraphQL product sync. As of 2025.06.22, GraphQL is always used regardless of this setting.
populate_order_note_field
Enabled
When enabled, populates the Shopify order note field with the platform Order ID for merchant reference. Set to false to disable.
filter_inventory_by_locations
Disabled
When enabled, filters inventory to only include stock from locations specified in shopify_config.enabled_location_ids. Requires explicit true.
disable_offline_offers
Disabled
When enabled, disables offers that are not published to the Shopify Online Store sales channel. Requires explicit true.
use_native_order_name
Disabled
When enabled, uses Shopify's native order naming convention during order writeback instead of the platform's order ID. Requires explicit true.
use_storefront_api
Disabled
When enabled, uses the Shopify Storefront API for product sync and order writeback, allowing merchants to control product availability via Product Listings. Requires explicit true.
use_cart_estimation
Disabled
When enabled, creates a draft order for shipping rate estimation instead of using draft order calculation. Requires explicit true.
redistribute_taxes
Disabled
When enabled, requests tax distribution from Shopify during order creation and assigns taxes as line items. Requires explicit true.
WooCommerce
use_short_description
Disabled
When enabled, syncs the WooCommerce short description field instead of the full product description. Requires explicit true.
sync_duplicate_sku_media
Disabled
When enabled, syncs media for products with duplicate SKUs. Requires explicit true.
use_basic_auth
Disabled
When enabled, uses HTTP Basic Authentication instead of OAuth for WooCommerce API calls. Requires explicit true.
filter_by_categories
Disabled
When enabled, filters product sync to only include products from categories specified in the platform config. Requires explicit true.
Salesforce Commerce Cloud (SFCC)
filter_by_catalog
Disabled
When enabled, filters products and collections to only those in catalogs specified in sfcc_config.enabled_catalog_ids. Requires explicit true.
filter_by_categories
Disabled
When enabled, filters product sync to only include products from categories specified in the platform config. Requires explicit true.
BigCommerce
use_price_lists
Disabled
When enabled, uses BigCommerce price lists for pricing from bigcommerce_config.enabled_price_list_ids. Requires explicit true.
filter_inventory_by_locations
Disabled
When enabled, filters inventory to only include stock from locations specified in bigcommerce_config.enabled_location_ids. Requires explicit true.
filter_by_categories
Disabled
When enabled, filters product sync to only include products from categories specified in the platform config. Requires explicit true.
CommerceTools
filter_inventory_by_channels
Disabled
When enabled, filters inventory to only include stock from channels specified in commercetools_config.enabled_channel_ids. Requires explicit true.
Wix
filter_by_collections
Disabled
When enabled, filters product sync to only include products from collections specified in the platform config. Requires explicit true.
Prestashop
use_short_description
Disabled
When enabled, syncs the Prestashop short description field instead of the full product description. Requires explicit true.
Ecwid
filter_by_categories
Disabled
When enabled, filters product sync to only include products from categories specified in the platform config. Requires explicit true.
Magento
filter_by_categories
Disabled
When enabled, filters product sync to only include products from categories specified in the platform config. Requires explicit true.
Cross-Platform Flag Reference
Some flags apply to multiple platforms. The table below shows which platforms support each cross-platform flag.
filter_by_collections
Shopify, Wix
filter_inventory_by_locations
Shopify, BigCommerce
use_short_description
WooCommerce, Prestashop
filter_by_categories
WooCommerce, BigCommerce, SFCC, Ecwid, Magento
Additional Configuration Options
The following configuration options are currently maintained by Violet. API access for channels to manage these configurations directly will become available over time. If you need any of these configurations applied to a merchant, or if you have questions about the available options, please reach out to the Violet team.
Store Configuration
The store_config object contains default settings for a merchant's store.
default_weight_unit
String
Default weight unit used by the merchant (e.g., KG, LB, OZ, G).
default_size_unit
String
Default size/dimension unit used by the merchant (e.g., CM, IN).
default_locale
String
Default locale used by the merchant (e.g., en-US).
default_currency
String
Default currency code used by the merchant (e.g., USD, EUR).
base_url
String
Base URL of the merchant's store.
base_media_url
String
Base URL for media assets from the merchant's store.
Orders Configuration
The orders_config object controls order submission behaviors, sync policies, and order conventions.
Basic Order Settings
commerce_disabled
Boolean
false
When true, disables order creation and cart submission for this merchant.
order_prefix
String
null
When supported by the commerce platform, this prefix will be used for orders.
custom_tags
Set<String>
null
Custom tags to be added to a merchant's orders upon submission.
prohibit_order_cancellations
Boolean
false
When true, prohibits order cancellations for this merchant.
prohibit_order_refunds
Boolean
false
When true, prohibits order refunds for this merchant.
force_push_orders
Boolean
false
When true, orders will be force-pushed to the commerce platform even if items are out of stock.
Order Sync Policy
The sync_policy object within orders_config controls how order status updates are synchronized.
sync_type
Enum
The synchronization strategy: POLLING, HYBRID, or NO_SYNC.
sync_frequency_minutes
Integer
How often to poll for order updates (when using POLLING or HYBRID).
consolidation_frequency_minutes
Integer
How often to consolidate order data.
Sync Types:
POLLING
Periodically polls the commerce platform for order updates.
HYBRID
Combines webhook-based updates with periodic polling for reliability.
NO_SYNC
Disables automatic order synchronization.
Addon SKU Injection
When the enable_addon_sku_injection global feature flag is enabled, Violet can configure rules to automatically inject additional SKUs into orders based on product tags.
Addon SKU rules are configured in orders_config.conventions.addon_sku_config.rules:
rule_name
String
Human-readable name for this rule (for logging/debugging).
match_tags
Set<String>
Offer tags that trigger this rule. If an Offer has ANY of these tags, the addon is injected.
addon_sku_id
Long
The SKU ID to inject when the rule matches.
quantity_multiplier
Integer
Multiplier for addon quantity. Addon qty = original SKU qty × multiplier. Default: 1.
reason
String
Optional descriptor for why this addon is injected (e.g., "return-packaging").
enabled
Boolean
Whether this rule is active. Default: true.
Example Use Case: Automatically add return packaging materials when orders contain items tagged with "returnable".
Shipping Configuration
The shipping_config object controls shipping method behaviors, fallback options, and exclusion rules.
Fallback Shipping Methods
When a merchant's commerce platform provides no shipping methods, Violet can configure fallback methods in shipping_config.fallback_methods.
Each fallback shipping method supports:
label
String
The display name of the shipping method.
description
String
Description of the shipping method.
price
Integer
The price of the shipping method in cents.
currency
String
The currency code (e.g., USD).
handle
String
The handle or external ID to use when utilizing this method.
calculation_type
Enum
PER_ORDER or PER_ITEM - whether the price applies to the entire order or per item.
conditions
Object
Conditions that determine when this shipping method is applicable.
Shipping Method Conditions
applicable_countries
Set<String>
ISO Alpha-2 country codes where this method can be applied.
inapplicable_countries
Set<String>
ISO Alpha-2 country codes where this method cannot be applied.
applicable_offer_ids
Set<Long>
Offer IDs that this shipping method is applicable to.
inapplicable_offer_ids
Set<Long>
Offer IDs that this shipping method is not applicable to.
min_order_amount
Integer
Minimum order amount (in cents) required for this method.
max_order_amount
Integer
Maximum order amount (in cents) for this method to be applicable.
min_weight
Object
Minimum order weight for this method (value and unit: KG, LB, OZ).
max_weight
Object
Maximum order weight for this method.
Simple Exclusion Flags
exclude_external_free_shipping
Boolean
false
When true, excludes free shipping methods from external platforms.
exclude_external_methods
Boolean
false
When true, excludes all shipping methods from external platforms.
Shipping Exclusions
For more granular control over which external shipping methods are excluded, Violet can configure shipping_config.shipping_exclusions. This supports both global exclusions (apply to all orders) and compound rules (conditional based on cart contents).
Global Shipping Exclusions
These exclusions apply unconditionally to all carts.
excluded_names
Set<String>
Exact shipping method names/labels to exclude (case-insensitive).
excluded_name_patterns
Set<String>
Substrings to match against shipping method names (case-insensitive contains match).
excluded_ids
Set<String>
Shipping method IDs or handles to exclude.
price_rules
Object
Price-based exclusion rules (see below).
Price Exclusion Rules (price_rules):
exclude_above
Integer
Exclude methods with price ≥ this value (in cents).
exclude_below
Integer
Exclude methods with price ≤ this value (in cents).
excluded_prices
Set<Integer>
Specific price values to exclude (in cents).
exclude_free
Boolean
Exclude free shipping methods (price = 0).
Compound Exclusion Rules
Compound rules in shipping_exclusions.exclusion_rules combine method matching criteria with offer-based conditions, allowing Violet to exclude certain shipping methods only when specific products are in the cart.
Each rule contains:
rule_name
String
Descriptive name for debugging/logging.
enabled
Boolean
Whether this rule is active. Default: true.
method_criteria
Object
Criteria for matching shipping methods to exclude.
offer_conditions
Object
Conditions based on cart contents.
Method Match Criteria
Criteria for identifying which shipping methods to exclude. Multiple criteria use OR logic.
Name-Based Filters:
names
Set<String>
Exact method names (case-insensitive).
name_patterns
Set<String>
Substrings to match (case-insensitive contains).
name_prefixes
Set<String>
Prefixes to match at start of names.
name_suffixes
Set<String>
Suffixes to match at end of names.
ID-Based Filters:
ids
Set<String>
Exact method IDs/handles.
id_patterns
Set<String>
Substrings to match in IDs.
id_prefixes
Set<String>
Prefixes to match in IDs.
Price-Based Filters:
price_above
Integer
Match methods with price ≥ this value (cents).
price_below
Integer
Match methods with price ≤ this value (cents).
price_between
Object
Match methods within a price range (min and max in cents).
prices
Set<Integer>
Match methods with these exact prices.
is_free
Boolean
Match free shipping methods (price = 0).
Carrier-Based Filters:
carriers
Set<String>
Carrier names to match (e.g., "UPS", "FedEx"). Case-insensitive.
carrier_patterns
Set<String>
Substrings to match in carrier names.
Service Level Filters:
service_levels
Set<String>
Service level codes (e.g., "GROUND", "EXPRESS", "OVERNIGHT").
exclude_expedited
Boolean
Match expedited/express methods.
exclude_overnight
Boolean
Match overnight/next-day methods.
exclude_ground
Boolean
Match ground/standard methods.
Delivery Time Filters:
min_delivery_days
Integer
Match methods with estimated delivery ≥ this many days.
max_delivery_days
Integer
Match methods with estimated delivery ≤ this many days.
Offer Conditions
Conditions that determine when an exclusion rule applies based on cart contents.
Product-Based Conditions:
applicable_offer_ids
Set<Long>
Rule applies only when cart contains these offer IDs.
inapplicable_offer_ids
Set<Long>
Rule does NOT apply when cart contains these offer IDs (override/exemption).
applicable_sku_ids
Set<Long>
Rule applies only when cart contains these SKU IDs.
inapplicable_sku_ids
Set<Long>
Rule does NOT apply when cart contains these SKU IDs.
applicable_external_sku_ids
Set<String>
Rule applies only when cart contains SKUs with these external IDs.
inapplicable_external_sku_ids
Set<String>
Rule does NOT apply when cart contains SKUs with these external IDs.
Category/Tag/Collection Conditions:
applicable_categories
Set<String>
Rule applies only when cart contains offers in these categories.
inapplicable_categories
Set<String>
Rule does NOT apply when cart contains offers in these categories.
applicable_tags
Set<String>
Rule applies only when cart contains offers with these tags.
inapplicable_tags
Set<String>
Rule does NOT apply when cart contains offers with these tags.
applicable_collections
Set<String>
Rule applies only when cart contains offers from these collections.
inapplicable_collections
Set<String>
Rule does NOT apply when cart contains offers from these collections.
applicable_vendors
Set<String>
Rule applies only when cart contains offers from these vendors.
inapplicable_vendors
Set<String>
Rule does NOT apply when cart contains offers from these vendors.
Cart Value/Quantity Conditions:
min_cart_value
Integer
Rule applies only when cart subtotal ≥ this value (cents).
max_cart_value
Integer
Rule applies only when cart subtotal ≤ this value (cents).
min_item_count
Integer
Rule applies only when cart contains ≥ this many items.
max_item_count
Integer
Rule applies only when cart contains ≤ this many items.
min_cart_weight
Object
Rule applies only when cart weight ≥ this value.
max_cart_weight
Object
Rule applies only when cart weight ≤ this value.
Geographic Conditions:
applicable_countries
Set<String>
Rule applies only for shipping to these countries (ISO Alpha-2).
inapplicable_countries
Set<String>
Rule does NOT apply for shipping to these countries.
applicable_regions
Set<String>
Rule applies only for shipping to these regions/states.
inapplicable_regions
Set<String>
Rule does NOT apply for shipping to these regions/states.
applicable_postal_codes
Set<String>
Rule applies only for shipping to these postal codes.
inapplicable_postal_codes
Set<String>
Rule does NOT apply for shipping to these postal codes.
applicable_postal_code_prefixes
Set<String>
Rule applies only for postal codes starting with these prefixes.
Match Mode:
match_mode
Enum
ANY
How to evaluate multiple IDs: ANY = at least one must match, ALL = all must be present.
Catalog Configuration
The catalog_config object controls inventory behaviors, availability rules, exclusion rules, and catalog sync policies.
Inventory Settings
Violet can configure inventory-related behaviors in catalog_config.inventory.
enforce_zero_as_out_of_stock
Boolean
false
When true, a stock level of zero is treated as out of stock, regardless of external inventory rules.
Safety Stock Rules
Violet can configure safety stock thresholds that override data from the external commerce platform in catalog_config.inventory.safety_stock_rules.
default_out_of_stock_level
Integer
The default stock level at which products are considered out of stock.
tags
Map<String, Rule>
Stock rules keyed by product tag.
categories
Map<String, Rule>
Stock rules keyed by category.
collections
Map<String, Rule>
Stock rules keyed by collection.
vendors
Map<String, Rule>
Stock rules keyed by vendor.
Each stock rule contains:
out_of_stock_level
Integer
The stock level at which matching products are considered out of stock.
Availability Settings
Violet can configure availability-related behaviors in catalog_config.availability.
enforce_draft_as_available
Boolean
false
When true, draft products are considered available.
bypass_inventory_policy
Boolean
false
When true, inventory policies and availability are ignored. Products are considered in stock and available if they are purchasable.
Availability Rules
Violet can override availability based on product attributes in catalog_config.availability.availability_rules.
tags
Map<String, Rule>
Availability rules keyed by product tag.
categories
Map<String, Rule>
Availability rules keyed by category.
collections
Map<String, Rule>
Availability rules keyed by collection.
vendors
Map<String, Rule>
Availability rules keyed by vendor.
Each availability rule contains:
available
Boolean
Whether matching products should be marked as available.
Catalog Exclusion Rules
Violet can configure which products to exclude from the catalog or mark as unpublished in catalog_config.exclusions.exclusion_rules.
tags
Map<String, Rule>
Exclusion rules keyed by product tag.
categories
Map<String, Rule>
Exclusion rules keyed by category.
collections
Map<String, Rule>
Exclusion rules keyed by collection.
vendors
Map<String, Rule>
Exclusion rules keyed by vendor.
Each exclusion rule contains:
excluded
Boolean
When true, matching products are completely excluded from sync. Setting this to true automatically sets unpublished to false.
unpublished
Boolean
When true, matching products are synced but marked as unpublished. Setting this to true automatically sets excluded to false.
Catalog Sync Policy
Violet can configure how the catalog is synchronized in catalog_config.sync_policy.
sync_type
Enum
The synchronization strategy (see below).
sync_frequency_minutes
Integer
How often to poll for catalog updates (when using POLLING or HYBRID).
consolidation_frequency_minutes
Integer
How often to consolidate catalog data.
excluded_webhook_topics
List<String>
Webhook topics to ignore when using EVENTS or HYBRID sync.
Sync Types:
POLLING
Periodically polls the commerce platform for catalog updates.
EVENTS
Relies entirely on webhooks for real-time catalog updates.
HYBRID
Combines webhook-based updates with periodic polling for reliability.
NO_SYNC
Disables automatic catalog synchronization.
Last updated
Was this helpful?