Skip to main content

Status Mismatch

Why the status in Velocity may differ from the carrier's website, your store, or your customer's view

Table of Contents​

  1. How status updates work in Velocity
  2. Velocity vs carrier website
  3. Velocity vs Shopify / WooCommerce
  4. Customer-facing status vs Velocity
  5. Delivered in Velocity but customer says not received
  6. API: shipment_track vs top-level status field

1. How Status Updates Work in Velocity​

Q: How does Velocity get shipment status updates from carriers?​

A: Velocity maintains a status mapping with each carrier (3PL). When a carrier sends a status event, it is mapped to the corresponding Velocity status and updated on your order.

Status updates happen asynchronously — they should reflect in Velocity within 15 minutes of the carrier event occurring.

Q: The status in Velocity doesn't match what the carrier is showing. What should I do?​

A: If you notice a consistent mismatch between a carrier's status and what Velocity shows — beyond the normal 15-minute lag — please raise it with our support team. Velocity's status mapping with the carrier may need to be reviewed or corrected.

Include:

  • AWB number
  • The status shown in Velocity
  • The status shown on the carrier's website
  • How long the mismatch has been present

2. Velocity vs Carrier Website​

Q: The carrier's website shows a newer status than Velocity. How long should I wait?​

A: Status updates typically appear in Velocity within 15 minutes of the carrier event. If the carrier's website shows an event that Velocity doesn't:

  • Wait up to 15–30 minutes for the sync to catch up
  • If Velocity still hasn't updated after that, contact support with the AWB number and the event visible on the carrier's website

3. Velocity vs Shopify / WooCommerce​

Q: Velocity shows the order as shipped/manifested but Shopify still shows it as "Unfulfilled".​

A:

  1. Go to Settings → Integrations → Shopify
  2. Verify that "Push fulfillment status to Shopify" is enabled
  3. Fulfillment status is pushed to Shopify when a shipment is manifested
  4. If the update hasn't arrived in Shopify after 30 minutes, contact support with the Order ID

Q: WooCommerce shows a different order status than Velocity. What should I check?​

A:

  1. Go to Settings → Integrations → WooCommerce
  2. Review the status mapping configuration — the mapping between Velocity statuses and WooCommerce statuses may be set differently than expected
  3. Re-authenticate the integration if it was recently disrupted
  4. Contact support with the Order ID if the mismatch persists

4. Customer-Facing Status vs Velocity​

Q: My customer sees a different status than what Velocity shows. Why?​

A: Customers may be checking via:

  • Carrier's own tracking website — which may be slightly ahead of Velocity by up to 15 minutes
  • WhatsApp notifications from Velocity VAS — these are sent at specific milestones (created, out for delivery, delivered, NDR) and don't reflect every scan in between
  • Branded tracking page — which pulls from Velocity's data and will reflect the same status as your dashboard

5. Delivered in Velocity but Customer Says Not Received​

Q: Velocity shows "Delivered" but the customer says they never received the package.​

A:

  1. Check the Tracking Timeline in Order details — look for delivery date, time, and any agent notes
  2. Request Proof of Delivery (POD) via support — we'll obtain it from the carrier. POD typically includes delivery time, recipient name/signature, and sometimes a photo
  3. If the POD confirms delivery to the correct address and the customer still disputes it, a formal claim investigation may be needed — contact support to initiate this

6. API: shipment_track vs Top-Level status Field​

Q: Why does current_status in shipment_track sometimes differ from the shipment's status?​

A: shipment_track[].current_status is a raw log of all events received from the 3PL carrier, in the order they arrived. Carriers often send scans out of order or with delays — for example, a ready_for_pickup hub scan may arrive after the shipment has already been delivered. This means the most recent entry in shipment_track is not necessarily the most recent real-world state.

The top-level status field on the shipment object is the authoritative, de-duplicated, and correctly-ordered state maintained by Velocity.

Always use the top-level status field to determine the current state of a shipment. Do not rely on shipment_track[].current_status for status decisions.

Example: out-of-order carrier scan

A shipment is delivered at 14:00. The carrier's system sends:

  1. delivered scan at 14:05 (received by Velocity → top-level status becomes Delivered)
  2. ready_for_pickup hub scan at 14:30 (delayed; sent out of order by the carrier)

shipment_track[].current_status will show ready_for_pickup as the latest entry — but the shipment was already delivered. The top-level status correctly remains Delivered.

Need Help?​

When reporting a status mismatch, always include:

  • AWB number
  • What Velocity shows vs what the carrier / store / customer sees
  • Timestamp of the discrepancy