Supplier Onboarding

This guide walks supplier admins through the full self-serve setup flow: starting a trial, completing the six-step onboarding wizard, and publishing your first retailer locator. Every step maps to a real screen in the supplier admin app and a real endpoint on the Stockisto API — no developer required.

Before you start

You only need two things to begin:

• A work email address (this becomes your supplier admin login).
• Your company name (this becomes your tenant and your locator's URL slug).

Everything else — brand colors, retailer data, install method — is configured inside the wizard and can be changed later.

Step 1: Start your trial

Go to the signup page and submit your email and company name. You can optionally pick a vertical preset (an industry style template) at this stage; if you skip it, you'll choose one inside the wizard.

Behind the scenes this calls:

POST /api/v1/trial/signup
Content-Type: application/json

{
  "email": "admin@yourbrand.com",
  "companyName": "Acme Bath Co",
  "verticalPresetSlug": "home-improvement"
}

What provisioning does:

• Generates a unique URL slug from your company name (e.g. acme-bath-co). If the slug is taken, a numeric suffix is added.
• Creates your tenant as a trial tenant with a 30-day trial window.
• Creates your SupplierAdmin user and a default LocatorProject (starts as Draft, install method Hosted).
• Sends a magic link sign-in email.

Validation rules

• Email — must be a valid address, max 254 characters.
• Company name — required, between 2 and 200 characters.
• Vertical preset slug — optional; lowercase letters, numbers, and hyphens only.

Confirm your email (magic link)

Open the email and click the sign-in link. It lands on /auth/verify?token=…, verifies the token, stores your session, and signs you in. First-time suppliers are greeted on the Welcome screen with a Start setup button that opens the wizard.

Step 2: The onboarding wizard

The wizard lives at /wizard and has six steps. Visiting /onboarding redirects here. Your progress is tracked per-tenant and survives sign-out, so you can leave and return at any time.

The six steps, in order:

1. Brand Profile — name & website
2. Choose Vertical — colors & style preset
3. Add Retailer Data — retailer locations
4. Choose Install Method — how to install
5. Verify Install — confirm the snippet is live
6. Publish Locator — go live

The left sidebar shows your position, a running "X of 6 complete" count, and a progress bar. You can click any step to jump to it, and completed steps can be reopened and updated.

Step 2.1: Brand Profile

Enter your brand tagline and brand website (both optional). The tagline appears in your locator's hero section ("Find a stockist near you"); the website powers the "back to brand site" link.

Saving stores the tagline on your locator project. These fields are non-blocking — if the save fails, you still advance, and you can edit everything later from Brand & Locator settings.

Step 2.2: Choose Vertical (style preset)

Pick a vertical preset that fits your industry. Each preset is a ready-made bundle of:

• Primary, secondary, and accent colors (shown as swatches).
• Heading and body fonts.
• A default hero tagline and icon set.

Selecting a preset applies its colors, fonts, and tagline to your project in one click. You can fine-tune every value afterwards in Brand & Locator settings — the preset is a starting point, not a lock-in.

Step 2.3: Add Retailer Data

This is where your locator gets real content. You have three options:

• Import CSV — upload a CSV or Excel file of retailer locations. This opens the importer; see the Data Import guide for the field reference, geocoding behavior, and the review queue.
• Use demo data for now — Stockisto shows sample retailer locations so your locator looks complete from day one. Swap in real data whenever you're ready.
• Skip for now — this step is optional and can be completed later.

Step 2.4: Choose Install Method

Decide how your locator reaches your customers. The wizard offers three methods (a fourth, link-only, is available from settings):

• Hosted page (instant) — Stockisto hosts your locator at a Stockisto URL. No code, ready in seconds. This is the default and the fastest path to live.
• Embed snippet — copy a small <script> tag into your website to embed the locator inline.
• Google Tag Manager — add the locator through a GTM custom-HTML tag, with no code deploy. See the GTM Install guide.

Your choice is saved to the project and can be changed at any time.

<!-- Example embed snippet (also available from project settings) -->
<div id="stockisto-locator"></div>
<script>
  (function(w,d,s,o){
    var j=d.createElement(s);j.async=1;
    j.src='https://cdn.stockisto.com/embed/v1/loader.js';
    j.setAttribute('data-project-id','YOUR_PROJECT_ID');
    j.setAttribute('data-api-base','https://api.stockisto.com');
    d.head.appendChild(j);
  })(window,document,'script');
</script>

Step 2.5: Verify Install

Once your snippet is live, this step checks that Stockisto is receiving events from your site. It reads the latest install health snapshot for your project and reports one of a few states:

• Healthy — the script is detected and working. The wizard shows a success message and advances automatically.
• Pending / not installed — no events yet. You'll see a friendly "not installed yet" notice with any specific issues listed.

If it's not healthy yet, use Check again to re-run the health check, or Skip for now — this step is optional and your hosted preview keeps working in the meantime.

Step 2.6: Publish Locator

The final step. You'll see a summary and two actions:

• Review locator config — opens the Locator Config page to double-check colors, filters, and map settings before going live.
• Mark as published — completes onboarding and takes you to your dashboard.

When all six steps are complete, the wizard shows a brief celebration and redirects you to /dashboard.

Step 3: First publish

Publishing flips your locator project from Draft to Published. Under the hood it:

• Snapshots your current configuration as the last known good config (so you can roll back).
• Records the publish timestamp.
• Invalidates the cached locator search, config, and brand theme so the live version updates immediately.

POST /api/v1/projects/{projectId}/publish
Authorization: Bearer <your token>

Visibility

A published locator is Public by default — anyone with the URL can view and search it. You can change visibility to Unlisted (URL works but isn't promoted) from your locator settings. See the Sharing + Groups guide for details.

What's next?

Your locator is live. To get the most out of it:

• Data Import guide — import your full retailer network and learn the review workflow.
• GTM Install guide — embed the locator on your site with no code deploy.
• Sharing + Groups guide — control who can see your locator and organize retailers.
• Analytics + ROI guide — track locator searches, leads, and ROI from your dashboard.