---
title: "Update merchant settings"
method: PUT
path: "/v1/merchants/{id}/settings"
tags: ["Merchant Setup"]
---

# Update merchant settings

`PUT /v1/merchants/{id}/settings`

## Request

- Base URL: `https://api.insumermodel.com`
- URL: `https://api.insumermodel.com/v1/merchants/{id}/settings`
- Auth: API key in header `X-API-Key`

Update discount stacking mode, cap, the store's terms for wallets sent without proof of control (a lower discount or none, and a daily limit), USDC payment settings, and whether the store's recognition is paused. All fields optional. Must be called by the API key that created the merchant.

## Path parameters

- `id` string, required

## Request body

- object
  - `discountMode` 'highest' | 'stack' | 'capped': 'highest' uses best single discount, 'stack' sums all, 'capped' sums all then caps at discountCap
  - `discountCap` integer: Maximum total discount percentage: a whole number from 1 to 100. A value with a fraction (25.5) is a 400; "25.0" is accepted as 25.
  - `maxDiscountsPerWalletPerDay` integer, nullable: Optional. The store's own limit on discount codes per UTC day for a wallet sent without a walletProof, a whole number from 1 to 100; null removes the limit. Unset means no limit. The limit does not apply to a proven wallet. When an unproven wallet has reached it, /v1/verify, /v1/acp/discount and /v1/ucp/discount return 429 with no credit used and no code created. Only orders that earn a discount count. Only the day's count is held, and it is deleted after the day.
  - `maxUnprovenDiscount` integer, nullable: Optional. What a wallet sent without a walletProof can get: at most this percent, a whole number from 0 to 100 (0 = no discount); null = the same as a proven wallet. Unset means the same. The verify response then carries discountIfProven, so the caller knows what proof would get. Published to agents in walletTerms on GET /v1/merchants and GET /v1/merchants/{id}.
  - `usdcPayment` object, nullable: USDC payment config, or null to disable
    - `enabled` boolean
    - `evmAddress` string: EVM wallet for USDC (0x + 40 hex)
    - `solanaAddress` string: Solana wallet for USDC (base58)
    - `preferredChainId` union: Chains supported for crypto payments. EVM chains and Solana accept USDC and USDT. Bitcoin accepts BTC (converted to USD at market rate, requires 1 confirmation). Tron accepts USDT-TRC20.
      - 1 | 8453 | 137 | 42161 | 10 | 56 | 43114
      - 'solana' | 'bitcoin' | 'tron'
  - `paused` boolean: Optional. true pauses the store's recognition; false resumes it. While a store is paused, discount codes for it are refused (409 on /v1/verify, /v1/acp/discount, /v1/ucp/discount and /v1/discount/check; no credit used, no code created), /v1/pass/verify answers recognized false with paused true, it is left out of GET /v1/merchants, and its NFC stickers give no code. Resuming restores everything, including the same stickers. Idempotent.

## Response `200`

Settings updated

- object
  - `ok` true
  - `data` object
    - `discountMode` string
    - `discountCap` integer
    - `maxDiscountsPerWalletPerDay` integer, nullable
    - `maxUnprovenDiscount` integer, nullable
    - `usdcPayment` object, nullable
      - `enabled` boolean
    - `paused` boolean: Whether the store's recognition is paused.
    - `pausedAt` string, date-time, nullable: When the store was paused, or null.
  - `meta` Meta
    - `version` string
    - `timestamp` string, date-time

## Other responses

- `400`: Validation error or no fields provided
- `401`: Invalid or missing API key
- `403`: API key does not own this merchant
- `404`: Merchant not found
- `429`: Rate limit exceeded. API-key requests count against the key's daily limit; every authenticated response carries X-RateLimit-Limit and X-RateLimit-Remaining headers, and a 429 additionally carries Retry-After (seconds until the window resets).
- `500`: Unexpected server error. Safe to retry; no credits are charged on a 500. Router endpoints return the standard error envelope; standalone endpoints (the ones whose 200 is a flat object) return a flat {"error": "..."} object.

---

[API](https://skmtc.dev/insumermodel/apis/insumerapi.md) · [All operations](https://skmtc.dev/insumermodel/apis/insumerapi/llms.txt) · [OpenAPI document](https://skmtc.dev/insumermodel/apis/insumerapi/revisions/91f56fe9e3d8?raw)