Parcel creation errors and how to fix them

What it means#

When you save a new parcel, from the New parcel page, the API or an Excel import, the server runs a series of checks first. If one fails, no parcel is created and nothing is charged, and a message explains why. On the New parcel page the reasons appear in a list under "The parcel was not saved because:"; a list headed "Parcel not saved, missing:" names empty required fields.

Who is affected#

Merchants, in the panel or through their API key. The API is for platform merchants only: a merchant created by a delivery company is refused with api_not_allowed (HTTP 403) before the plan and parcel checks. A platform merchant needs an active merchant-plan subscription (when merchant plans are active); a merchant created by a delivery company depends on that company's subscription. With plans active, Excel import and the API also need the plan's import and api features, or the request is refused before any parcel check (API: plan_feature, HTTP 403).

Likely causes#

The checks run in this order and stop at the first failure: form fields, plan, plan parcel limit, delivery company, pickup location (for a warehouse location, also the products to send), coverage, company limits, carrier enabled, price calculation (or the carrier's quote), then balance. The exception is the field rules, whose errors are reported together.

Required fields and their format

The first five rows are New parcel page messages. The API and Excel import return standard validation text only for the recipient name, phone and address; they do not require a pickup location (your default one is used) or a delivery type.

Plan, company and pickup location

• "The merchant subscription to a merchant plan has expired or does not exist ...". A merchant of a delivery company sees "The subscription of the merchant company has expired ..." instead.
• "You have reached your plan limit: N parcels during the subscription period (until DATE), and you used M. ..." This message appears only if the plan sets a maximum parcel count.
• "The selected delivery company is not available to you": the company is not offered to your account.
• "The selected pickup location does not belong to you", or "You have no registered pickup location — add a pickup location (branch) from the Stores/Branches page first". The message says Stores/Branches, but the page is called Pickup locations, under Settings in the side menu.

Coverage, company limits and carrier

• Coverage rejection: "“X” doesn't deliver to GOVERNORATE (Recipient). Supported governorates: ..." Governorate names appear in Arabic; see the linked article.
• "“X” accepts parcels up to N kg — this parcel is W kg." or "“X” accepts amounts in: ... — change the parcel currency."
• "Shipping company X is not currently enabled". It appears as an error pop-up, not in the list.

Price calculation

• "The delivery company prices by governorate: we could not determine the recipient governorate from the address ... — choose the governorate from the list."
• "Delivery company “X” has not set a price for governorate ... — set it from the “Delivery pricing” page or choose another company." The company has no price for that governorate, so it does not deliver there.
• "The delivery company prices by distance, and the pickup location ... has no location on the map ...", or "The delivery company prices by distance: set the recipient location on the map." One of the two points is missing on the map.
• With an external carrier, a failed quote shows the carrier's own error text (or "Could not calculate the shipping price"). It appears as an error pop-up.

Balance

• "Insufficient wallet balance. Required: 12.50, available: 3.00". The required amount is compared with your Shipping balance (recharge); both amounts are in US dollars, the ledger currency. It appears as a pop-up titled "Error".
• A merchant of a delivery company paying from the wallet kept with that company sees "Your balance with (company name) is not enough ...": ask the company to top up.
• Store orders and API requests with wait_for_balance=true are not rejected for a short balance: they are saved as "awaiting balance", completed automatically once the balance allows (checked hourly), and cancelled after 24 hours.

How to diagnose#

• Read every item in the list; each names the failed field or rule. Balance and carrier errors come as pop-ups.
• The price box on the New parcel page shows coverage, weight, currency and pricing problems before you save. It runs the coverage check, the company's weight and currency limits and the carrier-enabled check, then the price calculation (or the carrier's quote for an external carrier), and shows any error from those steps. It does not check the plan, whether the delivery company is available to you, whether the pickup location is yours, or the balance; those appear only on save.
• The API returns success: false and error.code: validation_failed (HTTP 422, fields in error.fields; plan errors are under the field plan), insufficient_balance (402) and carrier_error (422, including a disabled carrier or a failed carrier quote).
• In an Excel import the results table lists each row separately; several messages for one row are joined with " — ". Limits: 300 rows and 5 MB.

Resolution steps#

1. Fix every reason shown

   Correct each item and save again. A different message means the earlier check passed and the next one failed.

2. Complete the fields and correct their values

   Choose the pickup location, delivery company and delivery type (the API and Excel import need only the delivery company), enter the recipient's name and phone in an accepted format (such as 09xxxxxxxx), and set the address from the map.

3. Deal with a coverage rejection

   Choose the governorate explicitly, or pick a company that covers your destination. Only the platform administrator (super admin) can edit coverage areas, so ask them to change it.

4. Fix a price calculation message

   For a message about the governorate, choose the governorate explicitly or pick another company. For a message about a location on the map, set the recipient's location on the map and give your pickup location a location on the map from the Pickup locations page.

5. Top up the wallet

   Open My wallet in the side menu, or use the Top up link beside your balance under the parcel summary. The summary row "Deducted from your balance now" is the amount needed. Then save again.

6. Renew or upgrade the plan

   For a plan message, renew or upgrade from the subscription page. A merchant of a delivery company asks that company to renew.

12345

1. Choose the pickup place
2. Choose the delivery company
3. Enter the recipient's name and phone
4. Set the cash-on-delivery amount
5. Your invoice number, to recognise the parcel later

1234

1. Download the file template first
2. Drop the filled file here
3. Choose the pickup place
4. Start the import

When to contact support#

• You see "Something went wrong.", a generic message for unexpected errors, logged on the server. Send the time and the delivery company.
• Your balance differs from the "available" figure in the message: see the linked article on wallet discrepancies.
• An external carrier rejected the parcel. The carrier's own error text is shown as received (it differs per carrier); "Failed to create shipment at the shipping company" appears only when the carrier returned no text. In both cases the charge is reversed and the parcel deleted. Send the full message.