# Idempotency & Event Versioning in Courier APIs | x25pronto

Canonical: https://x25pronto.ch/en/blog/best-practices-fur-idempotenz-und-event-versionierung-in-kurier-apis.html

VW Tiguan R · 320 PS 4MOTION · discreet · direct

EXPRESS COURIER · DIRECT · MON–SUN

Courier service Switzerland.
Express courier. Direct.
Also overnight.

x25pronto Switzerland takes goods direct to the destination. Small loads go by car. Larger loads go by van or Van XL. Direct, express and overnight trips run Monday to Sunday when a slot is free. Free times are shown in the booking calendar. This keeps the plan clear.

[Calculate price](https://x25pronto.ch/en/#quote)[How overnight works](https://x25pronto.ch/en/overnight.html)

Direct Mon–Sun Overnight Mon–Sun Car & van up to 1,000 kg

COURIER INSIGHTS

# Best practices for idempotency and event versioning in courier APIs

Practical patterns for idempotency keys, deduplication, event versioning and safe migration paths in courier APIs. Focus: reliable bookings and reconciliation.

23 September 2026

## Quick answer

In short: use structured idempotency keys, server‑side deduplication with deterministic fingerprints, and an explicit event versioning scheme with clear migration paths. These measures prevent duplicate bookings, ease error handling and protect integrations from Zurich to Geneva.

## Why idempotency and versioning matter

Courier APIs handle mission‑critical actions: booking pickups, updating routes and cancelling orders. Network retries, client bugs or duplicated requests can create double bookings and inconsistencies. Idempotency prevents repeated effects. Event versioning keeps schema changes backward compatible and enables safe migrations across internal systems and third‑party integrators.

## Idempotency key pattern

Use a structured key: {client_id}:{operation}:{hash(payload)}. Example: customer42:createBooking:3f8a7b. client_id separates tenants, operation clarifies action, and hash(payload) captures the important fields. Set a configurable TTL (e.g., 24–72 hours). Store key, result status and server response. On repeated requests with the same key return the same HTTP status and payload.

## Server‑side deduplication and deterministic checks

Don’t rely on keys alone. Validate deterministically: check fields such as pickup address, recipient, package dimensions and time window. Maintain a fingerprint column in the DB (e.g., SHA256 over selected fields). If fingerprint and key match, treat the request as a duplicate. Define tolerances for 'similar' requests, for example small shifts in time windows.

## Event versioning: strategy and formats

Version events explicitly: event.type, event.version, event.schema. Use MAJOR.MINOR (1.0, 2.0). MAJOR changes are incompatible; MINOR changes are additive. Include a schema identifier (schema_uri or schema_id). Use JSON Schema or Avro for validation and keep old schemas in a repository so consumers can build backward parsers.

## Migration paths and compatibility rules

Set rules: 1) Additive fields are safe. 2) Removing or renaming fields is breaking. 3) Provide feature flags for consumers. Plan a deprecation window: notify integrations via webhook and portal 30–90 days before a MAJOR change. Offer an opt‑in for the new version until consumers migrate.

## Error handling and reconciliation

Log idempotency events, fingerprints and decision logic. Provide a reconciliation API so partners can poll status and report divergences. Build an operations UI to merge duplicates or resolve conflicts manually. Keep audit trails for compliance and dispute resolution.

## Frequently asked questions

How long should an idempotency key be valid? Common TTLs are 24–72 hours. Choose a window that fits the business flow. For pickup bookings 48 hours is often enough; for longer processes use a longer TTL.

What if payload fields change between retries? Compare fingerprints. Small non‑critical changes (notes) can be accepted; changes to crucial fields (destination, weight) should break idempotency and require a new booking.

How to handle incompatible event changes? Introduce a MAJOR version, notify consumers, keep old events readable and provide adapters or transformation layers in your event broker during migration.

Which fields belong in the idempotency hash? Business‑relevant fields: pickup/delivery address, recipient ID, package dimensions, desired time window and service type. Exclude volatile metadata like timestamps.

## Plan a courier trip in Switzerland

x25pronto Switzerland carries small and well packed shipments by car. Businesses can choose a direct courier trip or overnight service. Route, timing and shipment details can be entered online before booking. The guide price is then shown for the planned courier order.

[Direct courier →](https://x25pronto.ch/en/direct-courier.html)[Overnight →](https://x25pronto.ch/en/overnight.html)[Services →](https://x25pronto.ch/en/services.html)[Calculate guide price →](https://x25pronto.ch/en/#quote)

### At a glance: Best practices for idempotency and event versioning in courier APIs

Key points from this article. Follow the links to read each explanation.

Why idempotency and versioning matter Courier APIs handle mission‑critical actions: booking pickups, updating routes and cancelling orders. [Read this section](https://x25pronto.ch/en/blog/best-practices-fur-idempotenz-und-event-versionierung-in-kurier-apis.html#courier-article-step-1)

Idempotency key pattern Example: customer42:createBooking:3f8a7b. client_id separates tenants, operation clarifies action, and hash(payload) captures the important fields. [Read this section](https://x25pronto.ch/en/blog/best-practices-fur-idempotenz-und-event-versionierung-in-kurier-apis.html#courier-article-step-2)

Server‑side deduplication and deterministic checks Validate deterministically: check fields such as pickup address, recipient, package dimensions and time window. [Read this section](https://x25pronto.ch/en/blog/best-practices-fur-idempotenz-und-event-versionierung-in-kurier-apis.html#courier-article-step-3)

Event versioning: strategy and formats Version events explicitly: event.type, event.version, event.schema. [Read this section](https://x25pronto.ch/en/blog/best-practices-fur-idempotenz-und-event-versionierung-in-kurier-apis.html#courier-article-step-4)

Migration paths and compatibility rules Removing or renaming fields is breaking. [Read this section](https://x25pronto.ch/en/blog/best-practices-fur-idempotenz-und-event-versionierung-in-kurier-apis.html#courier-article-step-5)

More on this topic These guides cover related questions: [Idempotency, retries and rate limiting for courier APIs](https://x25pronto.ch/en/blog/idempotenz-retries-und-rate-limiting-bei-kurier-apis.html) · [Batch Bookings & Bulk Uploads via API: Best Practices](https://x25pronto.ch/en/blog/batch-buchungen-massenuploads-via-api-best-practices.html)