Troubleshooting & FAQ

Recovery steps for common shipping errors, answers to frequent questions, and a quick-reference screen index.

Common errors and recovery

"Calculated at checkout" never resolves

What it means: the shipping cost placeholder shows while the customer hasn't yet entered a delivery pincode, or while the serviceability check runs.

Recovery: confirm at least one shipping provider is connected under Extensions → Plugins. If connected, try the same pincode in the Rate Calculator — if that also fails, the provider's API may be temporarily down. Try again in a few minutes.

Shiprocket connection not working after entering credentials

Recovery:

1. Log in at shiprocket.com directly to confirm your credentials are valid — reset your password there first if not.
2. Confirm you're entering your login email and password, not an API key.
3. Check your Shiprocket wallet balance — a zero balance can cause certain calls to fail.
4. If Test Connection shows "Connected" but bookings fail, your account may need the Channels API enabled — contact Shiprocket support.

"Shiprocket authentication is temporarily blocked" or "sign-in is quarantined"

What it means: the platform protects your Shiprocket account from being locked by Shiprocket's own security system. When a sign-in attempt is rejected (wrong password, or the account is already temporarily locked by Shiprocket), the platform pauses further attempts — first for a short cooldown that grows with each failure, and after 5 consecutive rejections it quarantines the saved credentials and retries at most once every 24 hours. Without this pause, repeated automatic retries would keep your Shiprocket account permanently locked and trigger "Temporary Account Lock for Security Reasons" emails from Shiprocket.

Recovery:

1. Log in at shiprocket.com directly. If Shiprocket says your account is locked, wait out the lock (typically 30–60 minutes) — do not keep retrying, and reset your password there if needed.
2. Once you can log in on shiprocket.com, go to Extensions → Plugins → Shiprocket in your admin panel, re-enter (or simply re-save) your email and password, and click Save. Re-saving credentials clears the quarantine within a few minutes — you don't have to wait for the 24-hour retry.
3. Run Test Connection to confirm the green "Connected" badge returns.

Note: temporary network problems on Shiprocket's side never trigger the quarantine — only rejected credentials do. If you see this message without ever changing your password, your Shiprocket account was likely locked by Shiprocket first; step 1 still applies.

Warehouse shows "Registration failed"

What it means: Shiprocket rejected this pickup location, and bookings from it will keep failing until it's fixed. The warehouse card shows the carrier's exact error text underneath the status chip — read that first, it's the real cause, not a generic message. The same real reason now also shows up in the toast right after you click Register with Shiprocket manually, for example "Registration failed: Address name already exists and is inactive" — you don't have to open the warehouse card to see why it didn't work.

Recovery:

1. If the error mentions a name conflict ("this name already exists" / similar — for example Shiprocket's "Address name already exists and is inactive"), see Adding a warehouse — either reactivate the existing address on shiprocket.in or rename this one.
2. If the error mentions the phone number or an OTP/IVR step, Shiprocket verifies new pickup addresses by calling the contact phone — confirm the number is correct and reachable, then try registering again.
3. If the error is about the address itself (pincode, locality), correct it in the warehouse's details and re-save.
4. After fixing the cause, BillionBiz automatically retries a failed registration every 5 minutes — you don't need to manually re-register. If a failed booking alert on an order still shows Retry booking disabled, see "Retry booking button is missing / replaced with a note" below — this is expected until the recheck confirms your fix worked.

A "Pending" chip is not the same as "Registration failed." A warehouse can also sit at Pending even after Shiprocket accepts the registration call, if BillionBiz can't yet confirm the pickup shows up in Shiprocket's own live pickup-location list — see Reading the warehouse status chip. That case is not covered by the automatic 5-minute retry above (only a genuinely failed registration retries automatically) — click Register with Shiprocket again to re-check it.

Added a working warehouse but bookings still fail or use the wrong address

What it means: shipments are only ever booked from your default warehouse — never "whichever warehouse is healthy" and never the newest one you added. Adding a second, correctly registered warehouse changes nothing until it's made the default.

Recovery: go to Shipment → Warehouses and check which card has the green Default badge. If it isn't the one you just fixed, click Set as default on the warehouse you want used, then retry the booking. See Default warehouse for the full explanation.

Retry booking button is missing / replaced with a note

What it means: the failure alert (on the order, or the failed-shipments banner) only offers Retry booking when retrying could plausibly succeed — either the failure is a known-transient carrier issue, or you've already taken the suggested fix and BillionBiz is waiting to confirm it worked. If the underlying cause (e.g. a failed warehouse registration) hasn't been addressed yet, retrying would just reproduce the identical error — so instead you'll see a short note ("Retrying won't help until the issue below is fixed — use the action instead") and the fix-it button/CTA.

Recovery: follow the CTA linked in the alert (usually straight to the warehouse or plugin settings that need fixing). Once the cause is fixed, BillionBiz automatically rechecks the failure in the background — Retry booking reappears once it's eligible again, or the failure clears on its own if the recheck succeeds.

Failure alert says "The change you made didn't fix this"

What it means: you (or someone on your team) already acted on a failed-booking alert — for example, registered a warehouse or fixed an address — and BillionBiz's automatic recheck confirmed the exact same carrier error is still happening.

Recovery: the underlying issue wasn't actually resolved. Re-read the carrier's error text shown in the alert (it's the same real message from Shiprocket, not a generic one) and double-check the fix was saved correctly — a common cause is fixing the wrong warehouse when more than one exists (see "Added a working warehouse but bookings still fail" above), or a typo re-introduced during the fix. If the error text itself is unclear, contact Shiprocket support with the exact wording shown.

Retry all says some orders were "skipped"

What it means: the toast after Retry all breaks the batch into shipped / failed / skipped — "skipped" means that order was never actually attempted, most commonly because no shipping provider is configured. This is different from "failed," which means a carrier was tried and rejected the booking.

Recovery: connect a shipping provider (or fix whatever the toast's reason names), then retry. Skipped orders also still show individually on the Failed Bookings tab, so you don't have to remember which ones need a second look. See Retry all always tells you what happened.

A plugin shows "Needs attention" even though it's turned on

What it means: for Shiprocket and Delhivery, the Plugins list badge reflects live connection health, not just the plugin's own active/inactive switch — a plugin can be switched on while its carrier credentials are missing/inactive or its session token has expired or is about to.

Recovery: hover the badge for the specific reason, then open the plugin's own settings page and reconnect (re-enter credentials, or re-authenticate). See "Needs attention" on a shipping plugin.

Rate Calculator shows a warning instead of a price

What it means: "No carrier connected — manual fulfilment required" means no shipping provider actually answered this query — either none is connected, or the connected one couldn't verify this pincode right now. Any cost shown alongside it is your store's default fallback rate, not a carrier-verified quote.

Recovery: if the cause is "no provider configured," click Connect a provider in the result card. If the cause is a temporary provider check failure, try again shortly — the button doesn't appear in that case since a provider is already connected. See the full explanation under Rate Calculator.

The Action Required section on Shipment Overview didn't disappear after I acknowledged everything

What it means: Acknowledge and Snooze only hide a card from that widget's display — they never resolve the underlying failure, so it's still counted by the site-wide banner and the notification bell. If every card currently shown gets acknowledged/snoozed, the section stays visible with a caption ("N unresolved (M acknowledged/snoozed)...") instead of vanishing, so you're never left thinking a still-open failure was resolved just because its card went quiet.

Recovery: nothing to fix — this is expected. The section only disappears once there are genuinely zero unresolved failures. See Acknowledging the last card doesn't make the section vanish.

A shipping rule's condition shows "No condition (always applies)"

What it means: the rule was created (or edited) without a fully-filled-in condition. It's not an error state — the rule's action simply fires unconditionally for its rule type.

Recovery: if that's not what you intended, edit the rule and fill in a condition field, operator, and value.

No courier options in the Create Shipment dialog

What it means: the serviceability check returned no couriers for the destination pincode.

Recovery:

1. Verify the origin warehouse pincode under Shipment → Warehouses.
2. Check your Shiprocket wallet has a positive balance.
3. Test a known-serviceable pincode (e.g. 400001 or 110001) in the Rate Calculator to confirm the connection is alive.
4. If it's only one pincode, check the Rate Calculator — if "Not serviceable" appears there too, that pincode is genuinely outside your courier network.
5. If intermittent, it may be a transient API outage — try again shortly.

How do I fix an order with no shipping address?

What it means: a shipment can't be booked at all without a delivery address. This most often surfaces as a booking-failure alert on the order citing a missing address.

Recovery: open the order and use the Add shipping address action shown next to the customer's details (or in the shipment panel) — fill in address line 1, city, state, and postal code, then save. The order becomes eligible for booking immediately. See the full walkthrough at Adding a shipping address when the order has none.

Shipment cancelled but stock not restored

What it means: a shipment was cancelled but the product variant stock didn't go back up.

Recovery: this happens when you cancel at the shipment level only, not at the order level. Cancel from the Order Detail page instead — it triggers the full cascade (stock restore + refund + order status update). If you already cancelled from All Shipments, manually adjust stock under Products → edit the variant → update the stock count.

Manifest shows empty or zero shipments

Recovery:

1. Confirm the AWB numbers you entered belong to confirmed (not pending or cancelled) shipments.
2. Delhivery AWBs can't be included in a Shiprocket manifest.
3. If the AWBs are correct but the manifest is still empty, the shipments may not be registered in Shiprocket's system yet — wait 5 minutes and try again.

Label download fails (error page or blank PDF)

Recovery: try again in a few minutes — most often a transient Shiprocket API error. If it persists, check status.shiprocket.in for ongoing incidents, or as a last resort log in directly to Shiprocket and download the label by AWB from there.

Bulk cancel — partial failure

Recovery: the bulk cancel results screen lists every shipment and its outcome. For failures (typically already picked up or in transit), contact Shiprocket to intercept the parcel, then manually restore stock and initiate any refunds from the order detail screen.

Cancel rejected — parcel already picked up

Recovery:

1. Contact Shiprocket support with the AWB and ask them to intercept the parcel at the nearest sorting hub.
2. Once confirmed, the parcel is returned to your warehouse.
3. You can still cancel the BillionBiz order record manually from Order Detail — status updates, inventory restores, and the refund is initiated even though the physical cancellation is handled directly with Shiprocket.

Payment captured but order not confirmed

What it means: Razorpay captured the payment but BillionBiz didn't receive the webhook confirmation, leaving the order in "Payment Pending".

Recovery: go to Orders, find the order, and click Verify Payment — this re-checks with Razorpay. If confirmed, the order updates immediately and shipping can proceed. If the payment genuinely wasn't captured, the order stays pending and the customer needs to pay again.

COD return — no payment to refund

Recovery: there's no Razorpay transaction to reverse for a COD order. Refund the customer directly — bank transfer, store credit, or cash in person. BillionBiz restores inventory automatically when you approve the return; record the monetary refund in your own accounts.

Return request outside the return window

Recovery: to make an exception, go to Shipment → Returns → + New Return to create the return manually — manual returns bypass the window check.

"Unknown" city in checkout address

What it means: the pincode lookup didn't return a city name.

Recovery: the platform now leaves the city field blank in this case rather than showing "Unknown" — the customer types it manually. Couriers use the full address, not just the city field, so delivery isn't affected.

Customers don't see a pickup option at checkout

Recovery:

1. Confirm Enable store pickup is on under Settings → Fulfillment, and that you clicked Save after turning it on — the toggle does nothing until saved.
2. Confirm at least one pickup location exists and its row-level Active switch is on — a disabled location doesn't count even with the master toggle on.
3. If both are correct and the option still doesn't appear, hard-refresh the storefront — pickup availability is checked once per session.

See Customer Pickup & Gift Wrap for the full setup walkthrough.

Customers don't see the gift-wrap option, or the gift-message box is missing

Recovery: under Settings → Fulfillment, confirm Enable gift wrap is on and saved. If the toggle shows but the message box doesn't appear once a customer turns gift wrap on, Allow gift message is off — it's a separate toggle from gift wrap itself.

Frequently asked questions

Do I need a Shiprocket account? Yes — BillionBiz connects to your Shiprocket account to access the courier network. Create one at shiprocket.in; you can start with their free tier.

Can I use my own courier without Shiprocket? BillionBiz currently supports Shiprocket and Delhivery. Through Shiprocket you already reach Blue Dart, DTDC, Amazon Logistics, Xpressbees, and many others.

What does a shipment cost? Cost depends on origin/destination pincode, weight, dimensions, courier, and payment mode. Use the Rate Calculator for real-time rates before booking.

Can I offer free shipping? Yes — create a Free Shipping rule based on cart total, cart weight, payment method, pincode, or zone.

What happens if the customer's pincode isn't serviceable? The customer is told at checkout, before payment. The order isn't created — no risk of paying for an undeliverable order.

Can I cancel a shipment? Yes, as long as the parcel hasn't been picked up. Go to All Shipments, find it, and click Cancel — your Shiprocket wallet is refunded the label cost. If already picked up, contact Shiprocket to arrange an interception.

How do I reprint a label? Shipment → All Shipments → action menu → Download Label — labels can be reprinted as many times as needed.

How do I handle a damaged product claim? Shipment → Insurance Claims → + New Claim — attach photos and a description; it's tracked through resolution.

What if the courier measures a different weight than I declared? Check Shipment → Weight Disputes — review each discrepancy and contest it if the courier's measurement is wrong.

Can my vendors ship from their own Shiprocket accounts? Yes — in a marketplace setup, each vendor connects their own credentials from their Vendor Dashboard, and their shipments book under their own account and wallet.

What is a manifest and do I need one? A printed list of all parcels being handed over at a single pickup — many courier agents require a signed one before accepting packages. Generate it from Shipment → Pickup Management → Manifests.

When does auto-fulfillment not fire? When your Shiprocket wallet balance is too low, the delivery pincode isn't serviceable, the product has no warehouse assigned, or the order is on hold. You'll see a notification for any order it couldn't process.

How long does a COD refund take? BillionBiz never held the customer's money for a COD order — Shiprocket collected the cash on your behalf, so the refund is a direct transaction between you and the customer. Inventory restores automatically when you approve the return.

Can a customer choose pickup and still pay online? Yes — pickup only replaces shipping and its cost, not the payment method. Customers on a pickup order still choose between online payment and Cash on Delivery, if you offer COD.

Can I charge different gift-wrap fees for different products or order sizes? No — the gift-wrap fee under Settings → Fulfillment is a single flat amount store-wide, charged once per order when the customer selects gift wrap, regardless of what's in the cart.

Quick reference — screen index

See also

• Glossary of shipping terms