> For the complete documentation index, see [llms.txt](https://docs.violet.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.violet.io/prism/merchants/merchant-configuration-resources.md). # 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](https://github.com/violetio/docs/blob/main/api-reference/merchant-service/merchants-configuration/get-merchant-configuration/README.md) 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. {% hint style="info" %} These resource endpoints manage the same underlying configuration as the monolithic [Get Merchant Configuration](https://github.com/violetio/docs/blob/main/api-reference/merchant-service/merchants-configuration/get-merchant-configuration/README.md) endpoint. Changes made through either interface are reflected in both. {% endhint %} This page is the field and endpoint reference. For how each capability behaves, see the [Configuration](/prism/merchants/configuration.md) guides. ## 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). | Field | Type | Description | | -------------------------------- | ------- | ---------------------------------------------------------------------------------------- | | `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 ``` ```json { "exclude_external_methods": true, "exclude_external_free_shipping": false, "use_fallback_methods_on_empty": true } ``` **Update settings:** ``` PATCH /merchants/{merchant_id}/shipping-settings Content-Type: application/merge-patch+json ``` ```json { "exclude_external_methods": true } ``` Only the fields present in the request body are modified; omitted fields are left untouched. ## Shipping Methods Shipping methods are fallback methods you define in Violet. By default they are offered alongside the rates the merchant's commerce platform returns; see [When fallback methods are used](/prism/merchants/configuration/when-fallback-methods-apply.md) for the settings that change that. Each method is identified by a unique `handle` per merchant. | Field | Type | Required | Description | | ------------------ | ------- | -------- | ------------------------------------------------------------------- | | `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. | Field | Type | Description | | ------------------------ | --------- | ------------------------------------------------------------ | | `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:** ``` GET /merchants/{merchant_id}/shipping-methods ``` ```json [ { "label": "Standard", "description": "5-7 business days", "price": 500, "currency": "USD", "handle": "standard", "calculation_type": "PER_ORDER", "conditions": { "applicable_countries": ["US", "CA"], "min_order_amount": 1000 } } ] ``` **Create a method:** ``` POST /merchants/{merchant_id}/shipping-methods ``` ```json { "label": "Express", "price": 1500, "currency": "USD", "calculation_type": "PER_ORDER" } ``` 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:** ``` GET /merchants/{merchant_id}/shipping-methods/{handle} ``` **Create or replace a method by handle:** ``` PUT /merchants/{merchant_id}/shipping-methods/{handle} ``` **Delete a method:** ``` DELETE /merchants/{merchant_id}/shipping-methods/{handle} ``` {% hint style="info" %} 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. {% endhint %} ## Catalog Settings Catalog settings control offer visibility and publishing behavior during catalog sync. | Field | Type | Description | | ------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ | | `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:** ``` GET /merchants/{merchant_id}/catalog-settings ``` ```json { "truify_offer_visibility": true, "auto_publish_offers": false } ``` **Update settings:** ``` PATCH /merchants/{merchant_id}/catalog-settings Content-Type: application/merge-patch+json ``` ```json { "auto_publish_offers": false } ``` Only the fields present in the request body are modified; omitted fields are left untouched. {% hint style="warning" %} `truify_offer_visibility` is restricted to channel and admin tokens. Merchant tokens attempting to set this field receive a `403 Forbidden` response. {% endhint %} ## 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). Catalog rules currently apply to Shopify merchants only, and availability rules match on tags only. For when each rule type takes effect, see [How catalog rules work](/prism/merchants/configuration/how-catalog-rules-work.md). {% hint style="warning" %} Catalog rule `PUT` requests replace the entire rule object. Omitted fields are cleared, not preserved from the existing rule. Always send the complete rule with every field set explicitly. {% endhint %} **Read all rules:** ``` GET /merchants/{merchant_id}/catalog-rules ``` ```json { "availability": { "tags": { "sale": { "available": true } }, "vendors": {} }, "exclusions": { "tags": {}, "vendors": { "Pucci": { "excluded": true, "unpublished": false } } } } ``` ### Availability Rules Availability rules override whether products matching a given tag are marked as available. Vendor-keyed availability rules are accepted but currently have no effect. | Field | Type | Description | | ----------- | ------- | ------------------------------------------------------------------------------------------------------------------------ | | `available` | Boolean | `true` forces matching products to be available; `false` makes them unavailable. Delete the rule to remove the override. | | `published` | Boolean | Deprecated. Accepted and stored, but nothing reads it and it has no effect. Omit it. | {% hint style="warning" %} Because the `PUT` replaces the whole rule, a request that omits `available` stores `available: false`, making every matching product unpurchasable. Always include `available` explicitly. {% endhint %} **Create or replace an availability rule:** ``` PUT /merchants/{merchant_id}/catalog-rules/availability/{dimension}/{key} ``` For example, to mark all products tagged `"clearance"` as available: ``` PUT /merchants/{merchant_id}/catalog-rules/availability/tags/clearance ``` ```json { "available": true } ``` **Delete an availability rule:** ``` DELETE /merchants/{merchant_id}/catalog-rules/availability/{dimension}/{key} ``` ### Exclusion Rules Exclusion rules control whether products matching a given tag or vendor are excluded from sync entirely, or synced but marked as unpublished. | Field | Type | Description | | ------------- | ------- | -------------------------------------------------------------------- | | `excluded` | Boolean | When `true`, matching products are completely excluded from sync. | | `unpublished` | Boolean | When `true`, matching products are synced but marked as unpublished. | {% hint style="warning" %} `excluded` and `unpublished` are mutually exclusive. Setting one to `true` automatically clears the other. {% endhint %} **Create or replace an exclusion rule:** ``` PUT /merchants/{merchant_id}/catalog-rules/exclusions/{dimension}/{key} ``` For example, to exclude all products from the vendor `"Pucci"`: ``` PUT /merchants/{merchant_id}/catalog-rules/exclusions/vendors/Pucci ``` ```json { "excluded": true, "unpublished": false } ``` **Delete an exclusion rule:** ``` DELETE /merchants/{merchant_id}/catalog-rules/exclusions/{dimension}/{key} ``` {% hint style="info" %} The `{key}` path parameter should be URL-encoded if the tag or vendor name contains special characters. {% endhint %} ## 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. | Field | Type | Description | | ------------------- | --------- | --------------------------------------------------- | | `location_ids` | String\[] | The set of enabled location IDs (numeric strings). | | `filtering_enabled` | Boolean | Read-only. `true` when `location_ids` is non-empty. | {% hint style="warning" %} Inventory location filters are only supported for Shopify merchants. Requests for merchants on other platforms return `400 Bad Request`. {% endhint %} **Read filters:** ``` GET /merchants/{merchant_id}/inventory-location-filters ``` ```json { "location_ids": ["12345678", "87654321"], "filtering_enabled": true } ``` **Replace filters:** ``` PUT /merchants/{merchant_id}/inventory-location-filters ``` ```json { "location_ids": ["12345678", "87654321"] } ``` 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: ```json { "location_ids": [] } ``` ## Relationship to Get Merchant Configuration The [Get Merchant Configuration](https://github.com/violetio/docs/blob/main/api-reference/merchant-service/merchants-configuration/get-merchant-configuration/README.md) 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.violet.io/prism/merchants/merchant-configuration-resources.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. 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.