Magento 2 + AtoShip
Pull orders from your Magento 2 store into atoship, buy discounted USPS / UPS / FedEx labels, and push tracking numbers back — with a rich tracking panel right inside your Magento admin.
How it works
The integration has two parts: a Magento 2 extension that adds tracking display and webhook processing to your store, and an OAuth connection from your atoship dashboard that syncs orders and writes back tracking data automatically.
New orders appear in Magento
Customer places an order on your store
Orders sync to atoship
Auto-imported with customer info, items, weights
Buy label, tracking goes back
Tracking number + carrier + progress written to Magento order
Installation
Step 1 — Install the Magento extension
Download the atoship-for-magento.zip file from the sidebar (or the button below). Extract it to your Magento installation:
Option A: Copy to app/code (recommended)
# Extract and copy to your Magento root
unzip atoship-for-magento.zip
cp -r atoship-shipping/ <magento-root>/app/code/Atoship/Shipping/
# Enable the module
cd <magento-root>
php bin/magento module:enable Atoship_Shipping
php bin/magento setup:upgrade
php bin/magento cache:flushAfter running setup:upgrade, the module creates the atoship_tracking table and registers webhook routes automatically.
Step 2 — Connect via OAuth Integration
In your Magento admin, go to System → Integrations and click Add New Integration. Fill in the following:
https://atoship.com/api/channels/magento/callbackhttps://atoship.com/api/channels/magento/identity
Fill in the Name, Callback URL, and Identity Link URL. The Email field is optional.
Step 3 — Set API permissions
Click the API tab on the left. Under "Resource Access", either select All or grant access to these specific resources:
- Sales — Orders, invoices, shipments, credit memos
- Catalog — Products (for weights & dimensions)
- Stores — Store configuration & views
Tip: "All" is the simplest option and ensures all sync features work. You can restrict it later if needed.
Step 4 — Save and Activate
Click Save to create the Integration. Then find it in the list and click the Activate link. Magento will ask you to confirm — click Allow.
Click the Activate link next to the atoship integration to start the OAuth handshake.
Important: Make sure you're logged into your atoship account in the same browser before clicking Activate. Magento redirects your browser to atoship's Identity Link URL, and atoship needs your session to associate the store with your account.
Step 5 — Configure the extension
Go to Stores → Configuration → Sales → AtoShip and enter your webhook secret (found on your atoship Channels page). Configure notification and auto-complete preferences.
The atoship integration appears as Active in Magento's System → Integrations list.
Extension settings
All settings live under Stores → Configuration → Sales → AtoShip. Here's what each option does:
General
- Enable — Master switch for the extension. When disabled, webhooks are ignored and tracking panels are hidden.
- Webhook Secret — HMAC-SHA256 secret for verifying incoming webhooks from atoship. Copy this from your atoship Channels page.
- Debug Logging — Writes detailed logs to
var/log/atoship.log. Keep off in production.
Tracking
- Auto Complete on Delivery — Automatically marks orders as "Complete" when carrier tracking confirms delivery.
- Notify Customer on Ship — Sends a shipment notification email with tracking link when a label is purchased.
- Notify Customer on Delivery — Sends a delivery confirmation email when the package is delivered.
What gets synced
Magento → atoship
- Order number, date, total
- Billing & shipping addresses
- Line items with SKU, quantity, weight
- Customer name & email
- Order status & payment info
atoship → Magento
- Tracking number & carrier + service name
- Visual progress stepper (Label Created → Picked Up → In Transit → Delivered)
- Full tracking timeline with events & locations
- Label cost & label PDF link
- Shipment creation on the order
- Order status updates (→ Complete)
- Delivery & exception notifications
Tracking data is stored in the atoship_tracking table and displayed in a rich tracking panel on both admin order view and shipment view pages — no additional tracking extension required.
Order tracking panel
When a label is purchased in atoship, the extension adds a rich AtoShip Tracking panel to both the admin order detail page and the shipment detail page. Customers also see tracking progress on their My Account order view.
Carrier & service
Shows the real carrier logo (FedEx, UPS, USPS, DHL), carrier name, and service level (Ground, Priority, Express).
Progress stepper
Visual 4-step indicator: Label Created → Picked Up → In Transit → Delivered. Updates automatically as tracking status changes.
Tracking timeline
Collapsible event-by-event timeline with timestamps and locations, ordered newest-first.
Quick actions
Track on atoship tracking page, view on carrier's official site, label cost display (admin only).
The tracking number links to the atoship tracking page for a detailed view. Tracking data is pushed via webhook in real time.
Webhook events
The extension receives webhook events from atoship at /atoship/webhook/receive. All requests are verified with HMAC-SHA256 signature using your webhook secret.
| Event | Action |
|---|---|
label.created | Saves tracking record, adds admin order comment |
label.purchased | Saves tracking, moves order to Processing, notifies customer |
label.voided | Marks tracking as voided, adds admin comment |
tracking.updated | Updates status, events timeline, adds customer-visible comment |
tracking.delivered | Marks delivered, auto-completes order (if enabled), notifies customer |
tracking.exception | Logs warning, adds admin-only alert comment |
Alternative: Manual token entry
If you've already created an Integration and have the 4 API tokens (Consumer Key, Consumer Secret, Access Token, Access Token Secret), you can enter them directly:
- Go to atoship → Channels → Add Channel → Magento
- Switch to the Manual Tokens tab
- Enter your store URL and all 4 tokens
- Click Connect
This is useful if your Magento store can't reach the internet (e.g., staging environments behind a firewall) or if you prefer to manage tokens manually.
Disconnecting
You can disconnect from either side:
- From atoship: Go to Channels, find your Magento store, and click Disconnect.
- From Magento: Go to System → Integrations, find "AtoShip", and click Delete or Reset.
Disconnecting does not delete any orders, shipments, or tracking data already in your store. It only stops future sync. The extension can be uninstalled separately via module:disable Atoship_Shipping.
Troubleshooting
"State not found or expired" error
The OAuth handshake must complete within 10 minutes. If you took too long between Save and Activate, delete the Integration in Magento and create a new one.
Redirect goes to login page
You need to be logged into atoship in the same browser before clicking Activate in Magento. Log in to atoship first, then try Activate again (you may need to recreate the Integration).
Tracking panel not showing
Make sure the extension is enabled (php bin/magento module:status | grep Atoship) and the "Enable" setting is set to Yes in Stores → Configuration → Sales → AtoShip. Run cache:flush after any config changes.
Webhook events not received
Verify the webhook secret matches between atoship and your Magento config. Checkvar/log/atoship.log (enable Debug Logging) for signature verification failures. Your store must be accessible from the internet.
Orders not importing
Verify the store shows as "Active" on your Channels page. Check that the Integration has the required API permissions (Sales, Catalog, Stores). Order sync runs on a schedule — newly placed orders may take a few minutes to appear.
Requirements
- Magento 2.4+ (Open Source or Commerce)
- PHP 8.1+
- REST API enabled (default)
- HTTPS required
- Admin access to create Integrations and install extensions
app/code/Atoship/Shipping/.Callback URL
https://atoship.com/api/channels/magento/callbackIdentity Link URL
https://atoship.com/api/channels/magento/identity