A correct Now Shipping integration is more than just working API calls — it is resilient to network blips, protected against key exposure, and easy to support when something goes wrong. This guide distils the most important patterns into a concrete checklist and a set of do’s and don’ts your team can review before go-live and revisit during incident triage.
Integration checklist
Work through every item below before pointing your integration at the production environment. Each checkbox corresponds to a real failure mode seen in integrations that skipped it.
Do’s
Call GET /delivery-zones before building any address form. Populate your zone picker directly from the catalog so users can only select valid values. Hard-coding zone strings leads to silent rejections on order creation.
Use externalMerchantId as X-Merchant-Id if it is easier for your system. You do not need to look up the businessAccountCode on every request — just pass the same shop ID you used at onboarding.
Handle merchant re-onboarding idempotently. If your platform retries onboarding (for example, after a timeout), the API may return 409 MERCHANT_ALREADY_EXISTS. Catch this response and fetch the existing merchant via GET /merchants?search=<email or externalMerchantId> instead of treating the conflict as an error.
Use GET /ping for health checks and API key validation. This endpoint requires no scope, returns your account identity and active scopes, and costs nothing — make it your first call in monitoring scripts and integration pre-flight checks.
Don’ts
Do NOT send orderFees, pickupFees, fee, shippingFee, or any fee field in create or update requests. All fees are computed server-side. Sending a fee field does not guarantee that fee will be applied — the server ignores it and computes its own value. Rely on the orderFees and pickupFees fields in the response for the authoritative amounts.
Do NOT use free-text zone names. Strings like "Nasr City" or "القاهرة" are not valid zone values. Always use the exact value string from GET /delivery-zones (for example, "Nasr City - ElHay 06 (Nasr City)"). Invalid zones return 400 VALIDATION_ERROR.
Do NOT share API keys between environments. Use a dedicated key for staging and a separate key for production. This prevents test orders from appearing in your live account and makes it straightforward to rotate a key without disrupting the other environment.
Do NOT store your raw API key in client-side code or mobile apps. API keys are shown only once at creation and cannot be recovered from the Now Shipping database. Any exposure requires an immediate key rotation. All API calls must originate from your server.
Handling common errors
Use the table below as a quick-reference during development and incident response. Log both error.code and error.message from every error response — they are the fastest path to diagnosis.
Your Now Shipping account manager is your primary point of contact for anything that cannot be resolved through this documentation. Reach out for:
- API key provisioning and rotation — request new keys or revoke compromised ones
- Company account setup — enable the multi-tenant company flag on your account
- Custom pricing configuration — negotiate per-merchant or volume-based shipping rates
- Higher rate limits — request an increased cap beyond the default 120 requests per minute
- Integration troubleshooting — share your
error.code, error.message, and request timestamps to speed up diagnosis
