Merchant Configuration Resources
Overview
Individual merchant configuration sections — shipping settings, shipping methods, inventory location filters, catalog rules, and catalog settings — are available as first-class REST resources under /merchants/{merchant_id}/*. These endpoints let you read and update specific configuration sections without fetching or overwriting the full Merchant Configuration object.
Each resource follows standard REST semantics: GET to read, PATCH for partial updates, PUT for full replacement, POST for creation, and DELETE for removal.
These resource endpoints manage the same underlying configuration as the monolithic Get Merchant Configuration endpoint. Changes made through either interface are reflected in both.
Shipping Settings
Shipping settings control fallback shipping behavior toggles for a merchant. These are separate from the fallback shipping methods themselves, which have their own resource (see below).
exclude_external_methods
Boolean
When true, excludes all shipping methods returned by the merchant's commerce platform.
exclude_external_free_shipping
Boolean
When true, excludes free shipping methods from the commerce platform.
use_fallback_methods_on_empty
Boolean
When true, returns fallback shipping methods when the commerce platform provides none.
Read settings:
GET /merchants/{merchant_id}/shipping-settings{
"exclude_external_methods": true,
"exclude_external_free_shipping": false,
"use_fallback_methods_on_empty": true
}Update settings:
Only the fields present in the request body are modified; omitted fields are left untouched.
Shipping Methods
Shipping methods are the fallback methods Violet returns when a merchant's commerce platform provides no shipping options (or when exclude_external_methods is enabled). Each method is identified by a unique handle per merchant.
label
String
Yes
Display name of the shipping method.
description
String
No
Description shown to the customer.
price
Integer
Yes
Price in cents.
currency
String
Yes
ISO 4217 currency code (e.g., USD).
handle
String
No
Unique identifier. Generated from the label if omitted on creation.
calculation_type
Enum
No
PER_ORDER (default) or PER_ITEM.
conditions
Object
No
Rules that restrict when this method is available.
Conditions
Conditions let you scope a shipping method to specific countries, offers, order amounts, or weights.
applicable_countries
String[]
ISO Alpha-2 country codes where this method can be used.
inapplicable_countries
String[]
ISO Alpha-2 country codes where this method cannot be used.
applicable_offer_ids
Long[]
Offer IDs this method applies to.
inapplicable_offer_ids
Long[]
Offer IDs this method does not apply to.
min_order_amount
Integer
Minimum order amount (in cents) required.
max_order_amount
Integer
Maximum order amount (in cents) allowed.
min_weight
Object
Minimum order weight (value and unit: KG, LB, OZ).
max_weight
Object
Maximum order weight.
Endpoints
List all methods:
Create a method:
If handle is omitted, one is generated from the label (e.g., "Express" becomes "express"). If a handle is supplied and already exists for this merchant, the request returns 409 Conflict.
Get a single method:
Create or replace a method by handle:
Delete a method:
Renaming a method's handle requires deleting the old method and creating a new one. A handle in the request body, if present, must match the path handle.
Catalog Settings
Catalog settings control offer visibility and publishing behavior during catalog sync.
truify_offer_visibility
Boolean
Forces offer visibility to true during catalog sync, overriding the source platform's visibility settings.
auto_publish_offers
Boolean
Automatically publishes offers after creation or update. Set to false to require manual publishing.
Read settings:
Update settings:
Only the fields present in the request body are modified; omitted fields are left untouched.
truify_offer_visibility is restricted to channel and admin tokens. Merchant tokens attempting to set this field receive a 403 Forbidden response.
Catalog Rules
Catalog rules control which products are included, excluded, or unpublished during catalog sync. Rules are organized into two types — availability and exclusions — and are keyed by dimension (tags or vendors) and a dimension value (the specific tag or vendor name).
Read all rules:
Availability Rules
Availability rules override whether products matching a given tag or vendor are marked as available and/or published.
available
Boolean
Whether matching products are marked as available.
published
Boolean
Whether matching products are marked as published.
Create or replace an availability rule:
For example, to mark all products tagged "clearance" as available and published:
Delete an availability rule:
Exclusion Rules
Exclusion rules control whether products matching a given tag or vendor are excluded from sync entirely, or synced but marked as unpublished.
excluded
Boolean
When true, matching products are completely excluded from sync.
unpublished
Boolean
When true, matching products are synced but marked as unpublished.
excluded and unpublished are mutually exclusive. Setting one to true automatically clears the other.
Create or replace an exclusion rule:
For example, to exclude all products from the vendor "Pucci":
Delete an exclusion rule:
The {key} path parameter should be URL-encoded if the tag or vendor name contains special characters.
Inventory Location Filters
Inventory location filters restrict which warehouse or fulfillment locations are used for inventory calculations. When filtering is enabled, only stock from the specified locations is considered when determining product availability.
location_ids
String[]
The set of enabled location IDs (numeric strings).
filtering_enabled
Boolean
Read-only. true when location_ids is non-empty.
Inventory location filters are only supported for Shopify merchants. Requests for merchants on other platforms return 400 Bad Request.
Read filters:
Replace filters:
This replaces the full set of enabled location IDs. The filter_inventory_by_locations platform feature flag is derived automatically — it is enabled when the list is non-empty and disabled when the list is empty. The filtering_enabled field in the response is read-only and ignored on write.
To disable location filtering, pass an empty list:
Relationship to Get Merchant Configuration
The Get Merchant Configuration endpoint returns the complete configuration object for a merchant, including all of the sections covered above. The resource endpoints documented on this page provide targeted access to individual sections.
Use the full configuration endpoint when you need a complete snapshot. Use the individual resource endpoints when you need to read or update a specific section — they are lighter, avoid accidental overwrites of unrelated settings, and support partial updates via JSON Merge Patch where applicable.
Last updated
Was this helpful?