Skip to main content

Update Portal Settings

PUT 

/api/admin/portal/settings

Update the tenant-wide customer portal settings. Every field is optional: only the keys you send are changed and an omitted setting keeps its stored value, so a client can save one section without resending (or reverting) the others.

Required scope: customers:write

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

Body fields:

  • allow_backorder (optional, boolean): the portal-wide default for whether buyers can order more than is in stock. Every account inherits it unless that account sets its own allow_backorder, and an individual product overrides both. Ships enabled.
  • min_order_value_enabled (optional, boolean): master switch for a tenant-wide minimum order value. When false there is no default minimum (an account may still set its own).
  • min_order_value (required when min_order_value_enabled is true; number, greater than zero; otherwise nullable): the default minimum order subtotal applied to every account that hasn't set its own. A location's own minimum overrides this default. Stored as null whenever min_order_value_enabled is false.
  • min_first_order_value_enabled (optional, boolean): master switch for a tenant-wide opening-order minimum, the floor an account's FIRST order must reach (an account that has no non-cancelled sales order). Omit to leave unchanged.
  • min_first_order_value (required when min_first_order_value_enabled is true; number, greater than zero): the default opening-order minimum. An account's own min_first_order_value overrides it; the higher of the opening and regular minimum applies to a first order. Holdback: when holdback_enabled is true, the availability shown to portal buyers (catalog, product pages, inventory feed) is reduced — holdback_mode percent exposes holdback_percent % of available-to-sell, reserve subtracts holdback_reserve_qty units. Display-layer only; channel sync is unaffected.
  • branding_json (optional, object or null): the merchant branding shown to buyers. Prefer the dedicated Branding endpoints (PUT /api/admin/portal/branding, POST /api/admin/portal/branding/assets). Keys sent here are MERGED into the stored branding — keys you omit are kept, so sending only primary_color never wipes the logo; a key set to null resets it to the default; an explicit branding_json: null clears all branding (and deletes uploaded images). Omit to leave unchanged. Validated keys: primary_color, nav_color (6-digit hex, e.g. #1F3A2E), logo_url, mark_url (URL, max 2048 — a hand-hosted image; replacing an uploaded one deletes the uploaded file), display_name (max 80), support_email (email, max 255). Unknown keys pass through unchanged; version, logo_path and mark_path are server-managed and ignored. Colours are normalised to uppercase and version is bumped on every branding change.
  • approval_default_pricing_tier_id, approval_default_payment_term_id (optional, id or null): what approving an application sets when the reviewer leaves the field alone. Null = no default. Omit to leave unchanged.
  • approval_default_credit_limit (optional, number >= 0 or null): the default credit limit for a newly approved account. Null = none.
  • approval_default_order_discount_tiers (optional, array or null): the order-value discount ladder a newly approved account starts with, same shape and rules as an account's order_discount_tiers_json. Null = none.
  • application_alert_user_ids (optional, array of user ids, at most 20): staff users who get an in-app alert and an email when a new application arrives. Each must be a user of this account.
  • application_alert_emails (optional, array of email addresses, at most 10): addresses that get the new-application email. When both lists are empty, the alert goes to the users who can manage the portal.
  • approval_default_catalog_ids (array of catalog ids, optional): the catalogs a newly approved account is assigned (it sees their union). Empty = none, so new accounts follow the catalog marked Default. Deleted catalogs are dropped at approval.
  • preview_access_enabled (optional, boolean, default false): instant preview access for applicants. A new application provisions its account at once in the preview state (approval defaults applied) and invites the applicant, who can browse catalog, dealer pricing and stock but cannot order until the application is approved. Approving converts that same account to active; rejecting disables it. Omit to leave unchanged.
  • preview_access_business_domains_only (optional, boolean, default true): limit instant preview to business email domains; free-mail applicants (gmail, yahoo, outlook, icloud, aol, proton, ...) wait for a reviewer. Omit to leave unchanged. margin_replacement_cost_adjustment_percent (optional, −90..100, null/0 = none) and margin_replacement_cost_adjustment_label (optional, max 40, e.g. "at special"): an adjustment to the staff "View as buyer" margin overlay's replacement cost (the default supplier's price) — e.g. −15 for a merchant that only buys at the supplier's specials. Staff-only; never shown to buyers.

Order history & quotes:

  • order_history_scope: all_channels (default — buyers see every order the customer has, minus another channel's drafts) or portal (only orders placed in the portal).
  • guest_rfq_enabled: open the public Request a quote page (no account needed). Default false.
  • guest_rfq_note: optional plain-text intro above that form, max 2000; blank clears it.
  • rfq_pricing_hidden_until_sent: hide a requested quote's prices from the buyer until staff send it. Default false. All four are optional on update; an omitted key keeps its value.

Request​

Responses​

OK

Response Headers
    Content-Type