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.
customers:writeGrant 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_enabledis true, the availability shown to portal buyers (catalog, product pages, inventory feed) is reduced —holdback_modepercentexposesholdback_percent% of available-to-sell,reservesubtractsholdback_reserve_qtyunits. 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 onlyprimary_colornever wipes the logo; a key set to null resets it to the default; an explicitbranding_json: nullclears 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_pathandmark_pathare server-managed and ignored. Colours are normalised to uppercase andversionis 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
previewstate (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) andmargin_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) orportal(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
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Unprocessable Content
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.