Troubleshoot Orderly

Start with the symptom you see, run the checks in order, and stop when the expected result returns.

Before you start

Time

5–15 minutes

For

Operators, administrators, and developers

Before changing anything, record the selected organization, the affected bridge or carrier account, the approximate failure time, and the full error message. For API failures, also save the response status and request ID.

Orders are not syncing

Open Bridges↗

1. Confirm the correct organization is selected in the dashboard.
2. Find the source bridge and check its status. It must be active.
3. Click Sync now. If it is unavailable, resume or reconnect the bridge first.
4. Open Tasks & Schedules → History and inspect the newest grab-orders run.
5. If the run succeeded, open Orders and clear filters or saved views that might hide the new records.
6. If the run failed, open its error, correct the credentials or configuration, and run it again.

For ongoing sync, enable supported webhooks or schedule grab-orders every 15 to 30 minutes. See Connect a store and sync orders.

A bridge will not connect

• For OAuth platforms, confirm you are an administrator in the platform and approve every requested permission.
• For Shopify, enter only the store subdomain—the mystore part of mystore.myshopify.com.
• For API-key platforms, remove accidental spaces and confirm the key has not expired or been revoked.
• If the bridge previously worked, use Configure to rotate its credentials instead of creating a duplicate connection.
• If a platform reports an authorization callback error, return to Orderly and start the connection from Bridges again.

Webhooks are not arriving

1. Confirm the bridge is active and the required webhook topics are enabled under Configure → Real-time Webhooks.
2. Confirm the destination is public HTTPS. Local and non-HTTPS environments cannot receive real platform delivery.
3. Return 2xx quickly and move longer processing to a queue.
4. Check that signature verification uses the unmodified request body.
5. Use bridge history or the receiving service's logs to distinguish a delivery failure from a handler failure.

Non-2xx deliveries are retried with backoff. See Webhooks for event names and payload shape.

No shipping rates appear

Open Rate Calculator↗

1. Confirm at least one carrier account is active and has the Rating capability.
2. Check whether the account is Test or Production and use shipment data appropriate for that environment.
3. Complete both addresses with street, city, state, ZIP, and country.
4. Enter a positive package weight. If you enter dimensions, provide length, width, and height together.
5. Choose today or a future ship date.
6. Use Test credentials on the carrier account if the request still fails.

Some services are unavailable for particular origin, destination, package, or account combinations. Try a standard package before debugging a specialized service.

API requests return 401, 403, or organization errors

Response	Check
401 Unauthorized	The bearer token or API key is present, current, and copied without extra whitespace.
403 Forbidden	The key includes the scope required by the endpoint and your role can perform the action.
org_required	Send X-Organization-Id with the organization UUID.
Empty data	Confirm the organization header selects the organization that owns the records.
Browser CORS error	Keep credentials private by calling the API from your backend.

Start from the known-good request in Authentication. If one endpoint fails while another succeeds, compare the endpoint's required scopes in the API reference.

Intelligence is empty

Open Intelligence↗

1. Confirm the selected organization has Intelligence access.
2. Open Ingest & Scoring and confirm shipments and events were imported successfully.
3. Confirm tracking events use supported carrier codes and include event timestamps.
4. Allow delivered volume to accumulate for on-time and scorecard metrics.
5. Clear dashboard search and filters.

An empty Intervention Queue can be healthy: it means no in-transit shipments are currently outside their transit SLA. An empty carrier chart usually means there is not enough delivered volume yet.

If a board could not load, click Retry, confirm the selected organization, and check Orderly status.

The dashboard looks stale or incomplete

• Refresh the current view and check the LIVE or data-as-of indicator.
• Confirm the newest bridge task, tracking event, or ingest upload completed.
• Check Orderly status for an active incident.
• Compare the dashboard with a direct API request for the same organization.
• Sign out and back in if organization switching or permissions appear stale.

Escalate with useful context

Email support@orderly.dev with:

• organization name and organization ID,
• affected page, bridge, carrier, or tracking number,
• timestamp and time zone,
• complete error text and HTTP status,
• request ID for API errors,
• the checks already completed.

Do not send passwords, API keys, bearer tokens, or carrier credentials.