Migrating InPost's Country APIs to One Global API

Why InPost's Per-Country APIs Are Becoming a Liability

If you're shipping InPost parcels across Poland, the UK, Italy and Spain today, you're probably juggling four different authentication schemes and four different codebases to maintain them. That's not an exaggeration. Direct InPost integration means managing separate APIs and credentials for each market: InPost UK, InPost Italy, InPost ES, and InPost Global, each with different fields (Client ID + API Token for UK, Organisation ID + Bearer Token + Brand ID + LoginAPI + API Key for Italy, Username + Password + Dual Courier API credentials for Spain). On top of that, for the UK, every locker service needs its own credentials, so a single market can multiply your credential count further.

The pain isn't just onboarding. It's ongoing. InPost runs separate APIs per market and updates them independently, so direct integrators have to track changes across InPost UK, Italy, Spain, and Global, refresh credentials when authentication updates, and adjust per-service routing logic when locker product codes change. If you've built and maintained carrier connections at scale, you know what this looks like in practice: a Tuesday morning Slack message asking why Italian labels stopped generating, followed by two hours of digging through changelogs you didn't know existed.

This isn't unique to InPost. Several European carriers have spent the last few years collapsing region-specific integration stacks into single credential sets, and InPost's InPost Global API is the newest entrant in that pattern. The pitch is straightforward: one OAuth 2.1 client, one set of endpoints, and a Points API that works the same way whether you're looking up a locker in Kraków or a PUDO point in Manchester.

If you'd rather not run this migration yourself, this is exactly the kind of maintenance burden that platforms like Cargoson, alongside nShift and Sendcloud, are built to absorb by normalizing carrier credentials behind one API on their end.

What You Need Before You Start

Before touching any code, get these five things in place. Skipping this step is the single most common reason migrations stall halfway through.

• An active InPost contract in each live market. A direct commercial relationship with InPost is required regardless of which API you integrate against — the Global API doesn't remove this requirement.
• Developer Portal access at developers.inpost-group.com to register your application and obtain a Client ID and Client Secret.
• Sandbox access against the staging host, plus a REST client like Postman or curl for manual token testing before you write any application code.
• A written inventory of every existing integration touchpoint: label generation calls, Points/locker lookup calls, and tracking webhook or polling logic, per market.
• Realistic scope for phase one. Pilot phase: Currently available for selected domestic services in Poland, so don't plan a full UK/IT/ES cutover on day one.

Migrating Step by Step

The answer to "how do I move off four InPost APIs" is: audit first, authenticate second, migrate endpoints in parallel, then cut over market by market rather than all at once. Here's the sequence that avoids breaking production.

1. Audit existing per-market integrations. List every credential set and endpoint currently in use — ShipX PL tokens, UK Client ID/API Token, Italy's Organisation ID/Bearer Token/Brand ID combination, Spain's Username/Password pair — and map which order flows and which teams depend on each one. You can't migrate what you haven't inventoried.
2. Register for the InPost Global API. Create an application in the Developer Portal to get your Client ID and Client Secret. InPost is in-progress of enabling markets with a self-service solution at merchant.inpost-group.com, but until your market is live there, expect to contact your Integration Team with requested scopes directly.
3. Implement the OAuth 2.1 token flow. Request a token via POST to the token endpoint using the client_credentials grant. This is the flow InPost recommends for backend integrations: best suited for Machine-to-Machine applications, such as CLIs, daemons, or backend services, and it is strictly correlated with a single application, recommended for simple integrations. The critical detail here: the authorization server supports two OAuth 2.1–compliant ways to pass client_id and client_secret during the token request — choose exactly one method per request, do not send both at the same time. A successful call against the staging host returns a JSON body with an access token and a short expiry, typically under ten minutes, so build refresh logic from day one rather than bolting it on later.
4. Scope tokens correctly. Every token is scoped to specific permissions. Request only what each service needs — a tracking webhook consumer doesn't need shipment-write scope, and a rate-lookup job doesn't need Points-write access. Over-scoping is a security review problem waiting to happen; under-scoping produces 403s that look like outages.
5. Migrate Points/locker lookups first. This is the lowest-risk endpoint to move because it's read-only. The Global API introduces a unified approach to accessing pickup and drop-off locations across all supported markets — a single Points API now returns both lockers and PUDO points, regardless of country or region, with no need to query separate endpoints per market. Run this in parallel against your existing per-country Points calls for a few days and diff the results for a fixed set of postcodes before trusting it in production.
6. Migrate shipment creation and labels in parallel, not in place. Keep your legacy ShipX/UK/IT/ES calls live. Route a small, controlled slice of test orders through the Global API's shipment endpoint and compare label output, response codes and field mapping. This unified system simplifies location-based services and ensures consistency in user experience across borders, and the Global API streamlines shipment creation with a fast, consistent, and flexible process across all supported markets — but you should verify that claim against your own label formats before you believe it. Label requests support two response types, and depending on the requested Accept header, the API returns labels either as a binary file or a JSON object with the label content provided as a Base64-encoded string, so pick the format your printing workflow already expects rather than rebuilding that pipeline too.
7. Set up unified tracking webhooks. Replace per-market polling with the Global API's webhook configuration so status changes push to you instead of you pulling on a schedule. This alone removes a meaningful chunk of the maintenance overhead described earlier, since you stop tracking four separate polling cadences and rate limits.
8. Cut over market by market, starting with Poland. Poland is the only market with broad Shipping API coverage in the current pilot. Hold UK, Italy and Spain on their legacy APIs until InPost confirms Global API coverage for the specific services you use there, then decommission old credentials one market at a time rather than in one weekend cutover.

How to Know the Migration Worked

You'll know a given endpoint migration succeeded when three things line up in sandbox before you touch production: a shipment creation call returns a successful status with a valid label and a tracking number in the format your downstream systems already parse; a Points lookup for a known test postcode returns the same lockers and PUDO points as the legacy endpoint you're replacing; and a webhook fires on a test shipment status change without you having to poll for it manually. Run all three checks for at least a week of real order volume in staging before decommissioning any legacy credential — a one-day test doesn't catch weekend batch jobs or overnight tracking updates.

Failure Mode: Scope Mismatches and Silent 403s

The most common early mistake isn't a broken endpoint. It's an authentication configuration error that produces a response indistinguishable from an outage. Requesting a shipment-write action with a Points-only scope returns a permission failure that looks like the API is down, not like your token is misconfigured. The same happens if you mix up the two credential-passing methods: choose exactly one method per request — do not send both at the same time. Teams that skip this detail spend hours debugging what looks like a service disruption when it's actually a malformed token request.

The fix is boring but effective: log every token request and response pair in staging, and check the scopes your endpoint documentation requires against the scopes your token actually carries before you promote anything to production. Don't assume a scope that worked for Points also covers shipment creation.

Also keep a documented fallback path. Since the Shipping API is currently available for selected domestic services in Poland only, teams building UK, Italy or Spain flows should assume legacy per-market APIs remain the production path for those services until InPost confirms otherwise, not the other way around.

Where This Fits Your Broader Carrier Connectivity Strategy

InPost's consolidation mirrors a pattern playing out across carrier API surfaces more broadly, as OAuth 2.0/2.1 becomes the default authentication model and single-key or username/password schemes get phased out. If you're running InPost alongside a dozen other carriers, each with its own migration timeline, the calculation changes. TMS platforms with built-in carrier connectivity such as Cargoson, nShift, Shiptify and FreightPOP absorb this kind of per-carrier credential churn so your internal team isn't rebuilding an integration every time a carrier restructures its stack, while multi-carrier parcel tools like Sendcloud, ShipEngine, Easyship or Shippo solve a similar problem from the parcel side.

Whichever path you choose, the InPost Global API is worth testing now, even in limited pilot form. The Poland domestic pilot gives you a low-risk sandbox to validate your OAuth 2.1 implementation, your Points integration and your webhook handling before InPost expands coverage to UK, Italy and Spain. Start the audit this week, register your Developer Portal application, and get a Poland shipment through the new flow before you plan anything more ambitious.