GLS

GLS connects yStore to GLS parcel and express delivery services through GLS's ParcelService API. It registers GLS as a shipping method in checkout, and on the admin side it creates shipments, generates and stores shipping labels, and keeps tracking status in sync for orders fulfilled through the carrier.

What it does

• Adds GLS as a selectable shipping method in checkout, with standard yStore shipping-method behaviour (price, free-shipping threshold, country/weight restrictions, payment-method restriction, visibility window).
• Creates a GLS shipment for an order -- either manually from the order edit page, or automatically once the order reaches a configured status.
• Generates and stores the shipping label for each shipment (PDF or ZPL, depending on the configured format), viewable, downloadable, and printable from the admin.
• Polls GLS for tracking updates and shows a tracking timeline per shipment.
• Exposes GLS shipment operations as MCP tools, so an AI agent connected to the yStore MCP server can create shipments, fetch labels, and check tracking status directly.

How it works

1. Checkout. If GLS is enabled as a shipping method, it appears alongside the store's other shipping options, subject to the usual restrictions (country, weight, payment method, visibility window) configured in Settings.
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 orders that have a shipping weight and haven't hit the label limit), or
   • automatically, when the order transitions into a specific order status chosen in the plugin settings (Sync on order status).
3. Label and tracking. After a shipment is created, GLS's ParcelService API is called to print the label, and the label content is stored as an attachment on the shipment. The Shipments admin page shows every shipment with its parcel number, linked order, current status, and a tracking timeline built from GLS's status history. Tracking can be refreshed on demand, and a shipment can be re-synchronised if something needs to be redone -- this updates the same shipment record in place with a freshly issued parcel number, rather than creating a separate shipment.
4. Scheduled tracking refresh. A Craft schedule task (gls/shipments/update-statuses) runs hourly while the plugin is enabled and refreshes the status of every stored shipment, so the tracking timeline stays current without an admin having to open each shipment.

Example 1: home delivery with automatic label creation

A store ships most GLS orders as a standard parcel and wants labels created without manual admin work:

1. In the plugin settings, fill in the API credentials (client number, username, password) and the pickup address (this is sent as the sender on every label).
2. Set Sync on order status to the order status used once an order is packed and ready to ship (for example "Ready to ship").
3. When an order reaches that status, GLS automatically creates the shipment and requests the label -- no manual step needed. The label can be opened or printed straight from GLS → Shipments.

Example 2: manual shipment creation from the order edit page

A store wants an operator to review each order before a label is generated:

1. Leave Sync on order status unset (disabled).
2. Once an order has a recorded shipping weight, a "manage shipment" panel appears on the order edit page.
3. The operator creates the shipment from that panel; GLS prints and stores the label immediately, up to the configured Maximum shipping labels per order.

Frequently asked questions

Does this replace GLS's own shipping portal (MyGLS)? No. GLS talks to the same ParcelService API that MyGLS uses, so shipments created here appear the same way they would if submitted through GLS directly. You don't need to re-enter shipment data anywhere else.

Can more than one shipment be created for the same order? Only up to the number configured in Maximum shipping labels per order. Once that limit is reached, both the automatic and the manual "create shipment" action are blocked for that order. The count is based on shipments already created for the order, not on stored labels -- deleting a shipment's label (see Labels below) only removes the stored PDF and does not free up a slot. The limit must be raised to create another shipment.

What label formats are supported? The Default label format setting controls what GLS returns (for example A4_2x2 for a 4-label-per-sheet A4 PDF). The Label sheet start position controls which slot on a multi-label sheet the first label is printed into, useful when reusing a partially printed sheet.

Is there a sandbox/test mode? Yes -- enable Sandbox mode to send all API traffic to GLS's test endpoint with separate sandbox credentials, so shipments and labels can be verified before going live. Use Test Credentials on the settings page to check that the configured credentials are accepted by GLS before relying on them at checkout.

What happens if tracking can't be refreshed? The shipment keeps its last known status and stored tracking data. The hourly scheduled refresh and the manual "Refresh tracking" action on the shipment detail page both log failures to the Craft logs without blocking other shipments.

Admin / Craft CP

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

Page	Purpose
Dashboard	Shipment statistics: total shipments, last synchronisation time, and a status breakdown.
Shipments	Every shipment created with GLS: parcel number, linked order, status, tracking timeline, label download, CSV export, and per-shipment refresh/re-sync/delete-label actions.
Labels	A label-focused view of shipments -- filterable by label format, with quick access to view/download each stored label.
Settings	API credentials (production and sandbox), pickup address, default parcel weight and dimensions, label format and print position, label limits, and the auto-sync order status.
License	License activation and redemption for the plugin, shared across yStore's plugin licensing panel.

An order edit page shows a manage shipment panel for orders with a recorded shipping weight, allowing a shipment to be created for that order directly without visiting the Shipments list.

Developer notes

• Services (available on the plugin instance as Plugin::getInstance()->..., via the generated getters getShipments(), getLabels(), getTracking(), getClient(), getApi(), getDashboard(), getLicense()): shipments, labels, tracking, client (GlsClient, the low-level ParcelService API wrapper), api (credential testing), dashboard, license.
• Order automation. GLS listens for yStore's order status change event (OrdersService::EVENT_AFTER_ORDER_STATUS_CHANGE) and, when the target status matches the configured syncOrderStatusUid, calls the shipment service to sync the order (respecting the label limit and the plugin's own eligibility check via ShipmentService::shouldSyncOrder()).
• Scheduled task. gls/shipments/update-statuses (console command, registered on Craft's schedule and run hourly) refreshes the tracking status of stored shipments. Supports --limit and --onlyWithoutStatus when run manually, for example:

  php craft gls/shipments/update-statuses --limit=50 --onlyWithoutStatus=1

• MCP tools. When the yStore MCP plugin is installed, GLS registers five tools on EVENT_REGISTER_TOOLS:
  • shipping_create_shipment -- create a GLS label for an order (force to generate an additional label when one already exists).
  • shipping_get_shipment -- look up a shipment by shipment ID, parcel number, or order ID.
  • shipping_get_label -- fetch a shipment's label as base64, requesting it from GLS if not already cached.
  • shipping_list_labels -- list every label generated for an order.
  • shipping_track_parcel -- refresh and return the live GLS tracking timeline for a parcel.
• Data model. Shipments are stored as ShipmentRecord rows ({{%gls_shipments}}): parcel number, order ID, status, label type, the raw request payload sent to GLS, the raw API response, and the tracking response. Labels are persisted as filesystem attachments rather than kept only in the database column, so repeated downloads don't re-request the label from GLS.
• Settings model. GLS's settings extend yStore's shared AbstractShippingSettingsModel (yui/craft-core), so the common shipping fields (price, currency, free-shipping threshold, country/weight restrictions, visibility window, payment-method restriction) behave the same way as on every other yStore shipping plugin. GLS adds its own API credentials, sandbox toggle, pickup address, and label-related fields on top.

Requirements

• Craft CMS 4 or 5.
• yui/craft-core (ycore) and a yStore commerce install.
• A GLS account with ParcelService API credentials (client number, username, password) for the country-specific GLS domain -- production and/or sandbox.