Skip to main content

Update Setting

PUT 
/api/v2/settings/:slug

Updates a single setting by slug. Body shape varies per slug — for simple settings the body is {"value": ...}; for grouped settings (e.g. purchase-order, forecasting, general) the body is a flat object of allowed keys.

Required scope: settings:write

Grant this scope to your token under Settings → Developer → Personal Access Tokens.

Slug purchase-order accepts:

  • cc_outgoing_email (string|null, max 500) — comma-separated CC list applied to outgoing PO emails.

Slug general accepts (validated keys):

  • weight_unit (string: lb|g|kg|oz) and dimension_unit (string: in|cm|mm) — the units new products start with.
  • connectivity_alert_sound_enabled (boolean) — play a repeating audio alert on the device when the app loses connection to the server, and a confirmation tone when restored. Non-boolean values are rejected with 422.
  • stranded_order_minimum_age_days (integer, 0-90) — whole business days (Mon-Fri; weekends do not count) an order must go without producing a fulfillment order before the "Stuck, Never Dispatched" dashboard tile counts it as stranded. 0 disables the floor; values outside 0-90 are rejected with 422.

Slug packing-slip-rules accepts (every field optional; an empty list turns the rule off):

  • suppressed_line_descriptions (array of strings, each max 255) — line descriptions to leave off the packing slip entirely, such as shipping protection or insurance lines a warehouse cannot pick. Matched case-insensitively against the full line description.
  • highlighted_shipping_methods (object of keyword => colour name, each value max 32 chars) — when the order's shipping method contains the keyword, the shipping method prints highlighted. The value must be one of blue, green, purple, orange, red; anything else is rejected with 422. It is a colour name, never CSS.
  • highlighted_address_keywords (array of strings, each max 255) — when the shipping address contains one of these, the name and address block print highlighted.
  • brand_sizing_notes (object of brand name => note, each value max 255) — note printed under that brand's lines. Brand names are matched case-insensitively.

Authentication: Requires Bearer token.

Requires permission: settings.update

Slug inventory accepts the inventory-debt controls:

  • negative_inventory_policy (string: block|warn|allow) — whether a sale may ship when it would take a warehouse below zero on hand. block is the default and refuses the shipment; warn allows it once acknowledged with a reason; allow records it silently. Anything other than block requires an Inventory Debt Clearing account to be mapped first, otherwise the request is refused with 422 — the shipment would otherwise succeed while its journal could not be built. This policy governs shipments a PERSON chooses to make. A shipment already reported by a sales channel is not governed by it at all: the goods have left, so the units SKU cannot cover are always recorded as inventory debt regardless of this setting — including under block. Serial-tracked and lot-tracked products are the exception and are never recorded as debt, because SKU cannot owe a serial it never held; those surface for manual reconciliation instead.

  • negative_inventory_applies_to (array of sale|transfer|manufacturing|vendor_return) — which operations the policy covers. Counts and adjustments can never be included. Like the policy itself this scopes operator-initiated work only; a shipment already reported by a sales channel is recorded as debt even when its operation is not listed here, because the goods have gone either way.

  • debt_cost_estimate_chain (array, min 1, of last_purchase_price|average_cost|product_default_cost|zero) — the ordered list of bases tried until one yields a cost above zero. The first entry is the preferred basis. zero stops the search, so entries after it are never consulted.

  • debt_requires_reason (boolean) — require a reason when acknowledging a shipment below zero.

  • block_period_close_with_debt (boolean) — make outstanding debt block the month-end close rather than warn.

Slug product accepts:

  • days_of_sales_history (integer, 1-365) — days of sales history used for daily average consumption.
  • show_barcodes_on_lines (boolean, default true) — show each product's barcode on sales order, purchase order and sales credit lines. Non-boolean values are rejected with 422.

Slug warehouse accepts the transfer numbering defaults:

  • transfer_prefix (string|null, max 20) — prefix for new transfer numbers.
  • transfer_num_of_digits (integer, 0-10) — zero-padded digits after the prefix. Values outside 0-10 are rejected with 422.
  • transfer_shipping_method_id (integer|null) — shipping method new transfers start with.

Slug pos accepts the register toggles:

  • enabled (boolean) — turn the point-of-sale register on.
  • require_customer (boolean) — every sale must have a customer; checkout without one is rejected with 422.
  • auto_print_receipt (boolean) — open the printable receipt when a sale completes.
  • auto_show_new_products_in_register (boolean, default true) — new products appear on the register's product grid.
  • payment_processor (string: square|stripe) and square_location_id (string|null, max 64).

Serial format. For inventory-tracking, default_serial_format must include a sequence token, {seq} or {seq:N}, so every generated serial is different. A format without one fails with 422 on default_serial_format.

For general: timezone must be an IANA-style zone name (for example America/New_York); anything else is a 422. For accounting: Custom close checklist items (close_custom_checklist_items) must have distinct keys; keys that differ only in case or punctuation (for example "Freight" and "freight") are a 422 on the second item.

Request​

Responses​

OK