Troubleshooting

Most problems fall into one of these buckets. Start here before emailing support — most are self-serve.

Order didn't split

The whole order landed in Brightpearl as a single SO instead of being split into A/B.

Check 1 — Is the cart actually mixed? Single-status carts (all in-stock or all pre-order) are passed through unchanged by design. Look at the Splits dashboard: if the order shows up labelled "passthrough", that's expected.

Check 2 — Is your pre-order tag right? Open a pre-order product in Shopify and confirm it carries the exact tag set in Settings → Pre-order tag. Tags are case-insensitive but must match otherwise. Common gotcha: trailing whitespace.

Check 3 — Was the order placed before you connected Brightpearl? Pre-installation orders aren't retroactively split. Only orders placed after install go through nohold.

Check 4 — Did the webhook reach us? Splits dashboard shows every order nohold received. If your order isn't on the list at all, the webhook didn't reach us. See Webhook not received below.

SO didn't release after stock arrived

Pre-order stock landed in Brightpearl, but the held SO is still on hold.

Check 1 — Is all the pre-order stock for the SO available? nohold doesn't partially release. If the SO has 3 pre-order lines and only 2 have stock, it stays held. See Lifecycle → Auto-release.

Check 2 — Is the stock event firing? Brightpearl emits stock events on goods-in receipts and stock transfers. If you adjusted stock manually via the database or a non-standard tool, no event fires and nohold won't know.

Workaround: book a small goods-in receipt (even 0 quantity) on the SKU to trigger the event.

Check 3 — Is the SO in the configured deferred status? If someone manually moved the SO from the deferred status to a different held status, nohold no longer recognizes it as a candidate for release. Move it back, or release it manually from Brightpearl.

Brightpearl connection failed

You hit "Connect" and got an error.

• Account code is the slug in your Brightpearl URL — abc123 from abc123.brightpearl.com. Not the company name.
• Staff token must be from a user with API access enabled. Check Brightpearl → Settings → Staff → [user] → API.
• Tokens are shown once when generated. If you didn't copy it, generate a new one and try again.
• If your Brightpearl account is on a non-EU data centre, the URL pattern differs slightly — contact us and we'll configure the right region.

Webhook not received

The order was placed in Shopify but doesn't appear on the Splits dashboard at all.

1. Check Shopify webhook subscriptions — Settings → Notifications → Webhooks. There should be an orders/create webhook pointing to https://api.nohold.app/webhooks/shopify. If missing, reinstall the app.
2. Check Shopify webhook logs — Shopify shows recent webhook delivery attempts and HTTP responses. A 401 means the HMAC signature didn't match (rare; usually a Shopify bug or app reinstall in flight). A 200 means we received and accepted it.
3. Check the dashboard "Last received" timestamp on Settings — if it's recent, nohold is hearing webhooks; the issue is specific to that order.

ERP dispatch stuck

The dashboard shows a split as "Queued" or "Dispatching" for more than a minute.

Check 1 — Connection health on the dashboard. Yellow banner means the Brightpearl circuit breaker is open. Orders will resume dispatching when Brightpearl recovers — usually within a few minutes. See Failure handling.

Check 2 — DLQ entries. If the split lands in the DLQ, the dashboard shows the failure reason (auth_invalid, status_id_unknown, etc.). See DLQ for how to clear it.

Check 3 — Brightpearl rate limits. If you've placed a flood of orders (say, after a flash sale), dispatches queue at 50/minute per merchant. They'll catch up; nothing is lost.

Tax / shipping totals don't reconcile

The two SOs in Brightpearl don't sum back to the original Shopify total.

This shouldn't happen. nohold prorates totals deterministically. If you see this, please email us with the Shopify order number — we'll trace the dispatch and fix the bug.

Plan limits hit

Mid-month, the dashboard banner says "Quota reached" and orders aren't being split.

Mixed-cart splits count toward your monthly quota; single-status passthrough orders don't. If you've genuinely outgrown your plan, upgrade from Settings → Billing. Quota resets on the 1st of each calendar month.

While over quota, mixed carts are dispatched as a single held SO (the safe-default Brightpearl behavior) until you upgrade. Orders are not lost.

Still stuck?

hello@nohold.app — include the Shopify order number, the symptom, and any banner text you see on the dashboard. We can usually pinpoint the issue from the order number alone.