Migration guidelines for API v3 - Sendcloud API Developer Portal

Why should you migrate to API v3?

API v3 delivers powerful new capabilities unavailable in v2 to streamline operations, which is especially relevant if you are shipping high volumes or handling complex shipments. A standout improvement is per-parcel customisation for multicollo shipments, allowing you to specify individual weights, dimensions, items, and insurance amounts for each parcel. This removes the API v2 limitation where all parcels in a shipment had to share identical attributes, thereby enhancing accuracy and flexibility. For single-collo shipments, synchronous announcements now return labels instantly within the API response, minimising the risk of rate limiting by combining shipment creation and label retrieval into a single call. This significantly reduces delays caused by multiple API requests to fetch labels. Brand ID is now decoupled from the sender address, enabling more flexible and precise branding management. API v3 allows your entire workflow, from creating orders to printing labels, to be handled programmatically via the API, eliminating the need for manual work in the Sendcloud platform and boosting automation efficiency.

Exclusive API v3 Features

Label notes (parcel.label_notes): Print SKUs for pick-and-pack efficiency, customer delivery instructions (e.g., “Ring the blue doorbell”), or personalised thank-yous.
SSCC tracking (parcel.sscc): Monitor pallets or containers across the full supply chain.
Native ZPL labels (label_detail.mime_type): Direct carrier ZPL output prevents scanning errors common with converted formats.
Delivery scheduling (delivery_dates.handover_at / deliver_at): Notify carriers of planned handover times (ideal for warehouse pickups) and expected delivery to customers.
Validate a return: Check that return shipment details are correct before label creation.
Manage shop order statuses and custom status mappings for Prestashop v2 integrations.
Create, update and delete carrier contracts via the API.
More pickup carriers supported for scheduling pickups programmatically.
Create an external parcel for tracking.
Create proper multicollo shipments: Specify the weight and dimensions of each parcel individually to reflect real world differences, instead of duplicating the first parcel’s details as the previous API required.

What’s changed?

Managing orders

In API v3 we’ve introduced a dedicated Orders API to simplify order management. In API v2 these functionalities were spread across the Integrations and Parcels APIs, and some functionalities were only available for certified Sendcloud partners.

Action	API v2	API v3
Create an order that shows in the Sendcloud platform’s Incoming orders page	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label: false` in the request body OR use the Create or update a list of shipments endpoint^* in the Integrations API	Use the Create/update orders in batch endpoint in the Orders API
Get a list of incoming orders	Use the Retrieve a list of shipments endpoint in the Integrations API	Use the Retrieve a list of orders endpoint in the Orders API
Get a specific order	Use the Retrieve a list of shipments endpoint in the Integrations API to fetch all shipments and then filter the results yourself (e.g. by `external_order_id`, `external_reference`, or `order_number`)	Use the Retrieve an order endpoint in the Orders API
Update an order	Update an unannounced parcel using the Update a parcel endpoint in the Parcels API OR Update the integration shipment by re-sending it (re-creating) using the Create or update a list of shipments endpoint^* in the Integrations API	Use the Update an order endpoint in the Orders API
Delete or cancel an order	Use the Delete a shipment endpoint in the Integrations API	Use the Delete an order endpoint in the Orders API

^* This endpoint is only available for certified Sendcloud partners.

Shipping an existing order (creating labels)

The new Ship an Order API in v3 allows you to create a parcel and request a label for an existing order in Sendcloud in one step, both asynchronously and synchronously. In API v2, you could only do this asynchronously.

Action	API v2	API v3
Create a shipment and request the label immediately (asynchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label: false` in the request body	Use the Request a label for one or more orders asynchronously endpoint in the Ship an Order API
Create a shipment and request the label immediately (synchronously)	🚫 Not supported	Use the Request a label for a single order synchronously endpoint in the Ship an Order API

Shipments API v3 vs Ship an Order API v3

The Ship an Order API is specifically designed to create shipments and request labels for existing orders in Sendcloud, in a single step. In contrast, the Shipments API allows you to create a shipment and request a label in a single step without having an existing order in Sendcloud. Note that the Shipments API supports the following features which are not currently available in the Ship an Order API:

synchronous multicollo
importing order notes
order split
shipping rules controls
label creation when the order doesn’t exist in Sendcloud
sender address support (dynamic)
instructions on handling failures stemming from carrier validation errors

Integrations

New in the Integrations API v3, we’ve added the ability to manage shop order statuses and custom status mappings for Prestashop v2 integrations. Custom status mappings allow you to define how your shop order statuses correspond to Sendcloud’s internal status categories, enabling more accurate order processing.

Action	API v2	API v3
List all your integrations (i.e. connected shops/systems)	Use the Retrieve a list of integrations endpoint in the Integrations API (v2)	Use the Retrieve a list of integrations endpoint in the Integrations API (v3)
Get the settings for one specific integration	Use the Retrieve an integration endpoint in the Integrations API (v2)	Use the Retrieve an integration endpoint in the Integrations API (v3)
Update integration settings (full) → replace all settings	Use the Update an integration endpoint in the Integrations API (v2)	🚫 Not supported - use the endpoint below instead.
Update integration settings (partial) → change some settings without touching the rest	Use the Partially update an integration endpoint in the Integrations API (v2)	Use the Update certain parts of an integration endpoint in the Integrations API (v3)
Delete an integration	Use the Delete an integration endpoint in the Integrations API (v2)	Use the Delete an integration endpoint in the Integrations API (v3)
Retrieve or create integration exception logs	Use these Integrations API (v2) endpoints: Retrieve all integration exception logs Retrieve exception logs for a specific integration Create integration exceptions logs	🚫 Not supported
Get shop order statuses (for the Prestashop v2 integration only)	🚫 Not supported	Use the Retrieve shop order statuses for an integration endpoint in the Integrations API (v3)
Create/overwrite shop order statuses (for the Prestashop v2 integration only)	🚫 Not supported	Use the Create or overwrite shop order statuses endpoint in the Integrations API (v3)
Get custom status mapping (for the Prestashop v2 integration only)	🚫 Not supported	Use the Retrieve custom status mapping for an integration endpoint in the Integrations API (v3)
Create/update custom status mapping (for the Prestashop v2 integration only)	🚫 Not supported	Use the Create or update custom status mapping for an integration endpoint in the Integrations API (v3)

Parcels/Shipments

In API v2, the Parcels API was used to create shipments and request labels. In API v3, this has been replaced by the Shipments API. You can also refer to the following field changes when migrating from the Parcels API v2 to the Shipments API v3:

Address fields
Customs fields
Sender address fields
Shipment/Parcel fields
Shipping methods vs. Shipping products vs. Shipping prices vs. Shipping options fields

Action	API v2	API v3
Create a parcel without shipping rules or defaults (synchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label_async: false` and `apply_shipping_rules: false` in the request body	Use the Create and announce a shipment synchronously endpoint in the Shipments API
Create a parcel without shipping rules or defaults (asynchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label_async: true` and `apply_shipping_rules: false` in the request body	Use the Create and announce a shipment asynchronously endpoint in the Shipments API
Create a parcel with shipping rules or defaults (synchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label_async: false` and `apply_shipping_rules: true` in the request body	Use the Create a shipment with rules and/or defaults and announce it synchronously endpoint in the Shipments API
Create a parcel with shipping rules or defaults (asynchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label_async: true` and `apply_shipping_rules: true` in the request body	Use the Create a shipment with rules and/or defaults and announce it asynchronously endpoint in the Shipments API
Create multiple parcels at once	Use the Create a parcel or parcels endpoint in the Parcels API, sending an array of parcels in the request body	🚫 Not supported
Create a multicollo shipment	Use the Create a parcel or parcels endpoint in the Parcels API, setting `quantity` to a number greater than 1	Use any Shipments API `POST` endpoint, by creating more than one parcel object in the parcels array
Retrieve your label after announcement - PDF label	Use one of the following v2 endpoints: Retrieve PDF labels for a label printer Retrieve a specific PDF label for a label printer Retrieve parcel documents with the `type` path parameter set to `label` and the `Accept` header set to `application/pdf`	Use one of these options: Retrieve a parcel document, with the `type` path parameter set to `label` and the `Accept` header set to `application/pdf` Use the response from Create and announce a shipment synchronously or Create a shipment with rules and/or defaults and announce it synchronously (for single-collo shipments only)
Retrieve your label after announcement - ZPL/PNG label	Retrieve parcel documents with the `type` path parameter set to `label` and the `Accept` header set to `application/png` or `application/zpl`	Use one of these options: Retrieve a parcel document, with the `type` path parameter set to `label` and the `Accept` header set to `application/png` or `application/zpl` Use the response from Create and announce a shipment synchronously or Create a shipment with rules and/or defaults and announce it synchronously (for single-collo shipments only)
Understand if your shipment was successfully announced on the carrier side	Use one of these options: Use the Create a parcel or parcels endpoint in the Parcels API, passing `"errors": "carrier-verbose"` and `"request_label": true` in the request body. If there’s a carrier error the API will respond with a `400` status code Use the Retrieve a parcel or Retrieve parcels endpoints in the Parcels API, and check the errors object	Use one of these options: Create and announce a shipment synchronously or Create a shipment with rules and/or defaults and announce it synchronously endpoints in the Shipments API, and check the errors object. Unlike API v2, if there’s a carrier error the API still returns a `200` status code. Use the Retrieve a shipment or Retrieve shipments endpoints in the Shipments API, and check the errors object
List your parcels	Use the Retrieve parcels endpoint in the Parcels API	Use the Retrieve shipments endpoint in the Shipments API
Get a specific parcel	Use the Retrieve a parcel endpoint in the Parcels API	Use the Retrieve a shipment endpoint in the Shipments API
Update your parcel	Use the Update a parcel endpoint in the Parcels API. Only supported for parcels previously announced with `request_label: false` or those that were created with a 200 code, but no label was returned (a carrier error was returned instead)	🚫 Not supported. To fix carrier errors in API v3, a new parcel needs to be created.
Cancel a parcel	Use the Cancel a parcel endpoint in the Parcels API	Use the Cancel a shipment endpoint in the Shipments API
Define what carrier service you’d like to use to ship your parcel	Use the Create a parcel or parcels endpoint in the Parcels API, passing the `shipment.id` field. To get the `shipment.id` value, you can use the Shipping methods API or the Shipping products API.	Use any Shipments API `POST` endpoint and specify the `shipping_option_code` in the `ship_with.properties` field and pass `ship_with.type: "shipping_option_code"` in the request body. To understand what `shipping_option_code`s are available for your shipment, you can use the Return a list of available shipping options endpoint in the Shipping options API. If you have hardcoded your shipping methods on your system, you can use the Compat API to match your hardcoded shipping method IDs to the equivalent shipping option codes
Understand the pricing of the carrier service you’d like to use to ship your parcel	Use one of these v2 endpoints: Retrieve a list of shipping products, passing `contract_pricing: true` and the `contract` field (with your desired carrier contract ID) in the request body Retrieve a shipping price, passing the `from_country`, `shipping_method_id`, `weight`, `weight_unit` query parameters	Use the Return a list of available shipping options endpoint in the Shipping options API
Define the address from which you’d like to ship	Use the Create a parcel or parcels endpoint in the Parcels API and either: Specify all fields prefixed with `from_` in the request body Specify the `sender_address` field to use a sender address ID already saved in the Sendcloud system	Use any Shipments API `POST` endpoint and specify the `from_address` in the request body. Note that sender address IDs are not supported in the Shipments API v3.
Define the address to which you’d like to ship	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `name`, `company_name`, `address`, `house_number`, `address_2`, `postal_code`, `city`, `to_post_number`, `country_state`, `country`, `email`, and `telephone` fields in the request body	Use any Shipments API `POST` endpoint and specify the `to_address` in the request body
Define the brand you want your parcel to be associated with	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `sender_address`. Note: In the Sendcloud Platform, one sender address ID can be linked to one brand. When announcing a parcel with that sender address ID, the associated brand will also be linked to the parcel. The same sender address ID cannot have multiple brands associated with it.	Use any Shipments API `POST` endpoint and specify the `brand_id` in the request body. To understand what brands are available for your shipment, you can use the Retrieve a list of brands endpoint.
Add insurance to your single-collo shipment	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `insured_value` or `total_insured_value` fields in the request body	Use any Shipments API `POST` endpoint and include the `additional_insured_price` field for each parcel in the request body. `additional_insured_price` is the amount for which you want to add additional insurance (on top of carrier insurance), equivalent to the `insured_value` field in the Parcels API v2 The `total_insured_value` field is not supported in v3.
Add insurance to your multicollo shipment	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `insured_value` or `total_insured_value` fields in the request body. Note that each parcel must have the same insurance value.	Use any Shipments API `POST` endpoint and include the `additional_insured_price` field for each parcel in the request body. Unlike the Parcels API v2, each parcel can have a different insurance value.
Set parcel dimensions and weight for your single-collo shipment	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `weight`, `length`, `width`, and `height` fields in the request body	Use any Shipments API `POST` endpoint and specify the `dimensions` and `weight` fields for each parcel in the request body. You can also change the weight or dimensions units using these fields.
Set parcel dimensions and weight for your multicollo shipment	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `weight`, `length`, `width`, `height` fields in the request body. Note that each parcel must have the same weight and dimensions.	Use any Shipments API `POST` endpoint and specify the `dimensions` and `weight` fields for each parcel in the request body. Unlike the Parcels API v2, each parcel can have different dimensions and a different weight.
Set the Checkout Delivery Method so any shipping rule based on it gets applied	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `shipping_method_checkout_name` field in the request body	Use either the synchronous or asynchronous Create a shipment with rules and/or defaults endpoints in the Shipments API and include the `delivery_indicator` field in the request body
Assign a shipment UUID to your parcel to connect your parcels with the orders created via the Create or update a list of shipments endpoint in the Integrations API (only available for certified Sendcloud partners)	Use the Create a parcel or parcels endpoint in the Parcels API and specify the `shipment_uuid` field in the request body	Not applicable. Orders are automatically associated with a shipment when announced via the the Request a label for a single order synchronously or Request a label for one or more orders asynchronously endpoints.
Retrieve your label after announcement - Native ZPL label^*	🚫 Not supported	Use one of these options: Retrieve a parcel document, with the `type` path parameter set to `label` and the `Accept` header set to `application/zpl` Use the response from Create and announce a shipment synchronously or Create a shipment with rules and/or defaults and announce it synchronously (for single-collo shipments only)
Define a label note to either show on the label or on be communicated to the carrier without showing on the label (depending on the carrier)	🚫 Not supported	Use any Shipments API `POST` endpoint and specify the `label_notes` field for each parcel in the request body
Set the SSCC field when shipping a pallete	🚫 Not supported	Use any Shipments API `POST` endpoint and specify the `sscc` field for each parcel in the request body
Define when you’d like the shipment to be picked up by the carrier	🚫 Not supported	Use any Shipments API `POST` endpoint and specify the `delivery_dates.handover_at` field in the request body
Define when you’d like the shipment to be delivered to your customer	🚫 Not supported	Use any Shipments API `POST` endpoint and specify the `delivery_dates.deliver_at` field in the request body

^* Native ZPL labels are only supported for a few selected carriers. As of 1/12/2025: Asendia, Bring, BRT, Colis Privé, Colissimo, DHL eCommerce Benelux, DHL Germany, Inpost Poland, Ontime, PLX Parcel Logistics, Trunkrs, UPS

Returns

In API v2, returns were handled via the Parcels API. In API v3, there is a dedicated Returns API to make managing returns easier. We’ve also introduced the possibility to validate return shipments before creating them.

Action	API v2	API v3
Create a return (asynchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label_async: true`, `is_return: true`, setting the `from_`-prefixed fields in the request body, and setting a shipping method that supports returns.	Use the Create a return endpoint in the Returns API
Create a return (synchronously)	Use the Create a parcel or parcels endpoint in the Parcels API, passing `request_label_async: true`, `is_return: true`, setting the `from_`-prefixed fields in the request body, and setting a shipping method that supports returns.	Use the Create a return synchronously endpoint in the Returns API
Retrieve a list of returns	Use the Retrieve parcels endpoint in the Parcels API	Use the Retrieve a list of returns endpoint in the Returns API
Retrieve a return	Use the Retrieve a parcel endpoint in the Parcels API	Use the Retrieve a return endpoint in the Returns API
Request cancellation of a return	Use the Cancel a parcel endpoint in the Parcels API	Use the Request cancellation of a return endpoint in the Returns API
Validate a return	🚫 Not supported	Use the Validate a return endpoint in the Returns API
Retrieve a return portal URL	Use the Retrieve a return portal URL endpoint in the Parcels API	🚫 Not supported yet, but implementation is ongoing.

Contracts

In the v3 version of the Contracts API, we’ve added support for creating, updating, and deleting carrier contracts via the API.

Action	Contracts API v2	Contracts API v3
List all your contracts	Use the v2 Retrieve a list of contracts endpoint	Use the v3 Retrieve a list of contracts endpoint. Unlike the Contracts API v2, this endpoint uses cursor-based pagination.
Retrieve a specific contract	Use the v2 Retrieve a contract endpoint	Use the v3 Retrieve a contract endpoint
Create a contract for carrier	🚫 Not supported	Use the Create a contract for a carrier endpoint. To help with creating contracts, use the Retrieve a list of contract schemas endpoint.
Update a contract	🚫 Not supported	Use the Update a contract endpoint. To help with updating contracts, use the Retrieve a list of contract schemas endpoint.
Delete a contract	🚫 Not supported	Use the Delete a contract endpoint

Pickups

In the v3 version of the Pickups API, we’ve expanded support to include several new carriers that were not available in v2. There have also been some field changes between the Pickups API v2 and Pickups API v3. Please refer to the pickup fields section for more details.

Action	Pickups API v2	Pickups API v3
List all pickups	Use the v2 Retrieve a list of pickups endpoint	Use the v3 Retrieve a list of pickups endpoint
Get a specific pickup	Use the v2 Retrieve a pickup endpoint	Use the v3 Retrieve a pickup endpoint
Create a pickup for Correos Express	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for DHL	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for DHL Parcel Iberia	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for DPD	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for FedEx	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for Poste Italiane	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for UPS	Use the v2 Create a pickup endpoint	Use the v3 Create a pickup endpoint
Create a pickup for BRT	🚫 Not supported	Use the v3 Create a pickup endpoint
Create a pickup for DPD AT	🚫 Not supported	Use the v3 Create a pickup endpoint
Create a pickup for DHL DE	🚫 Not supported	Use the v3 Create a pickup endpoint
Create a pickup for DHL Express	🚫 Not supported	Use the v3 Create a pickup endpoint
Create a pickup for DHL Parcel GB	🚫 Not supported	Use the v3 Create a pickup endpoint
Create a pickup for GLS Italy	🚫 Not supported	Use the v3 Create a pickup endpoint
Create a pickup for Hermes Germany	🚫 Not supported	Use the v3 Create a pickup endpoint

Tracking

The Tracking API v2 is replaced with the Parcel tracking API v3, which has an improved response structure, and supports creating external tracking parcels.

Action	Tracking API v2	Parcel tracking API v3
Get tracking information for a parcel	Use the Retrieve tracking information of a parcel endpoint	Use the Retrieve tracking information for a parcel endpoint
Create an external parcel for tracking	🚫 Not supported	Use the Create an external parcel for tracking endpoint

Dynamic Checkout

The Dynamic Checkout API v2 is replaced with the Dynamic Checkout API v3, which contains references to the Shipments API v3 instead of the Parcels API v2, and can be used with codes from the Shipping options API. Error responses also now comply with the JSON:API standard for error objects.

Action	Dynamic Checkout API v2	Dynamic Checkout API v3
Get a list of delivery options to display in your shop’s checkout page	Use the v2 Retrieve a list of delivery options endpoint	Use the v3 Retrieve a list of delivery options endpoint

Service Points

Service Points API v3 makes service point discovery more explicit and predictable. Carrier selection must now be stated in the request, address searches return clearer geocoding results, and service point data uses a more structured response schema.

Base URL

Service Points API v3 uses the same domain as the other API v3 endpoints:

v2: https://servicepoints.sendcloud.sc/api/v2
v3: https://panel.sendcloud.sc/api/v3

Make sure to update both the API version and the host when migrating your Service Points API calls.

Client-side integrations

Service Points API v2 also supported authentication through the access_token parameter. The access token was based on the integration public key and was considered safe to expose, which allowed the API to be called directly from client-side applications such as a service point picker running in a web browser. This authentication method is not available in v3. Service Points API v3 uses regular API credentials, which are secret and must only be used from a backend. If your integration currently calls Service Points API v2 directly from a web browser using access_token, you will need to proxy these calls through your backend. The backend can authenticate with Service Points API v3 using one of the supported methods.

Endpoint changes

Action	API v2	API v3
Search service points	Use the v2 Retrieve a list of service points endpoint	Use the v3 Retrieve a list of service points endpoint
Retrieve a service point	Use the v2 Retrieve a service point endpoint	Use the v3 Retrieve a service point endpoint
Check service point availability	Use the v2 Retrieve availability of a service point endpoint	Use the v3 Check availability of a service point endpoint
Retrieve carriers enabled for service point delivery	Use the v2 Retrieve a list of service point carriers endpoint	🚫 There is no dedicated equivalent in Service Points API v3. Use the `service_point_carriers` field returned by Retrieve an integration endpoint to get the carriers enabled for an integration.

Changes to service point search

Request parameters

Several query parameters have been renamed, replaced, or removed in API v3.

API v2	API v3	Change
`country`	`country_code`	Renamed
`carrier`	`carrier_code`	Changed from a comma-separated string to repeated query parameters
🚫 Not supported	`use_integration_carriers`	Explicit alternative to `carrier_code`. See Carrier selection below for details
`city`, `postal_code`, `house_number`	`address_city`, `address_postal_code`, `address_house_number`	Replaced with structured address input for geocoding rather than exact service point filters. See Address search and geocoding below for details
🚫 Not supported	`address_street`	New structured address component. In v2, street matching was only possible via the free-text `address` parameter
`pudo_id`	`carrier_service_point_id`	Replaced with a carrier-agnostic service point identifier filter that also supports multiple values
`shop_type`	`carrier_shop_type`	Renamed
`general_shop_type`	`general_shop_type`	Changed from a comma-separated list to repeated query parameters
`weight`	🚫 Not supported	Removed
🚫 Not supported	`limit`	New parameter that limits the number of service points returned, with a default of `100` and a maximum of `200`

Response structure

Service Points API v3 follows the common v3 response structure. The list endpoint no longer returns a bare array of service points. Results are returned under data.results, with additional information about address geocoding available under data.geocoding. The Service point object itself has also been restructured. Related fields are grouped into carrier, address, position, and contact objects. Carrier information now includes the carrier name, logo, and icon in addition to its code.

API v2 response

[
  {
    "id": 10875349,
    "carrier": "postnl",
    "street": "Voorbeeldstraat",
    "city": "EINDHOVEN",
    "latitude": "51.441444",
    "longitude": "5.475185",
    <...>
  }
]

API v3 response

{
  "data": {
    "results": [
      {
        "id": 10875349,
        "carrier": {
          "code": "postnl",
          "name": "PostNL",
          "logo_url": <...>,
          "icon_url": <...>
        },
        "address": {
          "street": "Voorbeeldstraat",
          "city": "Eindhoven",
          <...>
        },
        "position": {
          "latitude": 51.441444,
          "longitude": 5.475185
        },
        "contact": {
          <...>
        },
        <...>
      }
    ],
    "geocoding": {
      <...>
    }
  }
}

See the Service point fields section for a complete mapping of v2 fields to their v3 equivalents.

Carrier selection

Service Points API v3 requires carrier selection to be explicit. A request must either use the carriers enabled in the API integration or specify the carrier codes to search for.

Scenario	API v2	API v3
Use carriers enabled in integration settings	Omit `carrier`	Set `use_integration_carriers=true`
Search for specific carriers	Set `carrier` to the requested carrier codes. All requested carriers must be enabled in integration settings	Set `carrier_code` to the requested carrier codes. These codes are not validated against integration settings

For example, to search using the carriers enabled in the integration:

API v2 - integration carriers

?country=NL

API v3 - integration carriers

?country_code=NL&use_integration_carriers=true

To search for specific carriers:

API v2 - specific carriers

?country=NL&carrier=postnl,dhl

API v3 - specific carriers

?country_code=NL&carrier_code=postnl&carrier_code=dhl

Unlike v2, carriers requested with carrier_code in v3 do not need to be enabled in the integration settings.

Address search and geocoding

Both Service Points API v2 and v3 allow you to search for service points near an address. The address is geocoded into geographic coordinates, which are then used as the reference point for the search. In v2, address is used for geocoding, while city, postal_code, and house_number behave differently: they filter service points by exact values stored in the database. This makes them sensitive to spelling and formatting differences and easy to confuse with address-based search. In v3, these strict filters are removed. In addition to the existing free-text address parameter, the reference address can be provided as separate components:

address_street
address_house_number
address_postal_code
address_city

All address_* parameters are used for geocoding and do not filter service point address fields directly. Providing the address as separate components can improve geocoding accuracy by removing ambiguity from a free-text address and giving the geocoding service more structured input. Geocoding results v3 also exposes the outcome of address geocoding through data.geocoding. In v2, different geocoding outcomes could result in the same 400 response, making it difficult to tell whether an address was not found, only partially matched, or the geocoding service itself failed. In v3:

matched means the address was successfully resolved.
partially_matched means only part of the supplied address could be resolved. The matched location is still used for the service point search.
not_found means the address could not be resolved and no service points are returned.
If the geocoding service is temporarily unavailable, the API returns 503 Service Unavailable.

For a resolved address, data.geocoding.precision indicates how precisely the address was matched, while data.geocoding.formatted_address contains the canonical address corresponding to the resolved location. For example, if a full address can only be resolved to its postal code, the request still succeeds and the search uses that broader location:

Partially matched address

{
  "data": {
    "results": [
      <...>
    ],
    "geocoding": {
      "status": "partially_matched",
      "precision": "postal_code",
      "formatted_address": "5611, Eindhoven, Noord-Brabant, Nederland"
    }
  }
}

If the address cannot be resolved at all, no service points are returned:

Address not found

{
  "data": {
    "results": [],
    "geocoding": {
      "status": "not_found",
      "precision": null,
      "formatted_address": null
    }
  }
}

Analytics

The Analytics API v2 is replaced with the Analytics API v3 (BETA). Endpoints now live under /analytics/... instead of /insights/..., accept arrays for the carrier, shipping option, and country filters, and shipping methods are replaced by shipping options. Country filters are renamed from_country_code / to_country_code to match other v3 APIs.

Action	Analytics API v2	Analytics API v3
Retrieve carrier transit times	Use the v2 Retrieve carrier transit times endpoint	Use the v3 Retrieve carrier transit times endpoint
Retrieve shipping option transit times	Use the v2 Retrieve shipping method transit times endpoint	Use the v3 Retrieve shipping option transit times endpoint

Reporting

The Reporting API v2 is replaced with the Reporting API v3, which references shipping options instead of shipping methods, uses from_address_* / to_address_* field naming to match other v3 APIs, and returns errors in the JSON:API format. There have also been some field changes between the Reporting API v2 and Reporting API v3. Please refer to the reporting fields section for more details.

Action	Reporting API v2	Reporting API v3
Create a parcels report	Use the v2 Create a parcels report endpoint	Use the v3 Create a parcels report endpoint
Retrieve a parcels report	Use the v2 Retrieve a parcels report endpoint	Use the v3 Retrieve a parcels report endpoint

What stayed the same?

Webhooks

There are no changes to webhooks between API v2 and API v3. Additionally, the new Event Subscriptions API (BETA) provides a programmatic alternative for subscribing to parcel events. It supports multiple connection types (webhook, Klaviyo) and configurable authentication, giving you more flexibility than the classic webhook setup.

API v2 endpoints that are compatible with API v3

Currently only the Return portal API API v2 endpoint doesn’t yet have an API v3 equivalent, but can still be used together with any API v3 endpoint.

Field changes between API v2 and API v3

Shipment/Parcel fields

Parcels API v2	API v3
`order_number`	`order_number`
`contract`	`ship_with.properties.contract_id`
`total_order_value_currency`	`total_order_price.currency`
`total_order_value`	`total_order_price.value`
`external_reference`	`external_reference_id`
`reference`	`reference`
`to_service_point`	`to_service_point.id`

Address fields

Parcels API v2	API v3
`name`	`to_address.name`
`company_name`	`to_address.company_name`
`address`	`to_address.address_line_1`
`house_number`	`to_address.house_number`
`address_2`	`to_address.address_line_2`
`postal_code`	`to_address.postal_code`
`city`	`to_address.city`
`to_post_number`	`to_address.po_box`
`country_state`	`to_address.state_province_code`
`country`	`to_address.country_code`
`email`	`to_address.email`
`telephone`	`to_address.phone_number`
`from_name`	`from_address.name`
`from_company_name`	`from_address.company_name`
`from_address_1`	`from_address.address_line_1`
`from_house_number`	`from_address.house_number`
`from_address_2`	`from_address.address_line_2`
`from_postal_code`	`from_address.postal_code`
`from_city`	`from_address.city`
🚫 Not supported	`from_address.po_box`
🚫 Not supported	`from_address.state_province_code`
`from_country`	`from_address.country_code`
`from_email`	`from_address.email`
`from_telephone`	`from_address.phone_number`

Parcel item fields

Parcels API v2	Shipments API v3
`parcel_items.hs_code`	`parcels.parcel_items.hs_code`
`parcel_items.weight`	`parcels.parcel_items.weight.value`
🚫 Not supported	`parcels.parcel_items.weight.unit`
`parcel_items.quantity`	`parcels.parcel_items.quantity`
`parcel_items.description`	`parcels.parcel_items.description`
`parcel_items.origin_country`	`parcels.parcel_items.origin_country`
`parcel_items.value`	`parcels.parcel_items.price.value`
🚫 Not supported	`parcels.parcel_items.price.currency`
`parcel_items.sku`	`parcels.parcel_items.sku`
`parcel_items.product_id`	`parcels.parcel_items.product_id`
`parcel_items.properties`	`parcels.parcel_items.properties`
`parcel_items.item_id`	`parcels.parcel_items.item_id`
`parcel_items.return_reason`	Not applicable, as in v3 returns are created via the Returns API v3. More context on how to create returns
`parcel_items.return_message`	Not applicable, as in v3 returns are created via the Returns API v3. More context on how to create returns
`parcel_items.mid_code`	`parcels.parcel_items.mid_code`
`parcel_items.material_content`	`parcels.parcel_items.material_content`
`parcel_items.intended_use`	`parcels.parcel_items.intended_use`
`parcel_items.dangerous_goods`	`parcels.parcel_items.dangerous_goods`

Shipping methods vs. Shipping products vs. Shipping prices vs. Shipping options fields

Shipping methods API v2	Shipping products API v2	Shipping prices API v2	Shipping options API v3
`from_postal_code`	`from_postal_code`	`from_postal_code`	`from_postal_code`
`is_return`	`returns`	🚫 Not supported	`functionalities.returns`
`sender_address`	🚫 Not supported	🚫 Not supported	🚫 Not supported
`service_point_id`	🚫 Not supported	🚫 Not supported	`to_service_point_id`
`to_country`	`to_country`	`to_country`	`to_country_code`
`to_postal_code`	`to_postal_code`	`to_postal_code`	`to_postal_code`
🚫 Not supported	`carrier`	🚫 Not supported	`carrier_code`
🚫 Not supported	`contract`	`contract`	`contract_id`
🚫 Not supported	`contract_pricing`	Pricing is always calculated	`calculate_quotes`
🚫 Not supported	`height`	🚫 Not supported	`parcels.dimensions.height`
🚫 Not supported	`height_unit`	🚫 Not supported	`parcels.dimensions.unit`
🚫 Not supported	`length`	🚫 Not supported	`parcels.dimensions.length`
🚫 Not supported	`length_unit`	🚫 Not supported	`parcels.dimensions.unit`
🚫 Not supported	`width`	🚫 Not supported	`parcels.dimensions.width`
🚫 Not supported	`width_unit`	🚫 Not supported	`parcels.dimensions.unit`
🚫 Not supported	`lead_time_hours`	🚫 Not supported	`lead_time`
🚫 Not supported	`weight`	`weight` (Required)	`parcels.weight.value`
🚫 Not supported	`weight_unit`	`weight_unit` (Required)	`parcels.weight.unit`
🚫 Not supported	`from_country` (Required)	`from_country` (Required)	`from_country_code`
🚫 Not supported	🚫 Not supported	`shipping_method_id` (Required)	`shipping_product_code` OR `shipping_option_code`
🚫 Not supported	🚫 Not supported	🚫 Not supported	`parcels.additional_insured_price`
🚫 Not supported	🚫 Not supported	🚫 Not supported	`parcels.total_insured_price`
🚫 Not supported	🚫 Not supported	🚫 Not supported	`functionalities`

Customs fields

Parcels API v2	Shipments API v3
`customs_invoice_nr`	`invoice_number`
`customs_shipment_type`	`export_reason`
`export_type`	`export_type`
`invoice_date`	`invoice_date`
`discount_granted`	`discount_granted`
`freight_costs`	`freight_costs`
`insurance_costs`	`insurance_costs`
`other_costs`	`other_costs`
`general_notes`	`general_notes`
`additional_declaration_statements`	`additional_declaration_statements`
`importer_of_record`	`importer_of_record`
`tax_numbers`	`tax_numbers`
`return_data`	Not applicable as in v3, returns are created via the Returns API v3. More context on how to create returns

Contracts fields

Contracts API v2	Contracts API v3
`carrier`	`carrier_code`
`client_id`	`client_id`
`country`	`country_code`
`is_active`	`is_active`
`name`	`name`
`is_default`	`is_default_per_carrier`

Pickups fields

Pickups API v2	Pickups API v3
`id`	🚫 Not supported
`carrier`	`carrier_code`
`country`	`address.country_code`
`city`	`address.city`
`name`	`address.name`
`country_state`	`address.state_province_code`
`company_name`	`address.company_name`
`email`	`address.email`
`address`	`address.address_line_1`
`address_2`	`address.address_line_2`
`postal_code`	`address.postal_code`
`telephone`	`address.phone_number`
🚫 Not supported	House number should be provided as part of the address field (`address.house_number`)
🚫 Not supported	`address.po_box`
`quantity`	`items.quantity`
`total_weight`	`items.total_weight.value`
🚫 Not supported	`items.total_weight.unit`
🚫 Not supported	`items.container_type`
`reference`	`reference`
`special_instructions`	`special_instructions`
`tracking_number`	🚫 Not supported
`pickup_from`	`time_slots.start_at`
`pickup_until`	`time_slots.end_at`
`pickup_status`	🚫 Not supported
`created_at`	🚫 Not supported
`cancelled_at`	🚫 Not supported
`contract`	`contract_id`

Reporting fields

The values you can pass in the fields array and the columns that appear in the CSV have been renamed to match the rest of the v3 APIs.

Reporting API v2	Reporting API v3
`from_company_name`	`from_address_company_name`
`origin_city`	`from_address_city`
`origin_postal_code`	`from_address_postal_code`
`origin_country_code`	`from_address_country_code`
`origin_country_name`	`from_address_country_name`
`destination_city`	`to_address_city`
`destination_postal_code`	`to_address_postal_code`
`destination_country_code`	`to_address_country_code`
`destination_country_name`	`to_address_country_name`
`shipping_method`	`shipping_option_code`
`shipping_method_name`	🚫 Not supported
`price`	`total_cost`
`global_status_slug`, `carrier_status`	`status` (merges the global and carrier-reported status into one field)
`global_sub_status_slug`, `carrier_sub_status`	`sub_status` (merges the global and carrier-reported sub-status into one field)
`arrived_at`	`delivered_at`
`first_delivery_at`	`first_offer_at`
`created_at`	🚫 Not supported (use `announced_at`)
`updated_at`	🚫 Not supported

The filters object follows the same renames where applicable. announced_after and announced_before are now required.

Dynamic Checkout fields

API v2	API v3
`method_id`	Use `checkout_identifier` with `shipping_option_code` instead

Service point fields

Service Points API v2	Service Points API v3
`id`	`id`
`code`	`carrier_service_point_id`
`carrier`	`carrier.code`
🚫 Not supported	`carrier.name`, `carrier.logo_url`, `carrier.icon_url`
`shop_type`	`carrier_shop_type`
`general_shop_type`	`general_shop_type`
`street`	`address.street`
`house_number`	`address.house_number`
`postal_code`	`address.postal_code`
`city`	`address.city`
`country`	`address.country_code`
`latitude`	`position.latitude` (now a number instead of a string)
`longitude`	`position.longitude` (now a number instead of a string)
`email`	`contact.email`
`phone`	`contact.phone`
`homepage`	🚫 Not supported
`formatted_opening_times`	`opening_times` (see note below)
`open_tomorrow`	`is_open_tomorrow`
`open_upcoming_week`	🚫 Not supported, use `next_open_at` instead (see note below)
`distance`	`distance`
`is_active`	🚫 Not supported, use `is_expired` instead (meaning inverted, see note below)
`extra_data`	🚫 Not supported
🚫 Not supported	`is_expired`
🚫 Not supported	`next_open_at`

Notable field changes

is_active → is_expired

is_expired replaces is_active with inverted semantics. In v2, is_active indicated whether the service point data was still considered fresh, rather than whether the service point was operational. The field name was therefore misleading. In v3, is_expired: true explicitly means that the service point data is stale.

open_upcoming_week → next_open_at

v2 only indicated whether the service point would be open at least once within the next 7 days. v3 instead returns the actual date and time when the service point is expected to open next.

formatted_opening_times → opening_times

Opening times have a clearer and stricter structure in v3. Weekday keys change from numbers to names, and opening hours change from formatted time-range strings to {start_time, end_time} objects. In v2, a closed day is represented as an empty array ([]). In v3, a closed day is always null, while an array always contains at least one opening interval.

API v2 opening times

{
  "0": ["09:00 - 12:00", "13:00 - 17:00"],
  <...>
  "6": []
}

API v3 opening times

{
  "monday": [
    { "start_time": "09:00", "end_time": "12:00" },
    { "start_time": "13:00", "end_time": "17:00" }
  ],
  <...>
  "sunday": null
}

Sender address fields

Parcels API	Shipments API
`city`	`city`
`company_name`	`company_name`
`contact_name`	`name`
`country`	`country_code`
`country_state`	`state_province_code`
`email`	`email`
`house_number`	`house_number`
`id`	`id`
`postal_box`	`po_box`
`postal_code`	`postal_code`
`street`	`address_line_1`
`telephone`	`phone_number`
`vat_number`	`tax_numbers` object `tax_number.name` `tax_number.country_code` `tax_number.value`
`eori_number`	`tax_numbers` object `tax_number.name` `tax_number.country_code` `tax_number.value`
🚫 Not supported	`tax_numbers`
🚫 Not supported	`brand_id`
🚫 Not supported	`label`
`signature_full_name`	`signature` object with `signature.full_name`
`signature_initials`	`signature` object with `signature.initials`
🚫 Not supported	`address_line_2`

​Why should you migrate to API v3?

​Exclusive API v3 Features

​What’s changed?

​Managing orders

​Shipping an existing order (creating labels)

​Shipments API v3 vs Ship an Order API v3

​Integrations

​Parcels/Shipments

​Returns

​Contracts

​Pickups

​Tracking

​Dynamic Checkout

​Service Points

​Base URL

​Client-side integrations

​Endpoint changes

​Changes to service point search