---
title: "Update user settings"
method: PATCH
path: "/api/user/settings"
tags: ["User"]
---

# Update user settings

`PATCH /api/user/settings`

## Request

- Base URL: `https://app.d-sports.org`
- URL: `https://app.d-sports.org/api/user/settings`
- Auth: HTTP bearer

Boolean fields only plus appearanceTheme, hqTextMode (marquee | expand | wrap, default expand; unknown values 400), teamNameDisplayMode (full | name_only, default full), and packOpenMotion (system | full | reduced, default system; unknown values 400). packSoundEnabled (#920) is a boolean like the other toggles (default true on a new row; a non-boolean is ignored). Unknown teamNameDisplayMode values, including null and empty string, return 400 VALIDATION_ERROR. Omitting teamNameDisplayMode or packOpenMotion leaves the stored value unchanged. Unknown packOpenMotion values, including null and empty string, return 400 VALIDATION_ERROR. A new settings row defaults to full. full is city plus name (Montreal Canadiens); name_only is the club name (Canadiens). Persist notifyTeams, notifyMilestones, notifyCommunity, liveScoreUpdates (opt-in Live Activity / ongoing notification consent), analyticsPersonalization (opt-out; default true), and personalizedAdsConsent (boolean, default false) separately. The server stamps personalizedAdsConsentAt and personalizedAdsConsentVersion (currently version 1) when the choice changes, on the first explicit choice, or when re-granting against a new version. Clients cannot set the timestamp or version; a client-supplied value is ignored. The settings row commits before impression cleanup. A privateProfile change writes User.isPrivate in that same transaction, so a cleanup failure cannot leave the settings row private while the user row stays public. Sending personalizedAdsConsent false (including a retry) or analyticsPersonalization false folds that user's backfill AdImpression rows into AdImpressionDailyRollup one page per transaction, then deletes the raw rows. FeedSignal is deleted only when analyticsPersonalization is set to false, and that purge stays in the settings transaction. A cleanup that stops early returns 500 while the saved flag stays; sending the same false again continues the delete. Do not write preferences.privacy. Does not read or write app tour progress; the response is the settings row without appTour. Includes showPullsInFeed (default true) for the live pull feed opt-in (#883). notifyPacks (#914) is a boolean like the other toggles (default true on a new row; a non-boolean is ignored). packAntialias (#923) is auto | off | fxaa | smaa | msaa (default auto); trim and lowercase; unknown values including null and empty string return 400 VALIDATION_ERROR and write nothing. packQuality (#854/W8) is auto | low | mid | high (default auto); the server stores the choice and the device resolves auto; invalid values return 400 VALIDATION_ERROR and write nothing. packSummaryLayout (#1155) is auto | grid | compact | carousel | marquee (default auto); trim and lowercase; the server stores the choice and native renders it; invalid values, including null and empty string, return 400 VALIDATION_ERROR and write nothing. customizerPreviewMode (#931) is full | compact (default full) with the same normalization and 400. showOpenChoiceSheet (#930) must be a boolean when present (non-booleans, including null, return 400 VALIDATION_ERROR). defaultOpenAction (#930) is exactly open_now | open_later (case-checked; OPEN_NOW, blanks, and null return 400 VALIDATION_ERROR). The stored enum is OPEN_NOW | OPEN_LATER and the response speaks open_now | open_later, with packOpenChoice { showSheet, defaultAction }. Omitting one of these fields leaves it unchanged. A new row defaults packAntialias to auto, customizerPreviewMode to full, showOpenChoiceSheet to true, and defaultOpenAction to open_later. Checkout and pack open ignore the preference. timezone, quietStart, and quietEnd (#947) follow the other fields: omitted leaves the stored value unchanged, null clears it, and a valid IANA zone or HH:mm is stored. Invalid timezone returns 400 VALIDATION_ERROR (Invalid timezone. Expected an IANA zone such as America/Toronto.). Invalid quietStart or quietEnd returns 400 (Invalid quiet hours. Expected HH:mm (24h) or null.). Nothing is written on 400. A usable window suppresses goal and kickoff pushes and delivers final scores silently. marketingEmailOptIn (#1032) must be a boolean when present; any other value returns 400 VALIDATION_ERROR. Optional marketingEmailConsentSource is settings | onboarding (default settings); unknown values return 400 VALIDATION_ERROR. On opt-in the server stamps marketingEmailConsentAt and marketingEmailConsentSource; a repeated opt-in keeps the original stamp. On opt-out both are cleared to null. Clients cannot set marketingEmailConsentAt; a client-supplied value is ignored. Each change (off to on, on to off) appends a MarketingEmailConsentEvent row (optIn, source, createdAt) in the same transaction.

## Request body

- object: Partial settings write. A JSON object is required; an omitted body is not valid JSON and the handler returns 500. Every settings field inside the object stays optional. teamNameDisplayMode is the closed enum. packAntialias, packQuality, packSummaryLayout, customizerPreviewMode, and defaultOpenAction are closed strings. showOpenChoiceSheet is a strict boolean. autoRefreshIntervalSec is an integer (0 or 30..3600 seconds).
  - `teamNameDisplayMode` 'full' | 'name_only': How club names are shown on web and engage-native. full is city plus name (Montreal Canadiens). name_only is the club name (Canadiens). Stored on UserSettings.teamNameDisplayMode. Default full.
  - `packAntialias` 'auto' | 'off' | 'fxaa' | 'smaa' | 'msaa': Pack-opening antialiasing mode for the fan (#923). auto lets the device pick a tier. The server stores the choice and does not know device tiers. Stored on UserSettings.packAntialias. Default auto.
  - `packQuality` 'auto' | 'low' | 'mid' | 'high': Pack-opening quality mode (#854, native W8). The server stores the choice; the device resolves auto. Stored on UserSettings.packQuality. New rows default to auto.
  - `packSummaryLayout` 'auto' | 'grid' | 'compact' | 'carousel' | 'marquee': Fan layout for the 3D pack-opening summary (#1155, native#1381). The server stores the choice; native renders it. auto is the device default (today grid). Stored on UserSettings.packSummaryLayout. New rows default to auto.
  - `customizerPreviewMode` 'full' | 'compact': Pinned customizer preview size for the fan (#931). full is the default size. compact shrinks the preview on scroll. Stored on UserSettings.customizerPreviewMode. Default full.
  - `showOpenChoiceSheet` boolean: When true, the fan sees the Open now / Open later sheet after checkout (#930). Default true.
  - `defaultOpenAction` 'open_now' | 'open_later': Wire value for the Open now / Open later default (#930). open_later is the inert default: the server never opens a pack from this preference. Stored as the PackOpenAction enum OPEN_NOW | OPEN_LATER. Default open_later.
  - `timezone` string, nullable: IANA zone such as America/Toronto (#947). Null clears. Omitted leaves the stored value unchanged.
  - `quietStart` string, nullable: Quiet-hours start, HH:mm 24h, inclusive, in timezone (#947). Null clears.
  - `quietEnd` string, nullable: Quiet-hours end, HH:mm 24h, exclusive, in timezone (#947). start greater than end wraps midnight. Null clears.
  - `requirePinForInventoryMove` boolean: Require the wallet PIN before moving inventory between wallets.
  - `walletReminderSnoozedUntil` string, date-time, nullable: Snooze the create-a-wallet reminder until an ISO-8601 date-time with timezone. Null clears; valid timestamps may be at most 30 days ahead, and past timestamps are accepted.
  - `walletReminderDismissedAt` string, date-time, nullable: ISO-8601 date-time with timezone when the fan dismissed the create-a-wallet reminder. Null clears.
  - `autoRefreshIntervalSec` union: Foreground auto-refresh cadence in seconds (engage-native). 0 disables periodic refresh (pull-to-refresh still works); otherwise 30..3600. Server default 60.
    - 0
    - integer
  - `marketingEmailOptIn` boolean: Marketing email consent (#1032). Non-booleans return 400 VALIDATION_ERROR.
  - `marketingEmailConsentSource` 'settings' | 'onboarding': Where the fan opted in; defaults to settings. Used only with marketingEmailOptIn true. Unknown values return 400 VALIDATION_ERROR.

## Response `200`

{ success, data } where data is the UserSettings row, including teamNameDisplayMode (full | name_only). Also packAntialias, packQuality, packSummaryLayout, customizerPreviewMode, showOpenChoiceSheet, defaultOpenAction (open_now | open_later), and packOpenChoice { showSheet, defaultAction }. Also autoRefreshIntervalSec (0 or 30..3600 seconds, default 60), requirePinForInventoryMove (boolean, default false), walletReminderSnoozedUntil, and walletReminderDismissedAt (ISO-8601 date-times with timezone or null).

## Other responses

- `400`: { success: false, error: Invalid teamNameDisplayMode. Expected full | name_only., code: VALIDATION_ERROR }. Also returned for an invalid hqTextMode. Nothing is written. Also returned for an invalid packAntialias (Invalid packAntialias. Expected auto | off | fxaa | smaa | msaa.), customizerPreviewMode (Invalid customizerPreviewMode. Expected full | compact.), showOpenChoiceSheet (Invalid showOpenChoiceSheet. Expected boolean.), or defaultOpenAction (Invalid defaultOpenAction. Expected open_now | open_later.), or packQuality (Invalid packQuality. Expected auto | low | mid | high.). Also returned for an invalid packSummaryLayout (Invalid packSummaryLayout. Expected auto | grid | compact | carousel | marquee.). Also returned for an invalid timezone (Invalid timezone. Expected an IANA zone such as America/Toronto.) or quiet hours (Invalid quiet hours. Expected HH:mm (24h) or null.). Nothing is written. Also returned for an invalid autoRefreshIntervalSec (Invalid autoRefreshIntervalSec. Expected 0 or an integer 30..3600 (seconds).). Nothing is written.
- `500`: { success: false, error: Failed to update settings, code: INTERNAL_ERROR }. Impression cleanup that stops early uses this response. The settings row, including privateProfile mirrored onto User.isPrivate, is already saved. Sending the same false again continues the delete.

## Changes

- **2026-11-20** `7cb91c806db1`: 1 info
  - added the new optional request property `packSummaryLayout`
- **2026-11-18** `6de639c52609`: 1 breaking, 2 info
  - added required request body
  - added the non-success response with the status `400`
  - added the non-success response with the status `500`
- **2026-08-17** `6a5e2c1b8022`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/changes/api/user/settings/patch.md)

---

[API](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api.md) - [All operations](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/llms.txt) - [OpenAPI document](https://skmtc.dev/d-sports-ecosystem/apis/d-sports-api/revisions/63735cf90a04?raw)
