How to Integrate Bpost's Shipping Manager API

What You Need Before You Start

Bpost's Shipping Manager API doesn't work like the REST/JSON APIs you're probably used to from DHL or DPD. It's an older XML/SOAP-style web service tied to a business contract, and a proper Bpost API integration means dealing with account provisioning, a portal-issued passphrase, and a manual email request before tracking even works. This guide walks through the actual sequence, not the marketing version.

Before you touch any code, you need a registered Bpost business account, not a personal shipping account. To begin, go to the Bpost website to create, or log into, the company's Bpost business account, and when creating the account, have the company's VAT number and mobile phone number ready. Following the website's steps to complete registration submits a request to enter a contractual business relationship between the company and Bpost, and that contract has to be signed before the Shipping Manager becomes usable. If the Shipping Manager link is greyed out once you're logged in, contact your account manager directly or call Bpost's support line.

You'll also want a sandbox-safe test order and someone on your team who can read WSDL/XSD schemas comfortably, since Bpost doesn't publish a Swagger or OpenAPI spec for this service.

Step 1: Get Your Account ID and General Service Passphrase

1. Log in to the Bpost portal and open Shipping Manager > Admin > General Settings. You can find your accountId and passphrase in your Bpost Shipping Manager section under Shipping Manager, Admin, General Settings.
2. Note your six-digit Account ID. Your Bpost account ID consists of six digits, and if your contract covers multiple account IDs you'll need to pick the one that matches the shop or division you're integrating.
3. Set or retrieve the General Service passphrase in the same screen. The passphrase should not exceed 30 characters, and you should modify the name of the webshop and change the default value of the passphrase rather than leaving Bpost's default in place — an easy thing to forget on a rushed setup.

This passphrase authenticates label and order creation calls. That's it. It has nothing to do with tracking, which brings us to the step most first-time integrators skip entirely.

Step 2: Request a Separate Tracking Passphrase (the step everyone misses)

Shipping and tracking are two separate credential domains in Bpost's model, and the tracking credential isn't self-service. If you announce your parcels through the Shipping Manager API, you'll have a passphrase, but for any tracking activity you'll be required to ask a Bpost consultant for an API Tracking password.

Sendcloud's carrier documentation confirms the structure directly: a direct Bpost integration means managing three separate credentials: Account ID, General Service passphrase, and a Tracking Service passphrase issued only on email request to [email protected]. This isn't available anywhere in the self-service portal. Your Tracking Service Passphrase cannot be found in the Bpost user portal — to request it, contact [email protected], and the Shipping Manager department will generate a Tracking Password for you.

Send this request in parallel with Step 1, not after. Email turnaround isn't instant, and this single gap accounts for most "my labels print fine but tracking returns nothing" support tickets you'll see once the integration goes live.

Step 3: Download the SHM API Package and Read the XSDs

There's no hosted developer portal with live API docs here. The bpack integration manual, Shipping Manager API example requests, and XSDs for all available web services are distributed as a downloadable package from Bpost's Freshdesk knowledge base. There are five ways to create announcements and labels, and you choose the method that suits your business — plug-ins, front-end modules, deep API integration, or EDI file upload. For a custom build, you want the deep integration path, which uses the Shipping Manager web services directly.

Inside the package you'll find the core schema objects: Order, Box, and the Product/Options block that determines which service the shipment ships under. National shipments and international shipments (bpack Europe/World) use different branches of the same schema, so check which XSD version your contract maps to before you start building request payloads — Bpost has iterated the schema over several major versions, and mixing an old example with a new XSD is a common source of validation errors.

Most implementations center on the createLabelForOrder call and its bulk equivalent for batch label generation. Community libraries built around this API (several PHP wrappers exist on GitHub) typically expose a method that takes an order reference, a label format, a flag for return labels, and an output type — useful as a mental model for what every implementation needs to supply, even if you're writing your own client from scratch rather than reusing someone else's wrapper.

Step 4: Build and Send the Order/Label Request

1. Construct the Order XML with sender/recipient blocks, a Box element describing weight and dimensions, and a Product/Options node specifying the service level.
2. POST the request to the SHM endpoint, authenticating with your Account ID and General Service passphrase from Step 1.
3. Parse the response for the returned barcode and label bytes (PDF or PNG, depending on what you requested).
4. Persist the barcode against your internal order or shipment ID immediately — it's the only link between the Bpost shipment and your ERP record, and Bpost doesn't send it back to you again unprompted.

Service selection differs meaningfully between domestic and international shipments, and getting this wrong is a common cause of rejected orders. For domestic deliveries within Belgium, the options are bpack 24h Pro, bpack 24h business, or bpack Bus. For cross-border shipments, the options are bpack World Express Pro, bpack World Business, or bpack Europe Business, and for international deliveries you also need to declare the type of goods in the package as SAMPLE, GIFT, GOODS, DOCUMENTS, or OTHER — a field that domestic shipments don't require but that international customs processing depends on.

You'll know the call worked when you get a 200-level response containing a valid barcode and a retrievable label file. If the barcode field comes back empty or the label bytes fail to decode, don't retry blindly — check the Product/Options combination against the delivery nature (domestic vs. international) first, since that mismatch is the most common cause of a silently malformed response at this step.

Step 5: Wire Up Tracking (Polling or Webhook)

Native Bpost tracking is gated behind the separate Tracking Service passphrase from Step 2, and the native web service is check-based rather than push-based — you poll it on a schedule rather than receiving events automatically. Most direct integrators build a cron-style job that checks status for open barcodes every few hours.

If that polling cadence is too slow for your customer service or WMS needs, third-party tracking aggregators fill the gap. TrackingMore, for instance, delivers automated tracking updates to your webhook endpoint whenever your Bpost shipment status changes, which removes the polling loop entirely at the cost of routing your tracking data through a third party. Whether that trade-off is acceptable depends on your data residency and vendor requirements.

This is also the point where a lot of shippers reasonably ask "why am I maintaining a SOAP client for this at all?" Platforms like Sendcloud, ShippyPro, ClickPost and AfterShip wrap the Bpost passphrase/XSD complexity behind a single REST schema shared across every carrier they support, and TMS platforms with built-in carrier connectivity, such as Cargoson, handle the same problem at the transport-order level so your team isn't the one re-testing payloads every time Bpost revises the schema. Through Sendcloud specifically, you authenticate once with your Sendcloud API key and use a single REST schema for Bpost alongside every other carrier in your account, and Sendcloud absorbs upstream changes from Bpost. The trade-off is control and cost, not correctness — a direct integration and a wrapped one can both work fine, but only one of them is yours to fix at 11pm when something breaks.

Common Failure Mode: Passphrase Mismatch and Silent Auth Errors

The most frequent production issue is exactly the gap described in Step 2: label calls succeed because they only need the General Service passphrase, while tracking calls fail because nobody emailed [email protected] for the separate Tracking passphrase. The symptom looks like a broken tracking integration; the actual cause is a missing credential that was never requested in the first place. Check your Tracking passphrase field before you assume the tracking endpoint itself is down.

A second, quieter failure mode: someone rotates the passphrase in the Shipping Manager portal (say, during a security audit) but forgets to update it in the integration config. The passphrase can be changed in the bpost platform by the administrator, and once done, a connected module will not be able to connect to the bpost platform anymore unless the password is likewise modified on the integration side. Bpost doesn't expire the old credential the way an OAuth token would — it just silently stops authenticating. Build a rotation runbook: whenever the passphrase changes in the portal, update it in your config the same day, and run a scheduled sandbox test that hits both the label and tracking endpoints independently so a mismatch surfaces within hours, not weeks.

Validating the Integration End to End

Before calling the integration done, run through this checklist on a real test shipment:

• Order created via the SHM API and a 200-level response received
• Label PDF or PNG retrieved and opens correctly
• Barcode logged against your internal order/shipment ID
• Tracking status successfully returned for that barcode using the separate Tracking passphrase
• Status change reflected in your TMS or ERP within your expected polling interval

Once that checklist passes, set up a recurring synthetic test shipment (weekly is a reasonable cadence) that runs the same five checks automatically. Bpost updates the Shipping Manager schema and international price-zone configuration periodically, and a scheduled health check catches a broken integration before your operations team does, which is a much better place to find out about it.