> 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 %}

## 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 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.

| 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).

**Read all rules:**

```
GET /merchants/{merchant_id}/catalog-rules
```

```json
{
  "availability": {
    "tags": {
      "sale": {
        "available": true,
        "published": true
      }
    },
    "vendors": {}
  },
  "exclusions": {
    "tags": {},
    "vendors": {
      "Pucci": {
        "excluded": true,
        "unpublished": false
      }
    }
  }
}
```

### Availability Rules

Availability rules override whether products matching a given tag or vendor are marked as available and/or published.

| Field       | Type    | Description                                        |
| ----------- | ------- | -------------------------------------------------- |
| `available` | Boolean | Whether matching products are marked as available. |
| `published` | Boolean | Whether matching products are marked as published. |

**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 and published:

```
PUT /merchants/{merchant_id}/catalog-rules/availability/tags/clearance
```

```json
{
  "available": true,
  "published": 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.violet.io/prism/merchants/merchant-configuration-resources.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.