Migration guidelines for API v3

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.

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

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

Some API v2 endpoints don’t yet have an API v3 equivalent, but can still be used together with any API v3 endpoint. Here’s a list of those endpoints:

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

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`

Getting started

Shipments

Addresses

Orders

Dynamic Checkout

Returns

Service points

Parcel tracking

Marketplaces

Archive

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

Analytics

Reporting

What stayed the same?

Webhooks

API v2 endpoints that are compatible with API v3

Field changes between API v2 and API v3

Shipment/Parcel fields

Address fields

Parcel item fields

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

Customs fields

Contracts fields

Pickups fields

Reporting fields

Dynamic Checkout fields

Sender address fields

​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

​Analytics

​Reporting

​What stayed the same?

​Webhooks

​API v2 endpoints that are compatible with API v3

​Field changes between API v2 and API v3

​Shipment/Parcel fields

​Address fields

​Parcel item fields

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

​Customs fields

​Contracts fields

​Pickups fields

​Reporting fields

​Dynamic Checkout fields

​Sender address fields

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

Analytics

Reporting

What stayed the same?

Webhooks

API v2 endpoints that are compatible with API v3

Field changes between API v2 and API v3

Shipment/Parcel fields

Address fields

Parcel item fields

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

Customs fields

Contracts fields

Pickups fields

Reporting fields

Dynamic Checkout fields

Sender address fields