Printago API
PATCH /v1/settings/store

Update store settings

`qrWorkflowSettings` needs the QR Workflows add-on (403 without it) and is checked against the action catalog from GET /v1/qr-tags/actions: an unknown action, a pair default that isn't one of that pair's actions or is destructive, or an order listing another scan's actions is a 400.

Requires: settings.edit

Request Body

Settings to update

UpdateStoreSettingsRequest
automaticQueueMatchingoptional
boolean
currencyoptionalnullable
string
currencySymboloptionalnullable
string
defaultFallbackFilamentSystemProfileIdoptionalnullable
number
defaultFallbackFilamentUserProfileIdoptionalnullable
string
defaultPrinterSystemProfileIdoptionalnullable
number
defaultPrinterUserProfileIdoptionalnullable
string
defaultProcessSystemProfileIdoptionalnullable
number
defaultProcessUserProfileIdoptionalnullable
string
experimentalFeaturesoptional
object
financial-trackingoptional
boolean
generalSettingsoptional
object
addReadSpoolsoptional
"off" | "bulk_first" | "new_stock"
What to do with a roll a printer reads that inventory has no spool for. Absent is `off`.
offbulk_firstnew_stock
aiDataProgramoptional
object
Where this store stands with the AI training-data program. Absent means never asked. Flipped to `invited` once the store has labelled enough AI failure alerts; the invite itself, consent copy and retention terms are separate from this flag.
decidedAtoptional
string
decidedByUserIdoptional
string
statusrequired
"unasked" | "invited" | "joined" | "declined"
unaskedinvitedjoineddeclined
amsSlotSelectionStrategyoptional
"lowest-index" | "highest-index" | "most-empty" | "most-full"
Controls which slot the queue matcher assigns when a job's material is loaded in multiple slots on the same printer. Absent is treated as `lowest-index` (left-to-right), so existing stores get deterministic left-to-right assignment without any configuration.
lowest-indexhighest-indexmost-emptymost-full
autoConfirmMacroRunoptional
boolean
When true, the Run Macro dialog's "printer is clear" safety checkbox starts checked and re-confirms itself as the macro/printer selection changes, so operators who run macros constantly don't have to tick it every time. The server-side digest check (stale-preview 409) still applies. Absent/false = the checkbox must be ticked manually.
autoMatchMaterialsNewPartoptional
boolean
enableCompletionSnapshotoptional
boolean
When true, Fuse captures a single fresh JPEG near the end of each print (last layer / 95% progress / FINISH transition, in that order) and uploads it as the print-job's `cameraThumbnailUri`. Independent from `enableTimelapse` — a store can have completion snapshots without paying the timelapse encode cost, or vice versa. New stores default to true via createDefaultSettings.
enableTelemetryCaptureoptional
boolean
Per-attempt print telemetry capture: the gateway archives a downsampled series (temperatures/progress/layer timings) at print end, and Fuse uploads its full-fidelity flight recording. Absent is treated as ON — unlike the camera toggles, telemetry defaults on and stores opt out. Artifacts land under the permanent `telemetry/` storage prefix and are linked from print history.
enableTimelapseoptional
boolean
When true, the cloud renders a timelapse video for each completed print by stitching together the snapshot history captured by Fuse during the print. New stores default to true via createDefaultSettings so the feature is on out of the box; stores that don't want the encode cost can toggle it off in store settings.
fabmaticIgnoredErrorCodesoptional
object[]
Error codes the store wants ignored when deciding whether a printer error should turn off FabMatic (continuous printing). Codes are matched format-insensitively (case, dashes, underscores and leading zeros are ignored) against the printer's health `errors` and the print `printError` code. (Health `warnings` never turn FabMatic off, so they are not part of this decision.) If every error present on a finished/errored print matches an entry here, FabMatic stays enabled and the queue keeps advancing. Absent/empty means no codes are ignored (current behaviour). Codes vary in length and format across printer brands: print errors are often 8 hex chars ("0500-400E"/"0500400E"/decimal "83902478") while health codes can be 16 hex chars ("0582040000010045"). Separators are optional and ignored when matching.
coderequired
string
noteoptional
string
plateMergingoptional
object
Plate merging (combining compatible pending jobs onto one build plate). Absent means DEFAULT_PLATE_MERGING_SETTINGS (automatic merging off; manual merging is always available, gated only by queue.manage).
automaticMergingrequired
boolean
When true, the matcher merges compatible queued jobs onto the assigned printer's plate at match time (scope-limited by mergeScope).
holdReleaseSaturationPercentoptional
number
Early release for the hold: once the batch that would merge fills at least this percent of the usable plate, waiting adds latency but little value, so the job assigns immediately. Fullness is the merge preview's coverage number — parts, the spacing around them, and gaps too small for anything else, over the plate inside the margin minus keep-out zones — so 100 means "nothing else fits". 1-100. Optional: absent means the default (80: about one mid-size part's worth of room left).
maxPartsPerPlaterequired
number
Upper bound on parts per merged plate (slicer/UI sanity bound).
mergeHoldMinutesoptional
number
When > 0 (and automaticMerging is on), a merge-eligible pending job is held back from being assigned to a printer for up to this many minutes after it was queued, so jobs arriving shortly after it can batch onto one plate instead of fanning out across idle printers. 0 = off (jobs assign immediately). The window is anchored to each job's own creation time, so a steady trickle of arrivals can never extend a job's hold. Manual "Match queue now" runs and direct printer assignments bypass holds. Optional: absent on settings saved before the field existed.
mergeScoperequired
"same-order" | "any"
Which jobs automatic merging may combine: 'same-order' only merges jobs from the same order (null orderId matches null — non-commerce jobs merge with each other); 'any' merges anything compatible. Manual merging is never restricted by this.
same-orderany
partSpacingMmrequired
number
Minimum clearance between placed parts, mm.
plateMarginMmrequired
number
Keep-out margin from the plate edge, mm.
processPoliciesoptional
Record<string, string>
Construct a type with a set of properties K of type T
slicerCompatibilityoptional
"allow-upgrades" | "account-default" | "exact"
How slicer engine/version differences gate merging and drive which slicer the merged plate is sliced with. Absent means DEFAULT_SLICER_COMPATIBILITY ("allow-upgrades"). See {@link SlicerCompatibilityMode }.
allow-upgradesaccount-defaultexact
reconcileReadSpoolsoptional
boolean
Bring a tag-read roll down to what its printer reports when the printer reads it well under what inventory holds: filament used outside Printago (a print sent from the slicer, or the roll run on another machine). Absent is on.
showGettingStartedChecklistoptional
boolean
Getting Started checklist visibility. Absent means "default by store age": stores created on or after GETTING_STARTED_RELEASE_DATE default on, older stores off (see isGettingStartedEnabled).
thumbnailStyleoptional
"orthographic" | "perspective"
Projection and shading the thumbnail renderer uses. Absent means DEFAULT_THUMBNAIL_STYLE ("orthographic"). Applies to renders from the moment it is saved — thumbnails already rendered keep their look until something re-renders them.
orthographicperspective
processLowPriorityJobsoptional
boolean
qrWorkflowSettingsoptional
object
Action ids come from GET /v1/qr-tags/actions.
actionOrderoptional
Record<string, string[]>
Construct a type with a set of properties K of type T
defaultSpoolGramsoptional
integer
The weight Register spool opens with, in grams.
min: 1max: 50000
disabledActionsoptional
string[]
Actions the app never offers and execute refuses with 403.
max items: 200
moveSpoolBetweenSlotsoptional
boolean
When false, loading a spool that sits in another slot is refused with 409 instead of moving it.
pairDefaultsoptional
Record<string, string>
Construct a type with a set of properties K of type T
slotStrategyoptional
"prompt" | "external" | "first_empty"
The slot the app pre-selects for a spool or filament scanned with a printer: `prompt` picks none, `external` the external spool holder, `first_empty` the first slot with nothing assigned and no spool (for a spool, first a slot the printer sees a spool in with nothing assigned). With no such slot the app asks.
promptexternalfirst_empty
repairSlicerProfileValuesoptional
boolean
sliceroptionalnullable
string

Example Request

application/json 
{
  "slicer": "string",
  "processLowPriorityJobs": true,
  "automaticQueueMatching": true,
  "repairSlicerProfileValues": true,
  "currency": "string",
  "currencySymbol": "string",
  "defaultPrinterUserProfileId": "string",
  "defaultPrinterSystemProfileId": 1,
  "defaultProcessUserProfileId": "string",
  "defaultProcessSystemProfileId": 1,
  "defaultFallbackFilamentUserProfileId": "string",
  "defaultFallbackFilamentSystemProfileId": 1,
  "experimentalFeatures": {
    "financial-tracking": true
  },
  "generalSettings": {
    "autoMatchMaterialsNewPart": true,
    "enableTimelapse": true,
    "enableCompletionSnapshot": true,
    "enableTelemetryCapture": true,
    "amsSlotSelectionStrategy": "lowest-index",
    "addReadSpools": "off",
    "reconcileReadSpools": true,
    "fabmaticIgnoredErrorCodes": [
      {
        "code": "string",
        "note": "string"
      }
    ],
    "plateMerging": {
      "automaticMerging": true,
      "mergeScope": "same-order",
      "partSpacingMm": 1,
      "plateMarginMm": 1,
      "maxPartsPerPlate": 1,
      "mergeHoldMinutes": 1,
      "holdReleaseSaturationPercent": 1,
      "processPolicies": {},
      "slicerCompatibility": "allow-upgrades"
    },
    "showGettingStartedChecklist": true,
    "autoConfirmMacroRun": true,
    "thumbnailStyle": "orthographic",
    "aiDataProgram": {
      "status": "unasked",
      "decidedAt": "string",
      "decidedByUserId": "string"
    }
  },
  "qrWorkflowSettings": {
    "disabledActions": [
      "string"
    ],
    "pairDefaults": {},
    "actionOrder": {},
    "slotStrategy": "prompt",
    "moveSpoolBetweenSlots": true,
    "defaultSpoolGrams": 1
  }
}

Response Schema

GetStoreSettingsResponse
automaticQueueMatchingrequired
boolean
When false, every background QueueRun event short-circuits inside `matchPrintersAndJobs` and the auto-matcher does not assign jobs. The queue page surfaces a "Match queue now" button that bypasses this gate by passing `manual: true` to the matcher. Defaults to true so existing stores keep their current behaviour.
createdAtrequired
string
format: date-time
currencyrequirednullable
string
currencySymbolrequirednullable
string
defaultFallbackFilamentSystemProfileIdrequirednullable
number
defaultFallbackFilamentUserProfileIdrequirednullable
string
defaultPrinterSystemProfileIdrequirednullable
number
defaultPrinterUserProfileIdrequirednullable
string
defaultProcessSystemProfileIdrequirednullable
number
defaultProcessUserProfileIdrequirednullable
string
experimentalFeaturesrequirednullable
object
financial-trackingoptional
boolean
generalSettingsrequirednullable
object
addReadSpoolsoptional
"off" | "bulk_first" | "new_stock"
What to do with a roll a printer reads that inventory has no spool for. Absent is `off`.
offbulk_firstnew_stock
aiDataProgramoptional
object
Where this store stands with the AI training-data program. Absent means never asked. Flipped to `invited` once the store has labelled enough AI failure alerts; the invite itself, consent copy and retention terms are separate from this flag.
decidedAtoptional
string
decidedByUserIdoptional
string
statusrequired
"unasked" | "invited" | "joined" | "declined"
unaskedinvitedjoineddeclined
amsSlotSelectionStrategyoptional
"lowest-index" | "highest-index" | "most-empty" | "most-full"
Controls which slot the queue matcher assigns when a job's material is loaded in multiple slots on the same printer. Absent is treated as `lowest-index` (left-to-right), so existing stores get deterministic left-to-right assignment without any configuration.
lowest-indexhighest-indexmost-emptymost-full
autoConfirmMacroRunoptional
boolean
When true, the Run Macro dialog's "printer is clear" safety checkbox starts checked and re-confirms itself as the macro/printer selection changes, so operators who run macros constantly don't have to tick it every time. The server-side digest check (stale-preview 409) still applies. Absent/false = the checkbox must be ticked manually.
autoMatchMaterialsNewPartoptional
boolean
enableCompletionSnapshotoptional
boolean
When true, Fuse captures a single fresh JPEG near the end of each print (last layer / 95% progress / FINISH transition, in that order) and uploads it as the print-job's `cameraThumbnailUri`. Independent from `enableTimelapse` — a store can have completion snapshots without paying the timelapse encode cost, or vice versa. New stores default to true via createDefaultSettings.
enableTelemetryCaptureoptional
boolean
Per-attempt print telemetry capture: the gateway archives a downsampled series (temperatures/progress/layer timings) at print end, and Fuse uploads its full-fidelity flight recording. Absent is treated as ON — unlike the camera toggles, telemetry defaults on and stores opt out. Artifacts land under the permanent `telemetry/` storage prefix and are linked from print history.
enableTimelapseoptional
boolean
When true, the cloud renders a timelapse video for each completed print by stitching together the snapshot history captured by Fuse during the print. New stores default to true via createDefaultSettings so the feature is on out of the box; stores that don't want the encode cost can toggle it off in store settings.
fabmaticIgnoredErrorCodesoptional
object[]
Error codes the store wants ignored when deciding whether a printer error should turn off FabMatic (continuous printing). Codes are matched format-insensitively (case, dashes, underscores and leading zeros are ignored) against the printer's health `errors` and the print `printError` code. (Health `warnings` never turn FabMatic off, so they are not part of this decision.) If every error present on a finished/errored print matches an entry here, FabMatic stays enabled and the queue keeps advancing. Absent/empty means no codes are ignored (current behaviour). Codes vary in length and format across printer brands: print errors are often 8 hex chars ("0500-400E"/"0500400E"/decimal "83902478") while health codes can be 16 hex chars ("0582040000010045"). Separators are optional and ignored when matching.
coderequired
string
noteoptional
string
plateMergingoptional
object
Plate merging (combining compatible pending jobs onto one build plate). Absent means DEFAULT_PLATE_MERGING_SETTINGS (automatic merging off; manual merging is always available, gated only by queue.manage).
automaticMergingrequired
boolean
When true, the matcher merges compatible queued jobs onto the assigned printer's plate at match time (scope-limited by mergeScope).
holdReleaseSaturationPercentoptional
number
Early release for the hold: once the batch that would merge fills at least this percent of the usable plate, waiting adds latency but little value, so the job assigns immediately. Fullness is the merge preview's coverage number — parts, the spacing around them, and gaps too small for anything else, over the plate inside the margin minus keep-out zones — so 100 means "nothing else fits". 1-100. Optional: absent means the default (80: about one mid-size part's worth of room left).
maxPartsPerPlaterequired
number
Upper bound on parts per merged plate (slicer/UI sanity bound).
mergeHoldMinutesoptional
number
When > 0 (and automaticMerging is on), a merge-eligible pending job is held back from being assigned to a printer for up to this many minutes after it was queued, so jobs arriving shortly after it can batch onto one plate instead of fanning out across idle printers. 0 = off (jobs assign immediately). The window is anchored to each job's own creation time, so a steady trickle of arrivals can never extend a job's hold. Manual "Match queue now" runs and direct printer assignments bypass holds. Optional: absent on settings saved before the field existed.
mergeScoperequired
"same-order" | "any"
Which jobs automatic merging may combine: 'same-order' only merges jobs from the same order (null orderId matches null — non-commerce jobs merge with each other); 'any' merges anything compatible. Manual merging is never restricted by this.
same-orderany
partSpacingMmrequired
number
Minimum clearance between placed parts, mm.
plateMarginMmrequired
number
Keep-out margin from the plate edge, mm.
processPoliciesoptional
Record<string, string>
Construct a type with a set of properties K of type T
slicerCompatibilityoptional
"allow-upgrades" | "account-default" | "exact"
How slicer engine/version differences gate merging and drive which slicer the merged plate is sliced with. Absent means DEFAULT_SLICER_COMPATIBILITY ("allow-upgrades"). See {@link SlicerCompatibilityMode }.
allow-upgradesaccount-defaultexact
reconcileReadSpoolsoptional
boolean
Bring a tag-read roll down to what its printer reports when the printer reads it well under what inventory holds: filament used outside Printago (a print sent from the slicer, or the roll run on another machine). Absent is on.
showGettingStartedChecklistoptional
boolean
Getting Started checklist visibility. Absent means "default by store age": stores created on or after GETTING_STARTED_RELEASE_DATE default on, older stores off (see isGettingStartedEnabled).
thumbnailStyleoptional
"orthographic" | "perspective"
Projection and shading the thumbnail renderer uses. Absent means DEFAULT_THUMBNAIL_STYLE ("orthographic"). Applies to renders from the moment it is saved — thumbnails already rendered keep their look until something re-renders them.
orthographicperspective
idrequired
string
processLowPriorityJobsrequired
boolean
qrWorkflowSettingsrequired
object
Which scan actions the store offers, and the defaults the app opens with.
actionOrderoptional
Record<string, string[]>
Construct a type with a set of properties K of type T
defaultSpoolGramsoptional
number
The weight Register spool opens with
disabledActionsoptional
string[]
Action ids the app never offers and execute refuses
moveSpoolBetweenSlotsoptional
boolean
When false, loading a spool that sits in another slot is refused instead of moving it
pairDefaultsoptional
Record<string, string>
Construct a type with a set of properties K of type T
slotStrategyoptional
"prompt" | "external" | "first_empty"
promptexternalfirst_empty
repairSlicerProfileValuesrequired
boolean
When true (the default), the cloud slicer clamps out-of-range / sentinel numeric values in the target slicer's printer/process/filament profiles (and the 3MF's embedded config) into the range that exact slicer build accepts, reproducing the desktop GUI's silent value tolerance so headless slices don't abort with CLI_INVALID_VALUES_IN_3MF (-18). Turn off to hand the profiles to the CLI verbatim. See packages/builders/slicers config-param-repair.
slicerrequirednullable
string
storeIdrequired
string
updatedAtrequired
string
format: date-time

Example Response

200 OK — application/json 
{
  "id": "string",
  "storeId": "string",
  "createdAt": "2025-01-15T12:00:00.000Z",
  "updatedAt": "2025-01-15T12:00:00.000Z",
  "slicer": "string",
  "processLowPriorityJobs": true,
  "automaticQueueMatching": true,
  "repairSlicerProfileValues": true,
  "currency": "string",
  "currencySymbol": "string",
  "defaultPrinterUserProfileId": "string",
  "defaultPrinterSystemProfileId": 1,
  "defaultProcessUserProfileId": "string",
  "defaultProcessSystemProfileId": 1,
  "defaultFallbackFilamentUserProfileId": "string",
  "defaultFallbackFilamentSystemProfileId": 1,
  "experimentalFeatures": {
    "financial-tracking": true
  },
  "generalSettings": {
    "autoMatchMaterialsNewPart": true,
    "enableTimelapse": true,
    "enableCompletionSnapshot": true,
    "enableTelemetryCapture": true,
    "amsSlotSelectionStrategy": "lowest-index",
    "addReadSpools": "off",
    "reconcileReadSpools": true,
    "fabmaticIgnoredErrorCodes": [
      {
        "code": "string",
        "note": "string"
      }
    ],
    "plateMerging": {
      "automaticMerging": true,
      "mergeScope": "same-order",
      "partSpacingMm": 1,
      "plateMarginMm": 1,
      "maxPartsPerPlate": 1,
      "mergeHoldMinutes": 1,
      "holdReleaseSaturationPercent": 1,
      "processPolicies": {},
      "slicerCompatibility": "allow-upgrades"
    },
    "showGettingStartedChecklist": true,
    "autoConfirmMacroRun": true,
    "thumbnailStyle": "orthographic",
    "aiDataProgram": {
      "status": "unasked",
      "decidedAt": "string",
      "decidedByUserId": "string"
    }
  },
  "qrWorkflowSettings": {
    "disabledActions": [
      "string"
    ],
    "pairDefaults": {},
    "actionOrder": {},
    "slotStrategy": "prompt",
    "moveSpoolBetweenSlots": true,
    "defaultSpoolGrams": 1
  }
}