> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Murph user preferences

> Read and set the authenticated user's Murph language and display preferences

Murph user preferences are scoped to the authenticated user. They control the
default language for new Murph conversations and expose display preferences the
UI can use when formatting Murph surfaces.

<Info>
  These endpoints are available only when Murph is enabled for the caller's
  account.
</Info>

## Get preferences

`GET /api/v2/murph/user-preferences`

Returns the caller's current Murph preferences. If the request is authenticated
with a service token instead of a user session, the endpoint returns the same
shape with all preference fields set to `null`.

```bash curl theme={null}
curl https://api.interchange.io/api/v2/murph/user-preferences \
  -H "Authorization: Bearer $SCOPE3_API_KEY"
```

### Response

```json theme={null}
{
  "preferredLanguage": "de",
  "locale": "de-DE",
  "timezone": "Europe/Berlin",
  "displayCurrency": "EUR"
}
```

| Field               | Type           | Notes                                                                                             |
| ------------------- | -------------- | ------------------------------------------------------------------------------------------------- |
| `preferredLanguage` | enum \| null   | User-level default language for new Murph conversations. `null` means Murph auto-detects language |
| `locale`            | string \| null | BCP-47 display locale, such as `en-US`, `de-DE`, or `ja-JP`                                       |
| `timezone`          | string \| null | IANA timezone, such as `America/New_York` or `Europe/Berlin`                                      |
| `displayCurrency`   | string \| null | ISO 4217 currency code used for display formatting, such as `USD`, `EUR`, or `JPY`                |

## Set default language

`PUT /api/v2/murph/user-preferences/language`

Sets the caller's user-level default Murph language. New conversations inherit
this value at creation time. Existing conversations keep their own language
override unless you update them separately.

Send `preferredLanguage: null` to clear the user default and return new
conversations to auto-detect.

```bash curl theme={null}
curl -X PUT https://api.interchange.io/api/v2/murph/user-preferences/language \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "preferredLanguage": "fr"
  }'
```

### Request body

| Field               | Type         | Required | Notes                                                         |
| ------------------- | ------------ | -------- | ------------------------------------------------------------- |
| `preferredLanguage` | enum \| null | Yes      | Supported Murph language code, or `null` to clear the default |

### Response

```json theme={null}
{
  "preferredLanguage": "fr",
  "locale": "fr-FR",
  "timezone": null,
  "displayCurrency": null
}
```

The response returns the full preference object now in effect.

## Supported languages

| Code | Language            |
| ---- | ------------------- |
| `en` | English             |
| `de` | German              |
| `fr` | French              |
| `es` | Spanish             |
| `pt` | Portuguese          |
| `it` | Italian             |
| `nl` | Dutch               |
| `sv` | Swedish             |
| `pl` | Polish              |
| `ja` | Japanese            |
| `ko` | Korean              |
| `zh` | Chinese, Simplified |
| `ar` | Arabic              |
| `hi` | Hindi               |
| `tr` | Turkish             |

## Errors

* `400 VALIDATION_ERROR` — invalid request body, unsupported language code, invalid locale, invalid timezone, or invalid currency.
* `400 BAD_REQUEST` — setting a user-level default was attempted from a non-user auth context.
* `401 UNAUTHORIZED` — missing or invalid bearer token.
* `403 FORBIDDEN` — Murph is not enabled for the caller's account.

See [Errors](/v2/reference/errors) for the full error contract.

## Related

<CardGroup cols={2}>
  <Card title="Ask Murph" href="/v2/setup/ask-murph" icon="sparkles">
    How storefront operators use Murph in the platform.
  </Card>

  <Card title="Murph confirmations" href="/v2/setup/murph-confirmations" icon="shield-check">
    Confirmation flows for Murph actions that need approval.
  </Card>
</CardGroup>