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.

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.

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