FAQ & troubleshooting

Answers to the questions support gets asked repeatedly, grouped by area. If your question isn't here, the per-section docs linked from the sidebar usually cover it — or email support@distribu.app.

Account & login

I forgot my password.

There's no self-serve "forgot password" flow today. Email support@distribu.app from the address on your account and we'll issue a reset link. Planned but not shipped.

I'm an owner and I'm locked out of my company.

Same deal — email support with the company name and we'll restore access. If someone else on the team still has ADMIN or OWNER access, they can also invite you back under a new email address from the Team settings page.

Can I change my email address?

Not through the UI today. Email support with the old and new addresses and we'll swap them for you.

Can I have one user account across multiple companies?

Yes — the same User can have memberships in multiple companies. Accept an invite for the second company while signed in, and you'll see a company-switcher in the dashboard header. See Team & roles.

Can one customer buy from multiple distributors?

Yes — a customer account is scoped per distributor, but one person can self-register at multiple storefronts using the same email address. Each storefront gets its own customer account. Carts and orders don't cross between stores.

Products

My product isn't showing up on the storefront.

Check these in order:

Is it active? On the inventory page, each product has an Active / Inactive toggle. Inactive products are hidden from the storefront but still usable in dashboard orders.
Is it in stock? Zero-stock products still show on the storefront, but the "Add to cart" button is disabled. Look for the red "Out of stock" badge.
Is the storefront filter hiding it? The catalog page has a category filter — double-check you're on "All categories" if you're expecting to see everything.
Is the customer logged in? Price-override-gated products only appear once a customer is authenticated. See Price overrides.

Can I upload multiple images per product?

Not today — one imageUrl per product. Planned but not shipped. The workaround is to use a single composed image (e.g. four angles tiled into one file) until proper galleries land.

Image upload says "Image too large."

5 MB is the cap. See Product images for the supported formats and limits. Most phone photos (especially iPhone HEIC) are well over 5 MB — resize first or toggle your camera to save in "Most Compatible" JPEG format.

My SKU import keeps rejecting rows as duplicates.

Check for:

Trailing whitespace — "WDG-001 " and "WDG-001" are treated as duplicates because we trim before comparing.
Case sensitivity — SKUs are case-sensitive, so WDG-001 and wdg-001 are two different SKUs.
Leading zeroes stripped by Excel — open the file in a plain text editor to verify. See Products CSV → Common pitfalls.

Customers

A customer can't log in to the storefront.

Most common cause: they're trying to log in before you've approved their contact. Customer contacts are passwordless — they register, you (the distributor) invite them, they click the link, they're in. See Storefront → Customer login.

Less common:

Their email address doesn't match any contact at your store.
They were marked BLOCKED — check the customer's status in the dashboard.
The contact's invite token expired (7 days) — re-send from the customer's detail page.

A customer says they never got the invite email.

Two common causes:

Spam folder. Especially for Gmail addresses with no prior relationship to your store's sending domain.
Wrong email. The customer's address has a typo in their customer record.

You can always copy the invite URL directly from the customer's detail page and send it out of band (Slack, SMS, whatever).

Can I import customers with their addresses in one CSV?

Not today — the customers CSV has five columns and doesn't include addresses. Addresses are managed separately at the customer's detail page, or by the customer themselves via the storefront. See Customers CSV format.

Orders

Why isn't stock decrementing on a dashboard-created order?

It is — stock decrements the moment the order is created, regardless of source. Look at the product's current stock against what it was before the order. Note that dashboard-created orders don't trigger the low-stock alert email (that only fires on storefront orders), so the lack of alert isn't the same as "stock didn't move."

Why can't I transition an order from CANCELLED back to SUBMITTED?

You can't. CANCELLED is a terminal status both in the dashboard UI and the REST API — there's no undo button. If you cancelled by mistake, create a new order with the same line items. The stock that was returned when you cancelled is still available.

This is the only transition the API blocks — everything else is permitted. See REST API → Orders endpoints for the full transition rules.

I'm over my monthly order limit.

The counter resets on the 1st of the month at 00:00 UTC. Until then, new orders are blocked with This store has reached its monthly order limit. Cancelled or deleted orders don't reduce the count — it tracks everything created this month.

Workarounds: upgrade the plan for immediate headroom (the limit applies instantly on upgrade), or wait until the 1st. See Plans & subscription → Orders-per-month reset.

Where's the "Export CSV" button on the Orders page?

Not shipped yet. See Orders → Exports and CSV → Orders export for the three workarounds (REST API, webhooks, support export).

Storefront

My storefront URL isn't loading.

Visit /store/{your-slug} — the slug is shown on your dashboard home page and in the Settings → Storefront page. Double-check the slug spelling; it's part of the URL, case-sensitive, and can't contain spaces.

If you're a hosted customer, your storefront is at https://distribu.app/store/{your-slug}. If you self-host, it's at whatever domain you've deployed to.

Can I use a custom domain for my storefront?

Not today — every storefront lives under your Distribu domain at /store/{slug}. Custom domains (orders.yourcompany.com) are planned but not built.

Customers are placing orders I don't want them to.

A few tools to control this:

Set the customer's status to BLOCKED — they can still log in but can't place orders.
Set a low credit limit — reference only today, not enforced. See Customers CSV.
Deactivate specific products (Active toggle off) — hides them from the storefront entirely.
Raise the minimum quantity — not supported today, but roadmap.

API

I'm getting 401 on every API call.

Check in this order:

Authorization: Bearer dk_... — lowercase bearer is rejected, the scheme has to be Bearer with that capitalization.
The key hasn't been revoked. Check API keys settings — revoked keys don't work even if the prefix looks valid.
You're calling /api/v1/..., not /api/.... The v1 path prefix is required.
You're not on a company-scoped URL. Every API endpoint is scoped to the API key's company — no {companyId} path parameter is needed.

See REST API → Authentication.

I'm getting 403 on `POST /api/v1/orders`.

The API key is missing the orders:write scope. Revoke the key and create a new one with the correct scope checked. Scopes can't be changed after creation. See Scopes.

My scripts are getting rate-limited.

60 requests per minute per key. If you need more, either:

Slow your client down. Even naive scripts rarely need more.
Use multiple API keys in a fleet. Each key gets its own 60/min bucket.
Contact support for Enterprise accounts with higher limits.

See REST API → Errors for the headers that tell you how close to the limit you are.

POST /api/v1/orders ignores the customer's price override.

That's intentional (for now). The API uses the catalog price on every line item; it doesn't apply per-customer overrides. The storefront order flow does apply overrides. If you need override-aware pricing via the API, email support — it's on the roadmap.

Webhooks

I registered a webhook but it's never firing.

Check:

Is the webhook active? On the Webhooks settings page, each webhook has an Active toggle. Disabled webhooks never fire.
Is the webhook subscribed to the event you're testing? An order.created webhook won't fire on a status change.
Are you placing storefront/API orders, or dashboard orders? order.created doesn't fire for orders created inside the dashboard (+ New order). Only storefront + API creation trigger it.
Is your endpoint returning 2xx within 10 seconds? Check the recent-deliveries accordion on the webhook card. Non-2xx or timeouts show up as red rows.

See Webhooks → Event types and Webhooks → Retries.

My signature verification is always failing.

99% of the time this is from re-serializing the JSON before hashing. Always hash the raw bytes from the request body, not a re-stringified parsed object. See Signatures.

Other common causes:

Wrong secret (copy/paste whitespace)
Using the wrong hash (SHA-1 instead of SHA-256, base64 instead of hex)
Different webhook's secret (each webhook has its own)

A delivery failed — how do I retry?

You can't, today. Failed deliveries are not automatically retried, and there's no "redeliver this event" button. See Retries & delivery for the reconciliation-via-polling workaround.

Billing

Can I get a refund?

Email support@distribu.app with the invoice ID (visible in the billing portal) and the reason. We'll review and process the refund for you.

My subscription is "past due" but I just paid.

Could be two things:

The status hasn't synced yet. Refresh in 30 seconds.
Invoice didn't actually succeed. Some payments are held for 3D Secure review. Check the invoice in the billing portal — if it's open / draft, the payment isn't complete.

If it's still stuck after a minute, email support.

The trial ended and I didn't upgrade — what happened to my data?

Today, nothing. Trial expiry is a soft deadline; the banner flips but the app keeps working at Starter-tier limits. Your data is intact. Upgrade from /dashboard/billing/plans whenever you're ready.

Can I switch from monthly to annual mid-period?

Yes, through the billing portal. The unused portion of the current monthly period is prorated against the first year's annual charge. See Managing your plan.

Still stuck?

If an answer here didn't fix your issue, email support@distribu.app with:

What you were trying to do
What you expected to happen
What actually happened
Any error messages / screenshots
Your company name or slug

More on what to include and how we route requests on Contacting support.

Next: Contacting support.