Skip to content

Settings & onboarding

Two small merchant surfaces: settings (the tenant's configuration) and onboarding (a first-run checklist). Examples reuse the api() helper.

Settings

GET /merchant/settings returns four category objects. The row is materialized on first read, so you never get a 404 — just empty categories:

const settings = await api("/merchant/settings", { token });
// → { businessProfile: {…}, checkoutSettings: {…}, apiSettings: {…}, notifications: {…} }

PATCH /merchant/settings — permission: settings:manage. Owner/Admin retain broad access; Staff needs that group. Each category you send is shallow-merged into the stored object, so you only send what changed:

await api("/merchant/settings", {
  method: "PATCH",
  token,
  body: JSON.stringify({
    businessProfile: { displayName: "Summit Gear Co.", supportEmail: "help@…" },
  }),
});

To clear a single key, set it to null: { businessProfile: { supportEmail: null } }. Other categories and keys are untouched. The update emits a settings.updated audit event recording only the category names that changed — never the values.

Onboarding checklist

GET /merchant/onboarding returns the steps plus a progress summary:

const { steps, summary } = await api("/merchant/onboarding", { token });
// summary → { totalSteps, completedSteps, percent }  (percent is 0–100)

Missing step rows are lazily seeded from the canonical list on first read, so the checklist is always complete and ordered.

Toggle a step with PATCH /merchant/onboarding/steps/:stepKey — Owner/Admin only while onboarding remains a coarse setup workflow. :stepKey is a canonical key like business_profile, first_product, or verify_email; an unknown key is 404:

await api("/merchant/onboarding/steps/first_product", {
  method: "PATCH", token, body: JSON.stringify({ completed: true }),
});

completed: true stamps who finished it and when; false reopens it (clearing both). Each toggle emits an onboarding.step_completed or onboarding.step_reopened audit event.

Related

  • Auth & roles — roles, memberships, and permission groups
  • Audit log — settings + onboarding changes are recorded