Matkahuolto API

Ta treść nie jest jeszcze dostępna w Twoim języku.

Globe Pickup Points integrates with Matkahuolto through Matkahuolto’s XML shipment interface. With this integration, you can:

Export orders to Matkahuolto directly from Shopify
Print shipping labels within Shopify, as 10 × 15 cm labels or four labels on an A4 sheet
Ship to Matkahuolto parcel points and parcel lockers in Finland
Ship to addresses in Finland as Home Parcel, XXS Parcel to Mailbox or Business Parcel
Ship to addresses in the other EU countries as International Home Parcel
Track parcels on Matkahuolto’s tracking page

There is no cash on delivery. See Cash on delivery (COD).

Enabling Matkahuolto API integration

You need your own Matkahuolto customer number with API credentials for Matkahuolto’s XML interface. Labels and invoices go to that customer number. If you have no API credentials for it yet, request them with the form on matkahuolto.fi (Corporate customers, Parcel services, Interfaces).

In your Shopify admin, open Globe Pickup Points and navigate to Shipping labels. Click Add carrier and select Matkahuolto.
Enter your Customer number, in digits. Globe drops spaces and leading zeros.
Enter the API password: the password Matkahuolto sends with the API credentials for the XML interface.
Select the Environment: Production creates real shipments. Development uses Matkahuolto’s test system, which processes nothing and works only with test credentials from Matkahuolto.
The sender fields are optional: Sender company name, Sender street, Sender ZIP, Sender city, Sender phone and Sender email. Leave all of them empty to print the sender Matkahuolto has for your customer number. If you fill them in, fill in at least the name, street, postcode and city of a Finnish address. The postcode has five digits.
Optionally, click Show advanced settings and set a Default weight (kg), used when an order has no weight.
Configure fulfillment and tagging options as needed:
- Automatically fulfill orders: Never, Yes, send order shipped email with the tracking number or Yes, do not send order shipped email. When enabled, the order is fulfilled after export with the Matkahuolto shipment number, Matkahuolto as the carrier and a link to Matkahuolto’s tracking page.
- Automatically tag orders with tracking number adds the shipment number as an order tag.
- Custom tag after export adds your own tag after every successful export.
Map your Shopify shipping methods to a Matkahuolto product. The mapping is optional. You can change the product for each order when you create the label.

Products

Product in Globe	Delivery
Matkahuolto (parcel point or locker if selected, otherwise home delivery)	To the Matkahuolto parcel point or locker the customer picked in checkout, as Pick-up Parcel. Without a point, as Home Parcel to an address in Finland, or as International Home Parcel to an address in another EU country. Also used when no product is set.
Matkahuolto Pick-up Parcel (80): parcel point or locker	To the Matkahuolto parcel point or locker on the order, in Finland. An order without one is refused.
Matkahuolto XXS Parcel (84): parcel point or locker, small parcels	Small parcels to the Matkahuolto parcel point or locker on the order, in Finland. An order without one is refused.
Matkahuolto Home Parcel (34): home delivery in Finland	To the customer’s address in Finland, also when the order has a pickup point.
Matkahuolto XXS Parcel to Mailbox (37): home mailbox in Finland	To the customer’s home mailbox in Finland.
Matkahuolto Business Parcel (30): business address in Finland, daytime	To a business address in Finland, in the daytime.
Matkahuolto International Home Parcel (97): home delivery in other EU countries	To the customer’s address in another EU country. See International Home Parcel.

Home Parcel, XXS Parcel to Mailbox and Business Parcel go to Finland only. For an address in another EU country, choose International Home Parcel.

Matkahuolto enables products per agreement. If your agreement does not include a product, Matkahuolto refuses the shipment: choose another product, or ask Matkahuolto to add it to your agreement.

Matkahuolto sends the customer an arrival notice by SMS or e-mail. An order with neither a phone number nor an e-mail address is not exported.

International Home Parcel

International Home Parcel goes to addresses in Austria, Belgium, Bulgaria, Croatia, Cyprus, Czechia, Denmark, Estonia, France, Germany, Greece, Hungary, Ireland, Italy, Latvia, Lithuania, Luxembourg, Malta, the Netherlands, Poland, Portugal, Romania, Slovakia, Slovenia, Spain and Sweden. An address in Finland needs Home Parcel. Destinations outside the EU are refused.

Matkahuolto hands these parcels to a partner carrier for delivery. The tracking number is the one Matkahuolto returns, which can be the partner’s number. Matkahuolto’s tracking page knows it.

Exporting and printing labels

You can export orders to Matkahuolto and print shipping labels directly from Shopify, either in bulk or individually. For the label workflow itself, see Creating shipping labels.

Exporting an order creates one Matkahuolto shipment with one parcel. Matkahuolto returns the shipment number and the label in the same answer. The shipment number is the tracking number. Parcels are tracked at https://www.matkahuolto.fi/seuranta?shipmentNumber=<shipment number>. The Shopify order name is sent as the sender reference, up to 35 characters.

The parcel weight comes from the order. If the order has no weight, the Default weight (kg) is used. If neither is set, the order is not exported. Matkahuolto checks the weight per product and refuses a parcel heavier than the product allows.

Matkahuolto needs the receiver’s name or company. For a delivery to an address, the order needs street, postcode and city. A Finnish postcode has five digits. The 10 × 15 label does not print the second address line, so Globe adds it to the first line when both fit in 40 characters.

Globe sends the orders of a batch one after another. If Globe cannot tell whether Matkahuolto created a shipment, for example because Matkahuolto did not answer in time, the error asks you to check Matkahuolto’s Paketit business portal before you create the label again. Globe then stops before the next order of the batch. It also stops when Matkahuolto refuses the customer number or password. The orders it did not send can be exported again safely.

Globe does not cancel Matkahuolto shipments. Creating the label for the same order again creates a second shipment. Globe deletes a shipment itself only when Matkahuolto created it but Globe cannot keep it: the answer carries no printable label, or Globe cannot save the shipment. The error then says so, and you can create the label again. If Matkahuolto refuses the delete, the error tells you not to create the label again: print or delete the shipment in Matkahuolto’s Paketit business portal.

The integration does not sync delivery statuses back to Shopify.

Pickup points

Globe sends Matkahuolto’s office code of the point, a number, to Matkahuolto. The customer selects the point at checkout; to offer Matkahuolto points, see Adding pickup point carriers. Matkahuolto points that reach the order through Packeta’s feed are accepted too. The point must be in Finland.

Matkahuolto does not refuse an unknown office code: it sends the parcel to the point nearest the customer’s address instead. So before the export Globe checks the point. A point that is no longer on Matkahuolto’s list of open pickup points is refused, and so is a code Matkahuolto does not know. If Matkahuolto’s point search does not answer, Globe uses the point from the order.

An order with a point from another carrier’s network is not exported. It is never shipped to the customer’s address instead. Choose a Matkahuolto point with the Modify pickup point action, or use Matkahuolto Home Parcel (34): home delivery in Finland.

When the customer’s address has no Finnish postcode and city, Globe sends the point’s address as the receiver address.

Cash on delivery (COD)

Matkahuolto has no cash on delivery: Matkahuolto removed it from its shipment interface in version 2.24. An order with a COD amount is not exported, whatever the product. Set the COD amount in the label panel to 0 if the order is already paid, or ship the order with another carrier.

Label printing

Matkahuolto labels can be printed in the following formats:

Format	Labels
Label printer, 10x15 cm (A6)	One label per page
A6 on A4	Four labels per A4 sheet

When printing A6 labels on A4, you can select the starting position on the sheet (positions 1–4) to reuse partially used sheets.

Globe asks Matkahuolto for 10 × 15 cm labels. Labels for several orders are combined into one PDF. Matkahuolto hands out a label only when the shipment is created, so Globe stores it and prints from that copy; you can print a label again at any time.

An International Home Parcel can come with two label pages, the partner’s label and Matkahuolto’s. Globe prints both.

If Globe has no stored label for one of the selected shipments, it prints none of them and names the shipment. Print that label in Matkahuolto’s Paketit business portal.

Troubleshooting

Issue	Resolution
`Matkahuolto settings are incomplete: …`	The message lists the missing settings. Fill them in the carrier settings: the Customer number in digits, the API password, and, if you filled in any sender field, the sender name, street, five-digit postcode and city.
`Matkahuolto refused the customer number or password`	Check the Customer number and API password: they are the API credentials (XML interface) of your Matkahuolto agreement. Development works only with Matkahuolto’s test credentials.
`… is not a Matkahuolto parcel point or locker` or `Wrong carrier for this order`	Choose a Matkahuolto point with the Modify pickup point action, or use Matkahuolto Home Parcel (34): home delivery in Finland.
`Order … has no Matkahuolto parcel point or locker, but delivery to a pickup point was chosen`	Choose a point with the Modify pickup point action, or choose a product that goes to the address.
`… has no Matkahuolto point number on the order`	Choose the point again with the Modify pickup point action, or use Home Parcel.
`Matkahuolto delivers to parcel points and lockers in Finland only` or `… goes to points in Finland only`	Choose a Matkahuolto point in Finland, or ship the order with another carrier.
`… is no longer on Matkahuolto's list of open pickup points`	The point has closed. Choose another point with the Modify pickup point action, or use Home Parcel.
`Matkahuolto no longer has the pickup point …`	Choose another point with the Modify pickup point action, or use Home Parcel.
`Matkahuolto did not accept the pickup point …`	Choose another point with the Modify pickup point action.
`Matkahuolto … delivers within Finland only, and the shipping address is in …`	For an address in another EU country, choose Matkahuolto International Home Parcel (97): home delivery in other EU countries.
`… the shipping address is in Finland. Choose "Matkahuolto Home Parcel (34)" for it`	International Home Parcel goes to other EU countries. Choose Home Parcel.
`Matkahuolto delivers International Home Parcels to EU countries only`	Ship the order with another carrier.
`Matkahuolto no longer offers cash on delivery, for any product` or `This carrier's labels cannot carry cash on delivery`	Set the COD amount to 0 if the order is already paid, or ship the order with another carrier.
`Order … has no weight`	Set the product weight in Shopify, enter Shipment weight (kg) in the label panel, or set a Default weight (kg).
`the parcel weighs … kg, more than Matkahuolto allows for …`	If the weight is wrong, correct Shipment weight (kg) in the label panel. Otherwise choose another product.
`the shipping address has no name or company`	Add the receiver’s name to the shipping address and create the label again.
`Order … has no phone number or e-mail address`	Matkahuolto sends the arrival notice by SMS or e-mail. Add a phone number or an e-mail address to the order.
`the shipping address has no … Matkahuolto … needs street, postcode and city`	Correct the shipping address in Shopify and create the label again. A Finnish postcode has five digits.
`the shipping address has no Finnish postcode and city, and neither has the pickup point`	Correct the address in Shopify and create the label again.
`Matkahuolto does not accept … for this customer number`	Choose another product, or ask Matkahuolto to add it to your agreement.
`Matkahuolto does not allow … for a customer number that pays in cash`	Choose another product, or ask Matkahuolto about your agreement.
`Matkahuolto answered with an internal error (1005)`	Matkahuolto also answers so for a destination the product does not serve. Check the product and the shipping address; if they are right, try again later.
`Matkahuolto refused the shipment: …`	The message gives Matkahuolto’s reason and error number. Correct the order and create the label again.
`Globe could not connect to Matkahuolto` or `Matkahuolto refused the request for order … (HTTP …)`	Nothing was created. Try again in a minute.
`… Check Matkahuolto's Paketit business portal before creating the label again, the shipment may already exist`	Matkahuolto did not confirm the shipment, but it may exist. Check the Paketit business portal before you export the order again.
`Globe stopped before sending order … to Matkahuolto`	Nothing was created for this order. Create its label again once the cause named in the message is fixed.
`… so Globe deleted the shipment again`	Nothing will be sent. Create the label again.
`… Do not create the label again: print or delete shipment … in Matkahuolto's Paketit business portal`	The shipment exists at Matkahuolto. Print or delete it in the Paketit business portal.
`No stored Matkahuolto label for shipment …`	Print the label in Matkahuolto’s Paketit business portal.

Add Matkahuolto pickup points to your Shopify store — pricing, demo & setup →