Foxpost

Foxpost connects yStore to the Foxpost parcel locker and courier network (Hungary). It registers Foxpost as a selectable shipping method in checkout, lets customers pick a parcel locker (APM) or confirm home delivery, and on the admin side creates shipments, generates labels, tracks parcel status, and handles Foxpost's return flows.

What it does

• Adds Foxpost as a selectable shipping method in checkout, with a live map/ list widget for choosing a parcel locker (APM) or home delivery address.
• Creates a shipment with Foxpost for an order -- manually from the order edit page, or automatically once the order changes status, if auto-sync is enabled.
• Generates and stores shipping labels (PDF or ZPL), including bulk label and delivery-note downloads for multiple shipments at once.
• Polls Foxpost for tracking updates and shows a tracking timeline per shipment; a console command can refresh all shipments on a schedule.
• Creates Foxpost returns for an order directly from the order edit page (RE/EXT, XRE/unique, or C2B parcel), and lets the return label be downloaded.
• Maintains a Foxpost account address book (sender/return/pickup addresses) synced with the addresses stored in the Foxpost account.

How it works

1. Checkout. If Foxpost is enabled as a shipping method, it appears alongside the store's other shipping options. Selecting it shows a locker picker: either the vendor's own map widget (cdn.foxpost.hu iframe) or, as a fallback/alternative, an in-page list of nearby parcel machines (APMs) with load state (normal/medium/overloaded), indoor/outdoor, opening hours, payment options, and a link to the machine on Google Maps. Picking a machine stores its address and machine ID against the order.
2. Order fulfilment. Once an order is ready to ship, a shipment can be created for it. This can happen:
   • manually, from the order edit page (a "manage shipment" panel appears for eligible orders), or
   • automatically, when the order's status changes, if Auto-sync shipments is enabled in settings (see Settings).
3. Labels and tracking. After a shipment is created, Foxpost issues a shipping label. The Shipments admin page lists every shipment with its barcode, status, linked order, and a tracking timeline built from Foxpost's status updates. Labels can be downloaded per-shipment (PDF or ZPL) or in bulk for several shipments, along with a combined delivery note. Tracking can be refreshed on demand from the admin, or in bulk via the foxpost/shipments/update-statuses console command.
4. Returns. From an order's edit page, an admin can create a Foxpost return without leaving the order: return the original Foxpost shipment (RE/EXT), register a return for a shipment that didn't originate with Foxpost (XRE/unique), or create a C2B parcel for a customer who ships the parcel back through an APT themselves. Each created return exposes a downloadable return label once Foxpost issues one.

Example 1: automatic shipment creation with parcel locker checkout

A store lets customers pick a Foxpost locker at checkout and wants labels created without manual admin work:

1. In the plugin settings, fill in the API tab (production API key, username, password) and the sender address on the Shipping tab, or select a Foxpost Account Address to reuse an address already stored in the Foxpost account.
2. Enable Auto-sync shipments so shipments are created as orders progress, without waiting for a manual "create shipment" click.
3. At checkout, the customer sees the Foxpost map/list widget, picks a nearby parcel locker, and completes the order as usual.
4. As the order reaches the next relevant status, Foxpost creates the shipment and requests the label automatically. The label can be opened, printed, or downloaded as ZPL straight from Foxpost → Shipments.

Example 2: creating a return from the order edit page

A customer wants to send a product back through the same Foxpost locker they received it from:

1. Open the order's edit page in the Craft control panel.
2. Click FoxPost Return and choose Return (RE/EXT) -- this reuses the original Foxpost shipment's barcode automatically if one exists for the order.
3. Foxpost registers the return; once a barcode is issued, a Return label entry appears in the same menu for that return, ready to download and hand or send to the customer.
4. For a parcel that never shipped with Foxpost (e.g. a different carrier or a walk-in return), use Return (XRE/unique) instead, or C2B parcel if the customer will drop the return off at an APT themselves.

Frequently asked questions

What's the difference between the map widget and the list picker? The map widget is Foxpost's own hosted iframe (cdn.foxpost.hu), themeable via the Widget settings tab (theme, language, map height per device). The list picker (foxpost/api/apm) is a lightweight in-page alternative fed from a locally cached machine list, with filtering by load state and payment option -- useful when the iframe isn't desired or as a fallback.

Can more than one return type apply to the same order? Yes. RE/EXT, XRE/unique, and C2B are independent return requests; an order can have several returns of different types, each tracked and downloadable separately from the order edit page.

What happens if label or shipment creation fails? A shipment.failed notification is raised (when auto-sync creates or attempts to create a shipment) so an operator can investigate from the control panel's notification center. The shipment can be retried from the Shipments list or the order edit page.

Is there a sandbox mode? Yes -- enable Sandbox mode on the API settings tab to send API traffic to Foxpost's test environment, so shipments, labels, and tracking can be verified before going live.

Does the plugin keep its own copy of Foxpost account addresses? The Addresses admin page lists, creates, and deletes addresses directly in the connected Foxpost account (not a local-only copy) -- useful for managing which sender/return addresses are available to pick from in settings without needing separate access to the Foxpost merchant portal.

Admin / Craft CP

See Settings for the full configuration reference. Once configured, the plugin adds navigation items under Foxpost in the Craft control panel:

Page	Purpose
Dashboard	Shipment totals and status breakdown at a glance, with a configurable widget layout.
Shipments	Every shipment created with Foxpost: barcode, status, linked order, tracking timeline, label download (PDF/ZPL), bulk label/delivery-note export, and per-shipment refresh/create/delete actions.
Addresses	The Foxpost account's stored addresses -- list, create, and delete, for reuse as a sender or return address in settings.
Settings	API credentials (production and sandbox), sender/return address, shipment defaults, checkout widget appearance, and returns.

An order edit page shows a manage shipment panel (for eligible orders) and, when at least one Foxpost shipment exists or a return type applies, a FoxPost Return action menu for creating and downloading returns without leaving the order.

Developer notes

• Services (available on the plugin instance as Yui\Foxpost\Plugin::getInstance()->...): getShipments(), getLabels(), getTracking(), getReturns(), getAddresses(), getLicense(), getFoxpostClient() (raw API client). Dashboard and APM lookups are reached through their controllers rather than a public plugin getter.
• Order automation. Foxpost listens for yStore's order status change event (OrdersService::EVENT_AFTER_ORDER_STATUS_CHANGE); when Auto-sync shipments is on, it checks shouldSyncOrder() and, if eligible, calls ShipmentService::syncOrder() to create the shipment.
• Notification types. Foxpost registers three notification types with yStore's notification system: shipment.created, shipment.failed, and shipment.status, so shipment events can be routed to admin notification channels like any other store event.
• Site-facing endpoint. foxpost/api/apm (anonymous, GET) returns a JSON array of parcel locker machines from the plugin's local cache, optionally filtered with ?load=NORMAL,MEDIUM and/or ?payment=CARD,CASH. It backs the in-page locker list widget and can be called directly for a custom storefront integration. Admins can force a cache refresh via foxpost/apm/refresh (POST, control-panel only, Craft's default plugin routing -- there is no /api/ prefix on this one).
• Console command. php craft foxpost/shipments/update-statuses [--limit=N] [--onlyWithoutStatus=1] refreshes tracking status for stored shipments, oldest-updated first; it's a no-op (exit 0) if the plugin is disabled. Wire this into a cron schedule to keep tracking current without relying on admin page visits.
• Return types. ReturnService exposes createReturnExt() (return of the original Foxpost shipment, re_ext), createReturnXreUnique() (xre_unique, for a shipment that didn't originate with Foxpost), and createC2bParcel() (c2b, customer drop-off). The order-edit action menu and foxpost/returns/create/<orderId>?type=... route cover the same three types; createReturnExts() (bulk RE/EXT across several barcodes) is only reachable programmatically.
• Data model. Shipments are stored as ShipmentRecord rows (barcode, unique barcode, status, linked order ID, label/tracking payloads); returns as ReturnRecord rows linked to the originating order and, where applicable, the original shipment barcode. Raw request/response payloads are kept on the shipment record for troubleshooting from the shipment detail page.

Requirements

• Craft CMS 5+.
• yui/craft-plugin (yStore) ^2.
• yui/craft-core ^1.
• A Foxpost merchant account with API credentials (production and/or sandbox).