FedEx Shipping for US to US and US to Canada

FedEx Botble eCommerce / Marketplace. Routes: US -> US domestic and US -> Canada cross-border. warehouse pickup and custom pricing rules. OAuth2 + Rates + Ship + Track + public tracking page. email notifications.

FedEx Shipping Plugin for Botble / Martfury

Plugin ID: maryam/fedex · Namespace: Maryam\FedEx\ · Install path: platform/plugins/Fedex/

FedEx REST API integration for Botble eCommerce with Martfury Marketplace support. One admin-managed FedEx account serves every vendor; each vendor configures their own warehouse pickup address and custom pricing rules. This plugin is completely independent of the DPD plugin — install one or the other or both; they share no code and no tables.

Supported Routes

OriginDestinationType

US

US

Domestic

US

CA

International

Any other pair is hidden at checkout and blocked server-side with a clear error message.

FeaturesBackend / API

• OAuth2 client-credentials auth (auto-refresh, cached)
• Rate API at checkout (real-time pricing, currency-converted to storefront currency)
• Ship API for label creation (PDF base64 stored locally — no FedEx login needed to print)
• Track API with status mapping (IN, PU, IT, OD, DL, DE, RS → human labels)
• Pickup API (sandbox limitation, works in live)
• Cancel Shipment API
• Postcode validator helper
• US state-name → 2-letter normalizer
• HS-code injection on product edit
• Customs / commercial-invoice builder for US → CA
• Full request/response logging under the [FEDEX] prefix

Admin

• One-click Sandbox ↔ Live toggle (no code change to go live)
• Settings page with: API keys, account number, origin address, default service, weight/dimension units, label format
• Test Connection presets (4 lanes — US→US ground, US→US overnight, US→CA Toronto, US→CA Vancouver)
• Shipments dashboard with filters, status cards, refresh, cancel, label print, schedule pickup, external sandbox/live tracking link
• 10 toggleable email-notification events (5 customer + 5 vendor)
• FedEx card on Botble's "Shipping Methods" page
• Tax-ID card (US EIN + Canadian importer fields)

Vendor

• Per-vendor warehouse pickup form
• Vendor shipments list with label-print + tracking
• Custom pricing rules

Customer

• FedEx services appear at checkout with live rates
• Order-confirmation email with tracking number
• Customer dashboard "Track Order" → public tracking page with scan history
• Auto-emails on shipped / out-for-delivery / delivered / exception / returned

Sandbox vs Live — what to expect

FeatureSandboxLive

OAuth + Rates + Ship + Cancel + Track APIs

✅ works

✅ works

Real scan events (after parcel ships)

❌ blank page

✅ updates live

FEDEX_GROUND service

⚠️ many test accounts get GROUND.SHIPPING.NOTAUTHORIZED

✅ requires Ground service contracted on the account

FEDEX_HOME_DELIVERY (residential)

⚠️ usually disabled

✅ enabled on most US accounts

INTERNATIONAL_PRIORITY US → CA

✅ works

✅ works

Schedule Pickup

❌ FedEx returns FORBIDDEN

✅ works

Production label barcodes

n/a

✅ scannable by real FedEx drivers

Important — Sandbox does NOT simulate real shipments

The FedEx sandbox environment is an API simulator, not a logistics simulator. When the plugin calls /ship/v1/shipments in sandbox, FedEx really does:

• Allocate a real-format tracking number (e.g. 794809048522)
• Generate a printable PDF label with a valid barcode
• Persist the shipment record in the FedEx sandbox database

But FedEx does NOT:

• Pick up the parcel
• Move it through the network
• Generate scan events (Picked Up / In Transit / Out for Delivery / Delivered)
• Schedule real pickups (the Pickup API returns FORBIDDEN in sandbox for almost every test account)

This is why the customer-facing tracking page and wwwtest.fedex.com/fedextrackshow a blank "no scans yet" state for sandbox tracking numbers — there are no scans because no real parcel was ever moved. This is normal sandbox behaviour and is not a plugin defect. Every FedEx integrator (Shopify, WooCommerce, Magento, custom) sees exactly the same blank tracking page in sandbox.

On live mode the entire flow works end-to-end: real labels, real pickups, real driver scans, real "Out for Delivery" / "Delivered" status updates pulled automatically into the customer dashboard, and real branded tracking pages on fedex.com.

Going live — exact checklist

1. FedEx Developer Portal → Move project to Production
2. Copy production clientId + clientSecret + accountNumber
3. Admin → FedEx Settings → switch Mode to live and paste the 3 production values
4. Save → click Test Connection → green banner = done
5. Place a small real order to yourself to validate the first live shipment

No code changes are required to go live — every environment-specific value lives in settings.

InstallationOption A — Zero CLI (shared hosting)

1. Upload the Fedex/ folder to platform/plugins/Fedex/.
2. In Botble admin go to Platform → Plugins and activate FedEx Shipping. Migrations run automatically during activation.
3. Open FedEx Shipping → Settings, enter your credentials, click Test FedEx Connection.

Option B — CLI

cp -R Fedex <martfury-root>/platform/plugins/Fedex cd <martfury-root> php artisan plugin:activate Fedex php artisan cache:clear

If the vendor dashboard ever shows a "FedEx warehouse storage is not ready" notice, the controllers will retry php artisan migrate --path=platform/plugins/Fedex/database/migrationsautomatically on the next page view.

Database tables

maryam_fedex_shipments            ← one row per FedEx shipment maryam_fedex_tracking_events      ← scan events from the Track API maryam_fedex_notifications_log    ← audit log of every email sent maryam_fedex_vendor_warehouses    ← per-vendor pickup addresses maryam_fedex_shipping             ← (placeholder for vendor rule groups) maryam_fedex_shipping_rules       ← custom per-vendor rate bands maryam_fedex_shipping_rule_items  ← city/state/postcode adjustments

Troubleshooting

SymptomLikely causeFix

AUTH.CREDENTIALS.INVALID

Wrong Client ID or Secret

Verify at https://developer.fedex.com → My Projects

FedEx hidden at checkout

Route not supported

Only US → US and US → CA are allowed

INVALID.INPUT.EXCEPTION on shipment

Missing state/province for US or CA

Fill state_province in the vendor warehouse form

Customs error on UK → US

Missing customsClearanceDetail

Ensure products have weight, price and description

Rate call returns empty services

Wrong serviceType or address

Enable API logging and check the raw response

Label URL returns 404

URL expired

Refresh tracking and download again

Dashboard shows 0 shipments after order

Auto-create failed

Grep storage/logs/laravel.log for [FEDEX] Auto-create

License & Support

Premium plugin by Maryam International LLC · codeupp.xyz

Purchase includes lifetime updates, 6 months of priority support, installation help on WhatsApp, and compatibility across Martfury, Shofy, Nest and future Botble releases.