Help

Magento

This guide covers what ParcelPilot needs to connect to Magento (Magento 2), where to find it, and where to enter it in ParcelPilot.

What ParcelPilot needs

Base URL (your Magento store URL)
Access Token (Magento integration token)
Store Code (optional; for multi-store setups)
Optional tuning:
- Page Size (pagination size for imports)
- Timeout (API timeout)

Where to find it in Magento

Magento Admin → System → Extensions → Integrations (menu names vary slightly by version).

Create an integration

Click Add New Integration
Enter a name like ParcelPilot
On the API tab, select the resources/permissions required
- For import-only: read access to orders/products/customers as needed
- For pushing shipment tracking back: permissions to create shipments / update orders (Magento-specific)
Save the integration

Activate and get the access token

Back on the Integrations list, click Activate for the ParcelPilot integration
Approve the requested access
Magento will show an Access Token (copy it)

Important: store this token securely.

Store code (optional)

If your Magento has multiple store views, you may need a store code.

Common places to find it:

Magento Admin → Stores → Settings → All Stores (store view code)
Or your storefront URLs if they include a code segment

Where to enter it in ParcelPilot

ParcelPilot Admin → Integrations → Client Integrations → create/edit an integration with Platform = Magento.

Fill these fields:

Base URL → credentials.magento.base_url (e.g. https://store.example.com)
Access Token → credentials.magento.access_token
Store Code (optional) → credentials.magento.store_code

Optional tuning:

Page Size → credentials.magento.page_size (default 100)
Timeout (seconds) → credentials.magento.timeout (default 20)

Operational settings:

Push shipment confirmations (tracking) back to ecommerce platform → settings.push_ship_confirms

Product Data / Units

Magento now uses the shared Product Data / Units section for dimension handling.

Auto-detect or use store default preserves the existing Magento behavior. ParcelPilot uses the legacy Magento dimension-unit setting when present and otherwise falls back to Magento's default import path.
Fixed override stores a shared dimension-unit override at settings.product_units.dimension_mode = fixed and settings.product_units.dimension_unit.

Magento product weight handling does not currently require a separate integration-level unit override because Magento weights are already treated on the importer's existing canonical path.

Product Data Mapping

Magento integrations can use Product Data Mapping to fill missing ParcelPilot Item product/customs fields from retained Magento product data.

Phase 1 behavior:

Mapping is scoped to this Client Integration only.
Mapping is fill-missing only; manual and Item CSV-maintained Item values are protected.
Supported source paths are retained Magento product properties and custom_attributes.<attribute_code> values.
Supported targets include Manufacturer Product ID, Manufacturer, Standard Product ID, Standard Product ID Type, HS Code, Country of Manufacture, and Customs Description.
Numeric Magento manufacturer option IDs are not treated as manufacturer names. Use a text attribute such as manufacturer_name if that is the intended source.
Provenance is recorded on the Item only when the mapping writes a value.

If Product Data Mapping is not enabled/configured, Magento keeps the legacy protected behavior for hs_code and country_of_manufacture. If explicit mapping rules are configured, those rules supersede the legacy assumptions.

On an individual Magento Item, Refresh from Magento normally keeps the same protected fill-missing behavior for existing ParcelPilot product/customs data. The optional Overwrite existing product data checkbox is a one-off refresh option for safe product/customs fields only: Manufacturer Product ID, Manufacturer, Standard Product ID, Standard Product ID Type, HS Code, Country of Manufacture, and Customs Description. Blank, missing, or invalid Magento values do not clear ParcelPilot values. Stock, inventory, allocations, reservations, locations, bundles/recipes, dimensions, weight, and other operational Item data are not affected by this checkbox.

The image options in the same modal are separate. Download images and Refresh existing images control image downloading only; they do not control product/customs overwrite behavior.

The Refresh product data sources action reads source fields from Magento product payloads already retained on ParcelPilot Items. It does not call Magento or change upstream data.

Super-admin targeted SKU check

On the Client Integration edit page, super admins have a Check SKU tool for Magento.

Use it when you need to inspect one upstream Magento product by SKU and, when valid, import that exact item immediately.

Current behavior:

the modal keeps the lookup result visible instead of relying on a transient notification
Parcel Pilot checks the Magento product status and current import-rule eligibility, including disabled-product and simple-product restrictions configured on the integration
if the SKU already maps to a Parcel Pilot item, the modal reports that the existing item can be refreshed safely
if the product is valid, Import Item imports the exact checked Magento product using the checked Magento product ID rather than re-running an unchecked SKU lookup

Notes:

this tool is super-admin-only
existing Magento collision and importer protection rules still apply during import
if the upstream product changes between check and import, Parcel Pilot rejects the import and asks the operator to run Check SKU again
the import writes the canonical integration-scoped Magento mapping and legacy compatibility identity together; identity disagreements or an uncorroborated SKU rename are skipped for review rather than automatically reassigned

For product identity repair, start with the read-only products:audit-sync-risks audit and a dry-run of the explicitly scoped compatibility backfill. Alternate Magento product IDs on one ParcelPilot Item require manual review; do not resolve them by applying a broad backfill. The backfill changes only ParcelPilot database identity rows and does not call Magento.

Troubleshooting

401 Unauthorized

Ensure the integration is activated.
Regenerate the token (deactivate/reactivate) if needed.

Base URL issues

Use the storefront base URL (not the admin URL).
Ensure HTTPS is correct and the site is reachable from the ParcelPilot server.

Missing orders?

If orders are missing in ParcelPilot, you can manually backfill using Pull Orders on the integration:

Pull Orders from eCommerce (manual backfill)

Security notes

Treat the access token like a password.
Rotate tokens if exposed.