How to Integrate GEODIS Shipment and Zoom APIs

GEODIS hands you two completely separate API keys before you write a single line of integration code, and if you only request one, your tracking calls will fail silently for weeks. That's the first surprise for most European shippers approaching a GEODIS API integration for the first time. Unlike single-endpoint carriers where one token gets you booking, labels and tracking, GEODIS splits its parcel and pallet connectivity into a Shipment API for booking and label generation, and a distinct "Zoom" API for tracking. This guide walks through connecting both, picking the right service code, and the rejection error that catches almost everyone on their first production run.

Why GEODIS needs two APIs, not one

GEODIS Distribution & Express runs its booking and label workflow through the Shipment API, while tracking events live entirely on a separate system called Zoom. Geodis maintains separate API endpoints for shipments and tracking (ZoomClient). That means two credential pairs, two sets of documentation, and two things that can break independently of each other. Boostmyshop's integration notes confirm the split is functional, not just organizational: the Geodis Shipment API covers shipment registration and validation as well as label printing, and the tracking number returns when the shipment is created, but that tracking number isn't final until Zoom processes it.

If you only need parcel and pallet shipping, the Shipment and Zoom APIs are your doorway. If you're instead moving ocean or air freight forwarding volumes, GEODIS routes that through a different system entirely, the IRIS booking platform exposed via the newer developer.geodis.com portal, which is explicitly pitched as a way to connect Business applications to our IT System, through API or EDI technologies. High-volume accounts can also skip APIs altogether and move transport orders via EDI. This guide covers Shipment and Zoom specifically, since that's where most mid-sized European shippers start.

Before you start: what you need

You can't self-serve your way into GEODIS Distribution & Express API access the way you can with a plug-and-play carrier. You need an active shipper contract and an account manager who will issue you five separate values. According to Sendcloud's own contract activation flow, you'll need to enter the Identifier, API Key (Shipments), API Key (Tracking, also called ZoomClient), Depot Code (CodeSA), and Customer Account (CodeClient) from your Geodis account manager.

• Identifier – your unique account identifier issued by GEODIS
• API Key (Shipments) – used for every call to the Shipment API
• API Key (Tracking / ZoomClient) – a separate key used only for tracking lookups
• Depot Code (CodeSA) – your departure agency code
• Customer Account (CodeClient) – your customer code, used for routing and billing

Note the depot limitation before you design your architecture: most third-party connectors, and likely your own setup, support one depot code per account; if you have multiple Depot codes, you'll need separate accounts. If you ship out of three distribution centers, budget for three sets of credentials and three connection configs, not one.

You'll also need a confirmed service code before you write a single request. GEODIS runs domestic parcel services like Pack30 (P30), European multi-parcel and pallet services under the MEI family, and express options under EEX and CXI, among others. Get your account manager to confirm in writing which of these your contract actually covers and what's a sandbox versus live environment, because GEODIS doesn't publish a universal testing sandbox the way some carriers do.

Step-by-step: connecting to the GEODIS Shipment and Zoom APIs

1. Request API access and credentials from your GEODIS account manager. This isn't self-serve signup. You need a live Distribution & Express contract first, and the account manager issues the Identifier, both API keys, CodeSA and CodeClient once that's in place.
2. Confirm your service code(s) and their mandatory fields. P30 is built for single-parcel domestic shipments only — the P30 service is designed for single-parcel shipments, which means it behaves differently from multi-parcel services. If your order management system batches multiple parcels per shipment, P30 will reject the payload. Confirm with your account manager which service supports multi-parcel before you build against it.
3. Build the shipment creation call to the Shipment API. Pass consignee details, weight, your confirmed service code, and for any European service like MEI, volume and dimensions, since for some European services such as MEI, volume and dimensions may be mandatory when generating the shipment.
4. Add the Incoterm field for any international move. This is the single most common cause of rejected calls, covered in detail below.
5. Parse the response for the shipment/tracking number and label file, then store both against your internal order ID. Watch the format of the tracking number closely here — more on that in the failure mode section.
6. Print and attach the label, then hand the parcel off to GEODIS for collection. Label formats returned are typically ZPL or PDF depending on your account configuration.
7. Call the Zoom API separately, using your ZoomClient key, to retrieve tracking events. This is a distinct authenticated call against a distinct endpoint; your Shipment API key will not authenticate against it.
8. Map GEODIS event codes to your internal status set (booked, collected, in transit, delivered, exception) and run one full end-to-end test shipment before go-live, confirming it mirrors correctly in the GEODIS customer web portal.

How you know it worked

You're looking for four concrete signals. First, the Shipment API call returns a valid label file (PDF or ZPL) alongside a tracking reference, since the Geodis Shipment API covers shipment registration and validation as well as label printing, and the tracking number returns when the shipment is created. Second, that same shipment appears in the GEODIS customer portal within minutes, confirming the booking actually registered on GEODIS's side and wasn't just accepted by your own code. Third, when you query the Zoom API with that tracking reference, you get back a real event, not an empty response. Fourth, your end-of-day manifest reconciles cleanly, meaning every shipment you booked that day actually appears on GEODIS's close-out report.

Common rejection: the temporary tracking number trap

Here's the one that catches almost every team on their first week in production, and it has nothing to do with the Incoterm or dimension fields. When you create a shipment, GEODIS doesn't hand back the real, customer-facing tracking number immediately. As Boostmyshop's documentation explains, when you process shipments with Geodis, Geodis API returns a temporary tracking number starting with JVGT, and this tracking number can not be used to track the parcel, it needs to be converted using the Zoom platform. If your system pushes that JVGT-prefixed placeholder straight into a shipping confirmation email or your OMS, customers get a tracking link that returns nothing, and your support team starts fielding complaints within hours.

The fix is a polling job, not a one-time call. You must schedule the feed to "transform" JVGT tracking numbers to real tracking numbers, requesting the Zoom server every hour to get the "real" tracking number from the temporary number. If your CMS or OMS has no mechanism to suppress the JVGT placeholder until it's resolved, the practical workaround used by several integrators is to delay the outbound shipping confirmation, since the only turnover is to schedule the shipping confirmation feed once a day, during the evening, this way the Zoom API should have returned the real tracking number before.

The second common rejection sits on the booking side, not tracking. For cross-border shipments, missing the Incoterm field is the most frequent cause of a failed call: for international shipments, an Incoterm is required depending on the enabled services and scope of your contract. Build a pre-submission validation layer that checks service code against required fields (Incoterm for international, volume/dimensions for MEI, parcel count against the contracted service) before you ever call the Shipment API. Catching this in your own code costs you one conditional statement. Catching it after a 4xx response costs you a support ticket and a delayed shipment.

When to use a connector instead of building direct

If GEODIS is one of several carriers you run, and especially if you're not shipping enough volume through them to justify dedicated maintenance, a managed connector removes most of this burden. Platforms like Sendcloud, Shippingbo, Boostmyshop and AfterShip already maintain GEODIS connectivity, including the JVGT-to-Zoom conversion logic described above, so you're not rebuilding that polling job yourself. Sendcloud is explicit about what you're buying out of: direct Geodis integration means managing separate API keys for shipments and tracking (the ZoomClient API), handling the Identifier, Depot Code (CodeSA), and Customer Account (CodeClient) on every shipment, and generating end-of-day Geodis manifests in your own code.

Multi-carrier TMS platforms take a similar approach at a different layer. Cargoson, for instance, exposes GEODIS's regional entities through a single unified booking and tracking pattern across freight prices, labels and tracking, rather than making you hold separate credential pairs per country. That's one option among several, not a universal recommendation, and the right call depends on how many carriers you run in parallel and how much in-house engineering time you want tied up in carrier-specific edge cases.

Maintaining the integration long-term

Service codes, Incoterm requirements and label formats change when GEODIS renegotiates contracts per country, often without much advance notice to the shippers using them. Build a quarterly review into your maintenance calendar: confirm your credential set is still valid, re-verify which service codes your contract actually supports, and keep a logged mapping table between your internal status codes and GEODIS's Zoom event codes so a silent carrier-side change doesn't quietly break your order status updates. For teams running dozens of direct carrier connections in parallel, this kind of recurring check is the unglamorous work that actually keeps a GEODIS Zoom API or Shipment API integration alive past its first six months in production.