# Finalize a Deutsche Post order Source: https://sendcloud.dev/api/v2/air-waybill/finalizing-a-box /.openapi/v2/air-waybill/openapi.yaml post /box/finalize Finalize a Deutsche Post order by closing the current open box and generating an AWB (Air Waybill) document for all parcels in that box. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This endpoint closes the current open order/box and generates an AWB (Air Waybill) document for all parcels in that box. **How it works:** 1. As you create Deutsche Post International parcels, they are automatically added to the current box (identified by the current box\_number). 2. When the box is full or you're ready to ship, call this endpoint to finalize the box. 3. The finalization process generates a single AWB label that is shared by all parcels in the finalized box and increments the box\_number, automatically starting a new box for subsequent parcels. 4. You can create and finalize multiple boxes throughout the day as needed. **Parameters:** * `copy_count`: Specify how many AWB copies you need (1-99). Use this if the parcels are split over multiple physical boxes or pallets. **Response:** When the request is successful, a `200` code will be returned with the `copy_count` requested. The AWB is generated and you can retrieve the AWB label from any parcel that was in the finalized box, as the AWB label is identical for all parcels included in the box. # Air Waybill API overview Source: https://sendcloud.dev/api/v2/air-waybill/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Parcels shipped with Deutsche Post International shipping methods require an **Air Waybill (AWB)** to facilitate the first leg journey by air freight to the International Mail Center in Frankfurt. The Air Waybill API allows you to create an AWB for multiple Deutsche Post International parcels that are shipped together in one box or pallet. 1. Parcels are created and receive individual shipping labels 2. At the end of the day, the parcels are announced as one **box** and an AWB is created 3. The individual parcels are labelled, and physically added to the **box** or pallet 4. The AWB is attached to the outside of the box or pallet, and the parcels are shipped together as one consignment 5. At the International Mail Center, the box is opened and the individual parcels are sorted and shipped on to their intended destinations. > Parcels can be created either via the Sendcloud platform or via the API. You can find the full process for creating DP parcels via the Sendcloud platform on our **Help Center**. ## Creating Deutsche Post International parcels via the Sendcloud API 1. Deutsche Post International parcels are created using the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. 2. The box is automatically initiated along with the first parcel of the day. 3. You can retrieve the box number via the [Retrieve parcels](/api/v2/parcels/retrieve-parcels) or [Retrieve a parcel](/api/v2/parcels/retrieve-a-parcel) endpoints. 4. Throughout the day, as you continue to create DP International parcels, they are all added to the same daily box. 5. At the end of the day, when you're ready to send the box, finalize it by calling the [Finalizing a box](/api/v2/air-waybill/finalizing-a-box) endpoint. 6. Once the box is finalized, the AWB is generated, alongside tracking numbers and labels for the individual parcels inside the box. 7. After a few minutes, the AWB label and tracking number can be retrieved via any single parcel that you have created throughout the day 8. The next day, the process starts again when you create the first Deutsche Post International parcel. # Analytics API overview Source: https://sendcloud.dev/api/v2/analytics/index The Analytics API lets you query for insights about transit times. # Retrieve carrier transit times Source: https://sendcloud.dev/api/v2/analytics/retrieve-carrier-transit-times /.openapi/v2/analytics/openapi.yaml get /insights/carriers/transit-times Retrieves the average transit time of a parcel per carrier. You can filter the results by origin and destination country, as well as by start and end dates. # Retrieve shipping method transit times Source: https://sendcloud.dev/api/v2/analytics/retrieve-shipping-method-transit-times /.openapi/v2/analytics/openapi.yaml get /insights/shipping-methods/transit-times Retrieves the average transit time of a parcel per shipping method and carrier. You can filter the results by origin and destination country, as well as start and end dates. # Retrieve a brand Source: https://sendcloud.dev/api/v2/brands/retrieve-a-brand /.openapi/v2/brands/openapi.yaml get /brands/{id} Retrieves a user's configured brand and its properties, identified by its unique ID **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a list of brands Source: https://sendcloud.dev/api/v2/brands/retrieve-a-list-of-brands /.openapi/v2/brands/openapi.yaml get /brands Retrieves a list of all brands and their associated properties. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # API v2 changelog Source: https://sendcloud.dev/api/v2/changelog ## Changed endpoints: * Changes for **POST** `/api/v2/parcels` and **PUT** `/api/v2/parcels/{id}`: * Field `manufacturer_product_id` added to parcel item object (nullable string, max 70 chars) * Field `manufacturer_product_id_std` added to parcel item object (nullable string, max 70 chars, for standardized identifiers such as GTIN) The [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint in the Parcels API is now in maintenance mode. It is **closed to new users** (any user with a Sendcloud account created after April 13th 2026) and will not receive further updates. Read more about [maintenance mode](/docs/getting-started/api-version-guide). Existing users can continue to use this endpoint, but we recommend migrating to API v3 for the latest features and improvements. See our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3) for more information. ## Affected endpoints: * **POST** `/parcels` ## Changed endpoints: * **GET** `/insights/parcels/series`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/insights/products/series`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/insights/parcels/buckets`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/insights/products/buckets`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/insights/parcels/counts-summary`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/analytics/shipping-methods`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/analytics/carriers`: Endpoint is now publicly visible (removed `x-excluded` flag) ## Changed endpoints: * **POST** `/shipping-price/multiple`: Endpoint is now publicly visible (removed `x-excluded` flag) ## Changed endpoints: * **GET** `/brand/{brand_domain}/return-portal/customs-declaration/download`: Endpoint is now publicly visible (removed `x-excluded` flag) ## Changed endpoints: * **POST** `/service-points/check_and_store`: Endpoint is now publicly visible (removed `x-excluded` flag) * **POST** `/service-points/items_fit_in_shipment`: Endpoint is now publicly visible (removed `x-excluded` flag) * **GET** `/service-points/{shop_type}/store`: Endpoint is now publicly visible (removed `x-excluded` flag) * Parameter `order_id`: Example value changed from integer `123456789` to string `'123456789'` * Parameter `service_point`: Example value changed from integer `1` to string `'1'` * Parameter `to_post_number`: Example value changed from integer `1338` to string `'1338'` ## Changed endpoints: * Changes to `OriginDetail` schema: * Field `company_close_time`: Example value updated to include timezone (`17:00:00Z`) ## Changed endpoints: * Changes to `ParcelsReport` schema: * Field `expires_at`: Example value updated to include timezone (`2022-07-14T08:38:10.226217Z`) * Field `updated_at`: Example value updated to include timezone (`2022-07-14T08:23:10.226265Z`) * Field `created_at`: Example value updated to include timezone (`2022-07-14T08:23:10.226265Z`) ## Changed endpoints: * **GET** `/users/me`: * Field `registered`: Example value updated to ISO 8601 format with timezone (`2022-04-06T11:29:37Z`) ## Changed endpoints: * Changes to `IntegrationWebhookBase` schema: * Field `integration.failing_since`: Example value updated to include timezone (`2019-02-03T06:48:07Z`) * Field `integration.last_fetch`: Example value updated to include timezone (`2019-02-03T06:48:07Z`) * Field `integration.last_updated_at`: Example value updated to include timezone (`2019-02-03T06:48:07Z`) ## Changed endpoints: * Changes for **POST** `/api/v2/webhooks/parcel-status-changed`: * Request schema `ParcelStatusChangedWebhook` changed: * Field `action` added to `IntegrationWebhookBase` * Changes for **POST** `/api/v2/webhooks/return-created`: * Request schema `ReturnCreatedWebhook` changed: * Field `action` added to `IntegrationWebhookBase` ## Changed endpoints: * Changes for **POST** `/oauth2/token`: * Request body `application/x-www-form-urlencoded` schema changed: * Field `grant_type` moved from property-level required to schema-level required ## Changed endpoints: * Changes for **GET** `/service-points`: * Parameter `carrier` description updated to clarify carrier filtering and validation requirements * Parameter `address` description updated with geocoding details and guidance on parameter combinations * Parameter `city` description updated to emphasize exact matching requirement * Parameter `postal_code` description updated to clarify exact matching behavior * Parameter `house_number` description updated to emphasize exact matching requirement * Parameter `radius` description updated for clarity * Parameter `weight` description updated to specify Poste Italiane weight limit behavior * Parameter `pudo_id` description updated to clarify DPD-specific usage * Parameter `shop_type` description updated to distinguish from `general_shop_type` * Parameter `general_shop_type` description updated to clarify normalized filtering * Response `200` example `RetrieveServicePoints` renamed to `FullResponse` with updated example data * Response `200` added new example `MinimalResponse` showing minimal service point data * Endpoint description updated with new "How carriers are selected" section * Changes for **GET** `/service-points/{service_point_id}`: * Response `200` example updated with new example data * Field `distance` removed from single service point response example * Changes for **GET** `/carriers`: * Response `200` schema description added * Response `200` items schema description added * Response `200` example updated with additional carrier codes * Response `404` removed * Changes for **service-point** schema: * Field `id` description added * Field `code` description added * Field `shop_type` description added * Field `extra_data` description updated to clarify carrier-specific nature and lack of fixed structure * Field `name` description added * Field `street` description added * Field `house_number` description added * Field `postal_code` description added * Field `city` description added * Field `latitude` description added * Field `longitude` description added * Field `email` description added * Field `phone` description added * Field `homepage` description added * Field `carrier` description added * Field `country` description added * Field `formatted_opening_times` description updated with detailed explanation of dynamic computation and exception handling * Field `distance` description updated to clarify conditional return behavior * Field `distance` removed from required fields list * Schema example updated with new example data * Changes for **400** error response: * Response schema properties descriptions added to `code`, `request`, and `message` fields * Response examples added: `RequiredFieldMissing`, `AddressGeocodeFailure`, `CarrierNotEnabled`, `RadiusWithBoundingBox` ## Changed endpoints: * Changes for **POST** `/delivery-options`: * Response `200` / `application/json` changed: * Field `lead_time_hours` added to service point delivery options * Field `sustainability_rating` added to service point delivery options * Field `is_order_overweight` added to service point delivery options * Field `allowed_weight` added to service point delivery options * Schema `DeliveryOption` description updated: * Reference link updated from `/api/v2/create-a-parcel-or-parcels` to `/api/v2/parcels/create-a-parcel-or-parcels` ## Changed endpoints: * Changes for **POST** `/box/finalize`: * Summary changed from "Finalizing a box" to "Finalize a Deutsche Post order" * Description updated to clarify the endpoint closes the current open box and generates an AWB document * Documentation (`x-mint.content`) updated with clearer workflow explanation and parameter details ## Changed endpoints: * Changes for **GET** `/api/v2/user/invoices/{id}`: * Description updated for clarity on retrieving detailed invoice information * Changes for `Invoice` schema: * Field `type` enum values updated: * `periodical` changed to `periodic` * `initial` changed to `initial_payment` * `other` removed and re-ordered to end of enum * `credit_limit` added * Field `type` description updated with new invoice type definitions * Field `price_incl` example changed from `5.5` to `6.5` * Field `price_excl` example changed from `6.5` to `5.5` * Field `date` description changed from "The creation date of the invoice" to "The creation datetime of the invoice" * Field `items` description changed from "Link to the invoice" to "Link to retrieve invoice items of this invoice" * Changes for `InvoiceDetail` schema: * Field `type` description and enum values incomplete (schema appears truncated in specification) ## Changed endpoints: * Changes for **POST** `/box/finalize`: * Description updated: Documentation references changed from "Sendcloud platform" to "Sendcloud panel" * Changes for **GET** `/checkout/configurations/{configuration_id}/delivery-options`: * Description updated: Documentation references changed from "Sendcloud platform" to "Sendcloud panel" * Schema documentation updated: References to "Sendcloud platform" changed to "Sendcloud panel" in delivery options, shipping rates, and delivery dates descriptions * Changes for **POST** `/shipments`: * Description updated: Documentation references changed from "Sendcloud platform" to "Sendcloud panel"; carrier count updated from "160+" to "80+" * Changes for **GET** `/parcels/statuses`: * Description updated: Documentation references changed from "Sendcloud platform" to "Sendcloud panel" * Changes for **POST** `/parcels/{id}/cancel`: * Description updated: Documentation references changed from "Sendcloud platform" to "Sendcloud panel" * Changes for **GET** `/carriers`: * Description updated: Documentation references changed from "Sendcloud platform" to "Sendcloud panel" * Changes for **GET** `/shipping-price`: * Parameter `contract` description updated: Reference changed from "Sendcloud platform" to "panel" * Request body parameter `contract` description updated: Reference changed from "Sendcloud platform" to "panel" * Changes for webhooks configuration: * Documentation updated: References changed from "Sendcloud platform" to "Sendcloud panel" ## Changed endpoints: * Changes for **ServicePoint Object** schema: * Field `is_active` description updated to clarify it indicates data freshness from recent scraping, not operational availability * Field `open_tomorrow` description added to clarify it reflects operational availability based on operating schedule * Field `open_upcoming_week` description added to clarify it reflects operational availability over the next 7 days ## Changed endpoints: * Changes for **GET** `/carriers`: * Documentation link added for improved API reference navigation ## Changed endpoints: * Changes for **POST** `/parcels` and related parcel endpoints: * Request body schema `ParcelItem` changed: * Field `dds_reference` added * Field `taric_doc_code` added ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/shipping_methods`: * Parameters changed: * Query param `cursor` added * Query param `limit` added ## Changed endpoints: * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/outgoing`: * Response `200` / `application/json` changed: * Field `data.labelless_service_point.general_shop_type` now can be null * Field `data.service_point.general_shop_type` now can be null * Changes for **GET** `/api/v2/service-points/{service_point_id}`: * Response `200` / `application/json` changed: * Field `general_shop_type` now can be null * Changes for **GET** `/api/v2/service-points`: * Response `200` / `application/json` changed: * Field `items.general_shop_type` now can be null ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **PUT** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `oneOf.2.parcels.allOf` changed supported schemas * `oneOf.1.parcel.allOf` changed supported schemas * `oneOf.0.failed_parcels.items.parcel.allOf` changed supported schemas * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `incoming_parcel_data.allOf` changed supported schemas * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Polymorphism object: * `returns.items.incoming_parcel_data.allOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/service-points/{service_point_id}`: * Response `200` / `application/json` changed: * Field `general_shop_type` added * Changes for **GET** `/api/v2/service-points`: * Parameters changed: * Query param `general_shop_type` added * Response `200` / `application/json` changed: * Field `items.general_shop_type` added * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/outgoing`: * Response `200` / `application/json` changed: * Field `data.labelless_service_point.general_shop_type` added * Field `data.service_point.general_shop_type` added ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Response `200` / `application/json` changed: * Field `delivery_options.items.is_order_overweight` added * Field `delivery_options.items.allowed_weight` added ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Response `200` / `application/json` changed: * Supported values for `delivery_options.items.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Changes for **GET** `/api/v2/tracking/{tracking_number}`: * Response `200` / `application/json` changed: * Supported values for `statuses.items.carrier_code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Supported values for `carrier_code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Supported values for `parcel.allOf.0.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Changes for **PUT** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Supported values for `parcel.items.allOf.0.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Changes for **POST** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Supported values for `oneOf.2.parcels.items.allOf.0.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Supported values for `oneOf.1.parcel.allOf.0.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Supported values for `oneOf.0.failed_parcels.items.parcel.allOf.0.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; * Changes for **GET** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Supported values for `parcels.items.carrier.code` changed: `['spring', 'dhl_parcel_iberia', 'inpost_gb', 'yodel', 'cirro', 'tnt_it', 'dhl_ecommerce', 'hermes_at', 'amazon', 'hermes_de', 'plx', 'transforce', 'gls_nl', 'nacex', 'gls_es', 'skymail', 'evri_international', 'rjpv2', 'gls_eu', 'inpost_es', 'fietskoeriers', 'geodis', 'postnl_large', 'poste_it_delivery', 'mhi', 'storeshippers', 'bol', 'hurby', 'fedexcrossborder', 'dpd_local', 'dbschenker', 'postnord', 'dhl_parcel_gb', 'hived', 'inpost_pl', 'paack', 'dpd_fr', 'inpost_it', 'parcelforce', 'fedex', 'glovo', 'hermes_c2c_gb', 'dhl_2_man_handling', 'tipsa', 'ctt_express']` added; ## Removed endpoints: * POST `/api/v2/brand/{brand_domain}/return-portal/rule-modifications` ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Response `200` / `application/json` changed: * Field `is_delivery_zone_configured` added * Field `is_delivery_zone_excluded` added ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Field `parcel.allOf.0.note` added * Changes for **PUT** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `parcel.items.allOf.0.note` added * Changes for **POST** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `oneOf.2.parcels.items.allOf.0.note` added * Field `oneOf.1.parcel.allOf.0.note` added * Field `oneOf.0.failed_parcels.items.parcel.allOf.0.note` added * Changes for **GET** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `parcels.items.note` added ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **PUT** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `oneOf.2.parcels.allOf` changed supported schemas * `oneOf.1.parcel.allOf` changed supported schemas * `oneOf.0.failed_parcels.items.parcel.allOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Response `200` / `application/json` changed: * Field `delivery_options.items.lead_time_hours` added * Field `delivery_options.items.sustainability_rating` added ## Changed endpoints: * Changes for **GET** `/api/v2/parcels`: * Parameters changed: * Query param `external_reference` added ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **PUT** `/api/v2/parcels`: * Parameters changed: * Supported values for `parcel.customs_information.tax_numbers.importer_of_record.items.name` changed: `['UKIMS']` added; * Supported values for `parcel.customs_information.tax_numbers.receiver.items.name` changed: `['UKIMS']` added; * Supported values for `parcel.customs_information.tax_numbers.sender.items.name` changed: `['UKIMS']` added; * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `oneOf.2.parcels.allOf` changed supported schemas * `oneOf.1.parcel.allOf` changed supported schemas * `oneOf.0.failed_parcels.items.parcel.allOf` changed supported schemas * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `incoming_parcel_data.allOf` changed supported schemas * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Polymorphism object: * `returns.items.incoming_parcel_data.allOf` changed supported schemas * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameters changed: * Supported values for `customs_information.tax_numbers.importer_of_record.items.name` changed: `['UKIMS']` added; * Supported values for `customs_information.tax_numbers.receiver.items.name` changed: `['UKIMS']` added; * Supported values for `customs_information.tax_numbers.sender.items.name` changed: `['UKIMS']` added; ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **PUT** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `oneOf.2.parcels.allOf` changed supported schemas * `oneOf.1.parcel.allOf` changed supported schemas * `oneOf.0.failed_parcels.items.parcel.allOf` changed supported schemas * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `incoming_parcel_data.allOf` changed supported schemas * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Polymorphism object: * `returns.items.incoming_parcel_data.allOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Parameters changed: * Query param `checkout_metadata` added ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/rule-modifications`: * Parameters changed: * Request body param `refund_type` added * Request body param `items.items.sku` added * Response `200` / `application/json` changed: * Field `modifications` added * Field `shipping_method_code` removed * Field `fee` removed * Field `disable_requests` removed * Field `not_returnable_items` removed * Field `parcel_not_returnable` removed ## Changed endpoints: * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `incoming_parcel_data.allOf` changed supported schemas, `['Return Parcel Object']` added * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Polymorphism object: * `returns.items.incoming_parcel_data.allOf` changed supported schemas, `['Return Parcel Object']` added * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/uploads`: * Now can return `401` / `application/json` response * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/label/download`: * Now can return `401` / `application/json` response * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/label/polling`: * Now can return `401` / `application/json` response * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/rule-modifications`: * Now can return `401` / `application/json` response * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameters changed: * Request body param `customs_information` added * Now can return `401` / `application/json` response * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/outgoing`: * Now can return `401` / `application/json` response * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal`: * Now can return `401` / `application/json` response ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Field `parcel.allOf.0.reference` added * Field `parcel.allOf.0.external_reference` now can be null * Changes for **PUT** `/api/v2/parcels`: * Parameters changed: * Request body param `parcel.reference` added * Request body param `parcel.external_reference` now can be null * Response `200` / `application/json` changed: * Field `parcel.items.allOf.0.reference` added * Field `parcel.items.allOf.0.external_reference` now can be null * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `200` / `application/json` changed: * Field `oneOf.2.parcels.items.allOf.0.reference` added * Field `oneOf.1.parcel.allOf.0.reference` added * Field `oneOf.0.failed_parcels.items.parcel.allOf.0.reference` added * Field `oneOf.2.parcels.items.allOf.0.external_reference` now can be null * Field `oneOf.1.parcel.allOf.0.external_reference` now can be null * Field `oneOf.0.failed_parcels.items.parcel.allOf.0.external_reference` now can be null * Changes for **GET** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `parcels.items.reference` added * Field `parcels.items.external_reference` now can be null ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}/return_portal_url`: * Now can return `401` response * Changes for **POST** `/api/v2/parcels/{id}/cancel`: * Now can return `401` response * Changes for **GET** `/api/v2/parcels/{id}`: * Now can return `401` response * Changes for **PUT** `/api/v2/parcels`: * Now can return `401` response * Changes for **POST** `/api/v2/parcels`: * Now can return `401` response * Changes for **GET** `/api/v2/parcels`: * Now can return `401` response ## Changed endpoints: * Changes for **POST** `/api/v2/box/finalize`: * Now can return `401` response ## Changed endpoints: * Changes for **POST** `/api/v2/integrations/{id}/shipments`: * Parameters changed: * Request body param `items.customs_details` added * Changes for **GET** `/api/v2/integrations/{id}/shipments`: * Response `200` / `application/json` changed: * Field `results.items.customs_details` added ## Changed endpoints: * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/label/download`: * Now can return `404` / `application/json` response ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas, `['Parcel Object']` added * Field `parcel.id` removed * Changes for **PUT** `/api/v2/parcels`: * Parameters changed: * Request body param `parcel.customs_information` added * Request body param `parcel.parcel_items.items.mid_code` added * Request body param `parcel.parcel_items.items.material_content` added * Request body param `parcel.parcel_items.items.intended_use` added * Response `200` / `application/json` changed: * Polymorphism object: * `parcel.allOf` changed supported schemas, `['Parcel Object']` added * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `oneOf.2.parcels.allOf` changed supported schemas, `['Parcel Object']` added * `oneOf.1.parcel.allOf` changed supported schemas, `['Parcel Object']` added * `oneOf.0.failed_parcels.items.parcel.allOf` changed supported schemas, `['Parcel Object']` added * Field `oneOf.1.parcel.id` removed * Field `oneOf.0.failed_parcels.items.parcel.id` removed * Changes for **GET** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `parcels.items.parcel_items.items.mid_code` added * Field `parcels.items.parcel_items.items.material_content` added * Field `parcels.items.parcel_items.items.intended_use` added ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: `root.oneOf` changed supported schemas ## Added endpoints: * **POST** `/api/v2/brand/{brand_domain}/return-portal/rule-modifications` ## Changed endpoints: * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Field `rule_modifications` added * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Field `returns.items.rule_modifications` added ## Changed endpoints: * **GET** `/api/v2/customs_declaration/normal_printer` entered deprecation phase. ## Changed endpoints: * Changes for **GET** `/api/v2/parcels/{id}`: * Response `200` / `application/json` changed: * Field `parcel.colli_tracking_number` removed * Changes for **PUT** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `parcel.items.colli_tracking_number` removed * Changes for **POST** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `oneOf.2.parcels.items.colli_tracking_number` removed * Field `oneOf.1.parcel.colli_tracking_number` removed * Field `oneOf.0.failed_parcels.items.parcel.colli_tracking_number` removed * Changes for **GET** `/api/v2/parcels`: * Response `200` / `application/json` changed: * Field `parcels.items.colli_tracking_number` removed ## Changed endpoints: * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal`: * Response `200` / `application/json` changed: * Field `portal.layout.helper_text` added ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Response `200` / `application/json` changed: * Field `delivery_options.items.internal_title` added ## Changed endpoints: * Changes for **POST** `/api/v2/pickups`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Response `201` / `application/json` changed: * Polymorphism object: * `root.oneOf` changed supported schemas * Changes for **GET** `/api/v2/pickups/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Parameters changed: * Query param `to_postal_code` added * Query param `parcel_length` added * Query param `parcel_width` added * Query param `parcel_height` added ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameters changed: * Request body param `images.items.product_id` added * Request body param `images.items.productId` removed * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Field `images.items.product_id` added * Field `images.items.productId` removed * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Field `returns.items.images.items.product_id` added * Field `returns.items.images.items.productId` removed ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/uploads`: * Response `201` / `application/json` changed: * Field `items.name` added * Field `items.id` removed ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/shipping-price`: * Parameters changed: * Query param `from_postal_code` added * Query param `to_postal_code` added ## Changed endpoints: * Changes for **GET** `/api/v2/tracking/{tracking_number}`: * Response `200` / `application/json` changed: * Supported values for `statuses.items.carrier_code` changed: `['dpd_gb', 'gls_de', 'sendcloud', 'poste_italiane', 'postnl_fulfilment', 'viatim', 'bpost', 'lettresuivie', 'van_straaten', 'colissimo', 'dp', 'dhl', 'sandd', 'fairsenden', 'postat', 'royal_mail', 'fadello', 'dhl_de', 'dhl_express', 'colisprive', 'ups', 'seur', 'mondial_relay', 'gls_it', 'postnl', 'delivengo', 'budbee', 'correos_express', 'homerr', 'hermes_gb', 'chronopost', 'rjp', 'trunkrs', 'dpd', 'brt', 'dpd_at', 'mrw', 'correos']` added; * Supported values for `carrier_code` changed: `['dpd_gb', 'gls_de', 'sendcloud', 'poste_italiane', 'postnl_fulfilment', 'viatim', 'bpost', 'lettresuivie', 'van_straaten', 'colissimo', 'dp', 'dhl', 'sandd', 'fairsenden', 'postat', 'royal_mail', 'fadello', 'dhl_de', 'dhl_express', 'colisprive', 'ups', 'seur', 'mondial_relay', 'gls_it', 'postnl', 'delivengo', 'budbee', 'correos_express', 'homerr', 'hermes_gb', 'chronopost', 'rjp', 'trunkrs', 'dpd', 'brt', 'dpd_at', 'mrw', 'correos']` added; * Changes for **GET** `/api/v2/brands/{id}`: * Response `200` / `application/json` changed: * Field `customization_settings.footer.whatsapp_business` added * Changes for **GET** `/api/v2/brands`: * Response `200` / `application/json` changed: * Field `brands.items.customization_settings.footer.whatsapp_business` added * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal`: * Response `200` / `application/json` changed: * Field `portal.brand.customization_settings.footer.whatsapp_business` added ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameters changed: * Request body param `products.items.return_message` is not nullable anymore * Request body param `products.items.return_reason` is not nullable anymore * Request body param `products.items.product_id` is not nullable anymore * Request body param `products.items.origin_country` is not nullable anymore * Request body param `products.items.origin_country` has new maximum length restriction: `2` * Request body param `products.items.origin_country` has new format: `iso-2` * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/outgoing`: * Response `200` / `application/json` changed: * Field `data.shipping_products.items.methods.items.pickup_date` now can be null * Field `data.shipping_products.items.methods.items.pickup_date` is not nullable anymore * Field `data.parcel.collo_count` now can be null * Field `data.parcel.collo_count` is not nullable anymore * Field `data.parcel.to_state` now can be null * Field `data.parcel.to_state` is not nullable anymore * Field `data.parcel.id` now can be null * Field `data.parcel.id` is not nullable anymore * Response `422` / `application/json` changed: * Field `error.message` changed its type to `string` * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal`: * Response `200` / `application/json` changed: * Field `return_locations.items.country_state` now can be null * Field `return_locations.items.country_state` is not nullable anymore * Field `portal.layout.background_image` now can be null * Field `portal.layout.background_image` is not nullable anymore ## Added endpoints: * **POST** `/api/v2/brand/{brand_domain}/return-portal/uploads` ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameters changed: * Request body param `images` added * Changes for **GET** `/api/v2/returns/{id}`: * Response `200` / `application/json` changed: * Field `images` added * Changes for **GET** `/api/v2/returns`: * Response `200` / `application/json` changed: * Field `returns.items.images` added ## Changed endpoints: * Changes for **POST** `/api/v2/parcels`: * Parameters changed: * Polymorphism object: * `root.oneOf` changed supported schemas ## Changed endpoints: * Changes for **GET** `/api/v2/contracts/{id}`: * Response `200` / `application/json` changed: * Field `is_default` added * Changes for **GET** `/api/v2/contracts`: * Response `200` / `application/json` changed: * Field `contracts.items.is_default` added ## Changed endpoints: * Changes for **GET** `/api/v2/integrations/{id}`: * Response `200` / `application/json` changed: * Field `webhook_url` now can be null * Field `shop_url` now can be null * Changes for **GET** `/api/v2/integrations`: * Response `200` / `application/json` changed: * Field `items.webhook_url` now can be null * Field `items.shop_url` now can be null ## Changed endpoints: * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/outgoing`: * Response `200` / `application/json` changed: * Field `data.applicable_actions.items.priority` added ## Changed endpoints: * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal`: * Response `200` / `application/json` changed: * Field `portal.layout` added ## Changed endpoints: * Changes for **POST** `/api/v2/integrations/{id}/logs`: * Parameters changed: * Request body param `exception` now can be null * Request body param `base_url` is not nullable anymore * Request body param `base_url` has new minimal length restriction: `1` * Request body param `method` is not nullable anymore * Response `201` / `application/json` changed: * Field `exception` now can be null * Field `base_url` is not nullable anymore * Field `base_url` has new minimal length restriction: `1` * Field `method` is not nullable anymore * Changes for **GET** `/api/v2/integrations/{id}/logs`: * Response `200` / `application/json` changed: * Field `results.items.base_url` is not nullable anymore * Field `results.items.base_url` has new minimal length restriction: `1` * Field `results.items.method` is not nullable anymore * Changes for **GET** `/api/v2/integrations/logs`: * Response `200` / `application/json` changed: * Field `results.items.base_url` is not nullable anymore * Field `results.items.base_url` has new minimal length restriction: `1` * Field `results.items.method` is not nullable anymore ## Changed endpoints: * Changes for **GET** `/api/v2/integrations/{id}/shipments`: * Parameters changed: * Query param `ordering` removed ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameters changed: * Request body param `service_point.code` removed * Request body param `service_point.is_active` removed * Request body param `service_point.extra_data` removed * Request body param `service_point.name` removed * Request body param `service_point.street` removed * Request body param `service_point.house_number` removed * Request body param `service_point.postal_code` removed * Request body param `service_point.city` removed * Request body param `service_point.latitude` removed * Request body param `service_point.longitude` removed * Request body param `service_point.email` removed * Request body param `service_point.phone` removed * Request body param `service_point.homepage` removed * Request body param `service_point.carrier` removed * Request body param `service_point.country` removed * Request body param `service_point.formatted_opening_times` removed * Request body param `service_point.open_tomorrow` removed * Request body param `service_point.open_upcoming_week` removed * Request body param `service_point.distance` removed * Request body param `service_point.shop_type` removed * Request body param `service_point.id` has new format: `int64` ## Changed endpoints: * Changes for **GET** `/api/v2/shipping-products`: * Parameter changes: * Parameter `returns` added ## Changed endpoints: * Changes for **GET** `/api/v2/shipping_methods/{id}`: * Response `200` / `application/json` changed: * Field `shipping_method.countries.items.price_breakdown` added * Changes for **GET** `/api/v2/shipping_methods`: * Response `200` / `application/json` changed: * Field `shipping_methods.items.countries.items.price_breakdown` added * Changes for **GET** `/api/v2/shipping-price`: * Response `200` / `application/json` changed: * Field `items.breakdown` added ## Changed endpoints: * Changes for **POST** `/api/v2/brand/{brand_domain}/return-portal/incoming`: * Parameter changes: * Parameter `incoming_parcel.from_country_state` added ## Changed endpoints: * Changes for **GET** `/api/v2/brand/{brand_domain}/return-portal/outgoing`: * Response `200` / `application/json` changed: * Field `data.products.items.image_url` added * Field `examples.OutgoingParcel.value.data.products.0.image_url` added ## Changed endpoints: * Changes for **GET** `/pickups`: * Response `200` / `application/json` changed: * Field `examples.RetrieveDHLParcelIberiaPickups` added * Changes for **POST** `/pickups`: * Parameter changes: * Parameter `examples.DHLParcelIberiaPickupRequest` added * Response `201` / `application/json` changed: * Field `examples.SuccessfullyCreatedDHLParcelIberiaPickup` added * Changes for **GET** `/pickups/{id}`: * Response `200` / `application/json` changed: * Field `examples.RetrieveDHLParcelIberiaPickup` added ## Changed endpoints: * Changes for **GET** `/api/v2/checkout/configurations/{configuration_id}/delivery-options`: * Response `200` / `application/json` changed: * Field removed: `delivery_options.items.delivery_dates.items.delivery_date` * Field removed: `delivery_options.items.delivery_dates.items.parcel_handover_date` * Field `delivery_options.items.delivery_dates` is now required * Field `delivery_options.items.delivery_dates` can be null now ## Changed endpoints: * Changes for **GET** `/api/v2/integrations/{id}/shipments`: * Parameter changes: * Added new parameter: `end_date` * Added new parameter: `external_order_ids` * Added new parameter: `external_shipment_ids` * Added new parameter: `order_number` * Added new parameter: `sender_address` * Added new parameter: `shipping_rules` * Added new parameter: `start_date` # Contracts API overview Source: https://sendcloud.dev/api/v2/contracts/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Sendcloud supports the connection of your own direct shipping contract with your Sendcloud account for any [Sendcloud-supported shipping carrier](https://www.sendcloud.com/carriers/). Once you've successfully connected your contract, your shipping label prices will be invoiced directly via your chosen carrier/s, and the price you pay for labels in Sendcloud will appear as 0,00 EUR. ## How to enable your direct carrier contract * [Log in](https://account.sendcloud.com/login/) to your Sendcloud account * Find your shipping carrier on the [Carriers](https://app.sendcloud.com/v2/shipping/carriers/list) page and click **Add Contract**. * Fill in the required information and click **Add this contract** The type of information you need to enter differs from carrier to carrier. You can find out specifically what information you need to submit and how to obtain it by finding your carrier on our help center's [carriers page](https://support.sendcloud.com/hc/en-us/categories/360001511752-Carriers-) and reading its contract activation guide. # Retrieve a contract Source: https://sendcloud.dev/api/v2/contracts/retrieve-a-contract /.openapi/v2/contracts/openapi.yaml get /contracts/{id} Retrieve information about a specific direct contract by passing its `id` as a path parameter. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a list of contracts Source: https://sendcloud.dev/api/v2/contracts/retrieve-a-list-of-contracts /.openapi/v2/contracts/openapi.yaml get /contracts Retrieves information about all of the available contracts you have in your Sendcloud account. It will also return the `contract_id` of your contracts, which you can use to retrieve information about a specific contract. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Dynamic Checkout API overview Source: https://sendcloud.dev/api/v2/dynamic-checkout/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Boost your conversion rate and offer an unbeatable delivery experience to your customers via Sendcloud. **Dynamic Checkout** provides everything you need to optimize your checkout page and let your customers choose when and how they want to receive their orders. Activate any of our **160+ supported carriers** (including 10+ international carriers) to create a first class shipping experience. Customize the methods you want to offer **per delivery country** and choose which delivery options will appear on your checkout page: * **Nominated day delivery** allows your customers to pick a preferred delivery day * **Same-day delivery** lets you stay ahead of the competition with the fastest possible delivery services * **Standard delivery** provides next-day, standard and international shipping options via a huge range of flexible shipping methods * **Service point delivery** allows your customers to pick a preferred service point Delivery options are configured directly via the Sendcloud platform, so you can create, customize and publish your checkout page in a matter of minutes. Learn how to set up and configure Dynamic Checkout in our help center. # Retrieve a list of delivery options Source: https://sendcloud.dev/api/v2/dynamic-checkout/retrieve-a-list-of-delivery-options /.openapi/v2/checkout/openapi.yaml get /checkout/configurations/{configuration_id}/delivery-options Get a list of delivery options to display in your checkout page, based on your Dynamic Checkout configuration in the Sendcloud platform. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). To use this API, you first need to [create your own Dynamic Checkout configuration](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout) in the Sendcloud platform. To get started, take the following steps: 1. Log in to your Sendcloud account and go to **Dynamic Checkout**. 2. Select your API integration from the **Shops** menu to customize your delivery options. 3. When you're done, click **Publish** to apply your configuration to your API integration. This API allows you to let your customers pick delivery options. The options returned via this endpoint are based on the [delivery methods](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4) they previously configured, in addition to cart/order information, e.g. parcel weight, total order value, destination country, etc. Then you can present the returned delivery options to your customer on your checkout page, where they can select their preferred option for their order. ## How do delivery options correspond to configured delivery methods? This API returns one delivery option per carrier configured in Dynamic Checkout. If a delivery method is configured with multiple carriers, then multiple delivery options will be returned - one per carrier. In cases when delivery options correspond to the same delivery method, delivery options' ids will refer to the same delivery method id, leaving API users with a flexibility to perform grouping based on a delivery method id, if desired. Only the [Service point delivery method](https://support.sendcloud.com/hc/en-us/articles/4414674483860) currently allows for selection of multiple carriers. Hence, multiple delivery options will be returned only for a delivery method of this type. ## How can I create a parcel out of the selected delivery option? You'll need to make an API call to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, passing `request_label=true` and `shipping_method_id={checkout_identifier.value}`, where the `checkout_identifier` field refers to the identifier of the selected delivery option. # Introduction Source: https://sendcloud.dev/api/v2/index Welcome to the Sendcloud API v2 documentation. Here, you'll find all the information you need to integrate with Sendcloud's powerful shipping platform. Whether you're looking to automate your shipping processes, manage orders, or track shipments, our API provides the tools you need to streamline your operations. **API v2 is entering maintenance mode.** Several endpoints are now closed to new users. Although some v2 endpoints are still available, we strongly recommend using API v3 for all new integrations to benefit from the latest features and improvements. Already using v2? Don't worry, your current integration remains fully functional. Read more about our versions, and how API v2 is entering [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Create or update a list of shipments Source: https://sendcloud.dev/api/v2/integrations/create-a-list-of-shipments /.openapi/v2/integrations/openapi.yaml post /integrations/{id}/shipments Insert shipments (or 'orders') into an API integration from your shop system, and have them appear in your Sendcloud account. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This endpoint is only available for official Sendcloud partners. This endpoint allows you to insert shipments (or 'orders') into an API integration from your shop system, and have them appear in your Sendcloud account. Imported orders will appear in the Sendcloud platform under the **Incoming order overview** with the status "Ready to process". This allows you to easily generate parcels and create shipping labels via the API or directly from the Sendcloud platform. The validation for this endpoint is more relaxed, therefore we recommend this method over the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint for third-party integrators. This is an **UPSERT** endpoint which attempts to be idempotent given specific fields to ensure that orders are not duplicated. If there's an existing match in our database for specific fields (`external_order_id` and `external_shipment_id`), then the shipment will be updated. The system will only update orders that have had their `updated_at` (ISO 8601 DateTime) timestamp changed. The `external_shipment_id` field is used to split orders across multiple shipments, however, this field is not supported by all shop systems. If your shop system supports the distribution of product items within an order across multiple shipments, you can use the shipment data to create multiple entries. If your shop does not support this feature, you can set the `external_shipment_id` value to `null`. Batches are limited to 100 orders at once. This endpoint should accept most values in any of the available fields, but in the case of erroneous data, an error message will be returned directly. Your requests should almost always succeed unless the field structure is not correct. # Create integration exceptions logs Source: https://sendcloud.dev/api/v2/integrations/create-integration-exception-logs /.openapi/v2/integrations/openapi.yaml post /integrations/{id}/logs Create integration exception logs, which will appear in the connection issue log screen of the user's integration. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Delete a shipment Source: https://sendcloud.dev/api/v2/integrations/delete-a-shipment /.openapi/v2/integrations/openapi.yaml post /integrations/{id}/shipments/delete Allows you to delete a shipment from Sendcloud, e.g. if it has been canceled or deleted in your shop system. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The `order_status` and `payment_status` fields we retrieve from integrations are not mapped in our system, meaning that orders will not be automatically updated or deleted if the values for these fields change after an order is placed. You can delete an order by providing either a `shipment_uuid`, or a combination of the `external_order_id` and `external_shipment_id` properties. # Delete an integration Source: https://sendcloud.dev/api/v2/integrations/delete-an-integration /.openapi/v2/integrations/openapi.yaml delete /integrations/{id} Delete a shop integration from the Sendcloud system. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Integrations API overview Source: https://sendcloud.dev/api/v2/integrations/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Sendcloud offers plug-and-play integrations with 100+ e-commerce platforms, marketplaces, WMS, and ERP systems. Once connected, orders are automatically imported into Sendcloud and appear in the **Incoming orders** overview on the Sendcloud platform. Then, you can change an order, select a shipping method, and print the shipping label. The Integrations API allows you to retrieve, update and add orders to custom webshop integrations. # Partially update an integration Source: https://sendcloud.dev/api/v2/integrations/partially-update-an-integration /.openapi/v2/integrations/openapi.yaml patch /integrations/{id} Partially update settings for a specific integration using its `id`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Using this endpoint, you can change the webshop name and URL, edit the list of carriers you want to enable for service point delivery and enable or disable service point delivery by setting `service_point_enabled` to `true` or `false`. Unlike the [Update an integration](/api/v2/integrations/update-an-integration) endpoint, you can send only the fields you want to update. You can obtain an integration `id` via the [Retrieve a list of integrations](/api/v2/integrations/retrieve-a-list-of-integrations) endpoint. # Retrieve a list of integrations Source: https://sendcloud.dev/api/v2/integrations/retrieve-a-list-of-integrations /.openapi/v2/integrations/openapi.yaml get /integrations Retrieve information about all the shop integrations currently connected to your Sendcloud account. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The information returned includes the shop name and URL, the date, and the time of the last order fetch. The response indicates whether service point delivery is enabled for this integration, and for which carriers. # Retrieve a list of shipments Source: https://sendcloud.dev/api/v2/integrations/retrieve-a-list-of-shipments /.openapi/v2/integrations/openapi.yaml get /integrations/{id}/shipments Retrieve a list of orders that were imported from a specific webshop integration. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Note that the orders **are not** affected by [shipping rules](https://support.sendcloud.com/hc/en-us/articles/360025143571-Automate-your-workflow-using-Sendcloud-Shipping-Rules) at the time of retrieval, unless enabled explicitly. This endpoint is paginated, meaning that you can navigate through the `results` via the URLs provided within the `next` and `previous` fields. # Retrieve all integration exception logs Source: https://sendcloud.dev/api/v2/integrations/retrieve-all-integration-exception-logs /.openapi/v2/integrations/openapi.yaml get /integrations/logs Retrieve all integration exception logs. These logs are created when integrations have problems making API requests to shop systems. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Integration exception logs might be generated, for example: * if some resource cannot be found * if API credentials are no longer valid Each log record may contain information about the request and response, the status code and code exception, and can be used as a reference to identify issues between Sendcloud and a webshop. # Retrieve an integration Source: https://sendcloud.dev/api/v2/integrations/retrieve-an-integration /.openapi/v2/integrations/openapi.yaml get /integrations/{id} Retrieve information about a specific integration using its `id`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The information returned includes the shop name and URL, the date and the time of the last order fetch. The response will also indicate whether service point delivery is enabled for this integration, and for which carriers. # Retrieve exception logs for a specific integration Source: https://sendcloud.dev/api/v2/integrations/retrieve-exception-logs-for-a-specific-integration /.openapi/v2/integrations/openapi.yaml get /integrations/{id}/logs Retrieve exception logs for a specific integration. These logs are created when integrations have problems making API requests to shop systems. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Integration exception logs might be generated, for example: * if some resource cannot be found * if API credentials are no longer valid Each log record may contain information about the request and response, the status code and code exception, and can be used as a reference to identify issues between Sendcloud and a webshop. # Update an integration Source: https://sendcloud.dev/api/v2/integrations/update-an-integration /.openapi/v2/integrations/openapi.yaml put /integrations/{id} Update settings for a specific integration using its `id`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Using this endpoint, you can change the webshop name and URL, edit the list of carriers you want to enable for service point delivery and enable or disable service point delivery by setting `service_point_enabled` to `true` or `false`. Unlike the [Partially update an integration](/api/v2/integrations/partially-update-an-integration) endpoint, you must send all fields, even those you don't want to change. You can obtain an integration `id` via the [Retrieve a list of integrations](/api/v2/integrations/retrieve-a-list-of-integrations) endpoint. # Invoices API overview Source: https://sendcloud.dev/api/v2/invoices/index Sendcloud translates the costs for shipping labels, surcharges and other used functionalities into invoices. For more information on how we bill your usage, see [this page](https://support.sendcloud.com/hc/en-us/articles/360025143911-How-do-we-charge-invoice-your-shipments-) The **Invoices API** allows you to retrieve a list of your invoices and view their details. You can also download invoices in PDF or CSV format directly from your Sendcloud account, by going to [Billing](https://app.sendcloud.com/v2/account/financial/invoices/list), finding an invoice, and clicking **Details**. For more information on invoices and their payment, see [this page](https://support.sendcloud.com/hc/en-us/articles/35114000751633-Billing-Financial-Invoices). # Retrieve a list of invoices Source: https://sendcloud.dev/api/v2/invoices/retrieve-a-list-of-invoices /.openapi/v2/invoices/openapi.yaml get /user/invoices Retrieve all invoices (with the associated invoice `id`) which have been issued to your account to date. # Retrieve a specific invoice Source: https://sendcloud.dev/api/v2/invoices/retrieve-a-specific-invoice /.openapi/v2/invoices/openapi.yaml get /user/invoices/{id} Retrieve detailed information about a specific invoice issued to your Sendcloud account, including all line items. You can obtain the `id` from the [Retrieve a list of invoices](/api/v2/invoices/retrieve-a-list-of-invoices) endpoint. # Bulk PDF label printing Source: https://sendcloud.dev/api/v2/labels/bulk-pdf-label-printing /.openapi/v2/labels/openapi.yaml post /labels Request multiple shipping labels for an array of parcels at the same time. You will receive URLs to download the labels in PDF format, for both normal and label printers. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Labels API overview Source: https://sendcloud.dev/api/v2/labels/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Once a parcel has been announced, you can use the **Labels API** to request a PDF shipping label in order to print it and attach it to the box. You can retrieve a shipping label in A4 or A6 format, suitable for normal printers, or A6 format for label printers. For normal printers the `start_from` value will indicate the position of the label on an A4 size page: * `0` = Top left * `1` = Top right * `2` = Bottom left * `3` = Bottom right # Retrieve a customs declaration PDF Source: https://sendcloud.dev/api/v2/labels/retrieve-a-customs-declaration-pdf /.openapi/v2/labels/openapi.yaml get /customs_declaration/normal_printer/{parcel_id} Retrieve the customs documents associated with a label in PDF format for a normal printer. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a label for a specific parcel Source: https://sendcloud.dev/api/v2/labels/retrieve-a-label-for-a-specific-parcel /.openapi/v2/labels/openapi.yaml get /labels/{parcel_id} You will receive URLs to download the labels in PDF format, for both normal and label printers. You can get the `id` of a parcel from the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a PDF label Source: https://sendcloud.dev/api/v2/labels/retrieve-a-pdf-label /.openapi/v2/labels/openapi.yaml get /labels/normal_printer/{parcel_id} Retrieve a shipping label for a specific parcel in PDF format for a normal printer. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a specific PDF label for a label printer Source: https://sendcloud.dev/api/v2/labels/retrieve-a-specific-pdf-label-for-a-label-printer /.openapi/v2/labels/openapi.yaml get /labels/label_printer/{parcel_id} Retrieve a shipping label for a specific parcel in PDF format for a label printer. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve multiple customs declaration PDFs Source: https://sendcloud.dev/api/v2/labels/retrieve-multiple-customs-declaration-pdfs /.openapi/v2/labels/openapi.yaml get /customs_declaration/normal_printer Retrieve PDF customs documents suitable for normal printers for multiple different parcels at the same time. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This endpoint is deprecated as of Mon, 08 Jan 2024 00:00:00 GMT. We recommend using the [Retrieve parcel documents](/api/v2/parcel-documents/retrieve-parcel-documents) endpoint instead. # Retrieve multiple PDF labels Source: https://sendcloud.dev/api/v2/labels/retrieve-multiple-pdf-labels /.openapi/v2/labels/openapi.yaml get /labels/normal_printer Retrieve PDF label documents suitable for normal printers for multiple different parcels at the same time. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve PDF labels for a label printer Source: https://sendcloud.dev/api/v2/labels/retrieve-pdf-labels-for-a-label-printer /.openapi/v2/labels/openapi.yaml get /labels/label_printer Retrieve PDF label documents suitable for label printers for multiple different parcels at the same time. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # OAuth 2.0 token Source: https://sendcloud.dev/api/v2/oauth2/token /.openapi/v2/auth/openapi.yaml post /oauth2/token Use this endpoint to get a new OAuth 2.0 access token. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). OAuth 2.0 authentication is currently available as a beta feature for a limited number of clients. Following this beta phase, we are planning a gradual rollout of the OAuth2 authentication feature to all users. Our aim is to ensure a smooth transition and to continue providing an optimal user experience throughout the process. You can find a list of open-source libraries to help with OAuth 2.0 authentication at [https://oauth.net/code/](https://oauth.net/code/) # Parcel documents API overview Source: https://sendcloud.dev/api/v2/parcel-documents/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). For international shipments, customs documentation is generated alongside the shipping label. These documents can be downloaded separately from the shipping label in various formats and resolutions via the **Parcel Documents API**. # Retrieve parcel documents Source: https://sendcloud.dev/api/v2/parcel-documents/retrieve-parcel-documents /.openapi/v2/parcel-documents/openapi.yaml get /parcels/{id}/documents/{type} Retrieve a document for a given parcel by providing the parcel `id` and document `type`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). For international shipments, a commercial invoice, CN23 or CN22 (+CP71) form must be attached (either physically or [digitally](https://support.sendcloud.com/hc/en-us/articles/4417349714452-Send-your-customs-documents-digitally-via-Paperless-Trade-) for some carriers) to the shipment for customs officials to access. The type of document required depends on the shipping method and value of the shipment. When you use the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, Sendcloud generates the correct type of document for your shipment if you have filled in all the information related to the parcel contents, value, and invoice. Use this endpoint to retrieve these documents in your preferred format. The supported document types are as follows: * `air-waybill` * `cn23` * `cn23-default` * `commercial-invoice` * `cp71` * `label` * `qr` # Parcel statuses API overview Source: https://sendcloud.dev/api/v2/parcel-statuses/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). During the delivery journey, a parcel can receive a number of different status updates, also refered to as **tracking statuses**. These statuses are used to indicate the current progress of the shipment, or to depict any changes that have taken place which result in the parcel being unable to be delivered. It's the role of the carrier to send tracking updates, and new updates occur whenever the parcel receives a scan, either at the sorting hub, service point or from the delivery driver. Shipping carriers use a variety of interchangeable terms to indicate delivery milestones. Sendcloud maps these different terms into a list of universally understandable parcel statuses. These are then used to trigger tracking notifications, or to display the current status of a parcel in the Sendcloud platform. You can use our **Parcel Statuses API** to retrieve a list of all the parcel statuses that are supported by Sendcloud. # Retrieve a list of parcel statuses Source: https://sendcloud.dev/api/v2/parcel-statuses/retrieve-a-list-of-parcel-statuses /.openapi/v2/parcel-statuses/openapi.yaml get /parcels/statuses Get a list of all parcel statuses available in the Sendcloud system, with their unique code and friendly description. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Cancel a parcel Source: https://sendcloud.dev/api/v2/parcels/cancel-a-parcel /.openapi/v2/parcels/openapi.yaml post /parcels/{id}/cancel Cancel an announced parcel (if supported by the carrier) or delete an unannounced parcel. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). You can use this endpoint to: 1. **Cancel** an announced parcel; or, 2. **Delete** an unannounced parcel ## Cancelling a parcel When you **cancel** a parcel which has already been announced (has a shipping label attached to it), you will still be able to find it via the `parcel_id` and the [Retrieve a parcel](/api/v2/parcels/retrieve-a-parcel) endpoint. In the Sendcloud platform, it will appear in your **Cancelled labels** overview. **Insurance Notice**: If you proceed to ship a parcel that was initially cancelled, the parcel's insurance coverage will become void, and any insurance claims will not be valid for that shipment. After 42 days, it's no longer possible to cancel a parcel, even if it hasn't been shipped. ### Conditions for label cancellation It's not always possible to cancel a parcel which has already been announced. As a result, cancellation is not guaranteed and may be asynchronous depending on the state of the parcel. When you send a cancellation request via this endpoint, the response will indicate the status of the cancellation request. Each carrier has different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the label is cancelled within the deadline. You can find more information about cancellation deadlines in our [help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-). ## Deleting a parcel When you **delete** a parcel which hasn't been announced, the parcel will be removed from the Sendcloud system and you will no longer be able to locate it via the parcel `id`. You will need to create the parcel again if you want to announce it at a later date. # Create a parcel or parcels Source: https://sendcloud.dev/api/v2/parcels/create-a-parcel-or-parcels /.openapi/v2/parcels/openapi.yaml post /parcels Create one or multiple parcels, either to be immediately announced to the carrier, or to be created for later announcement. **This endpoint is now in maintenance mode and is closed to new users.** * If your Sendcloud account was created before April 13th 2026, you can continue to use this endpoint as normal. * New users should start with API v3 to access our latest features and improved performance. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This endpoint **creates a parcel** under your API credentials. * You can choose to **announce the parcel** and create the shipping label at the same time as you create the parcel by providing the parameter `request_label: true`. * When `request_label` is `false`, the parcel will be created, but not announced. * You can then request the shipping label at a later date by changing the `request_label` parameter via the [Update a parcel](/api/v2/parcels/update-a-parcel) endpoint. Make sure you use the correct `sender_address` if you wish to ship this parcel from a location **other than** your **default** sender address. You can find the `sender_address` for each of the addresses you've saved in your Sendcloud account via the [Retrieve a sender address](/api/v2/sender-addresses/get-a-sender-address) endpoint. Also keep in mind that the `sender_address` id will not be saved/reflected in the created order (Incoming Orders view / Pack & Go) if `request_label` is `false`. ## International parcel creation If you want to create a parcel to ship to a destination country outside the EU, it's mandatory to include additional information related to the parcel contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping method selected. After the shipping label and associated documents are generated, you can retrieve and download them via the [Retrieve parcel documents](/api/v2/parcel-documents/retrieve-parcel-documents) endpoint. If you have more than one active contracts for a specific carrier, you must fill the `contract` field with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v2/contracts/retrieve-a-list-of-contracts) endpoint. International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. You can read more in-depth information on international shipping and its requirements in [our developer guides](/docs/shipping/international-shipping/). ## Multicollo More information on how to create multiple parcels within one shipment can be found in the [Multicollo page](/docs/shipping/multicollo/) of our developer guides. # Parcels API overview Source: https://sendcloud.dev/api/v2/parcels/index **The [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint in Parcels API v2 is now in maintenance mode and is closed to new users.** * If your Sendcloud account was created before April 13th 2026, you can continue to use the Parcels API v2 as normal. * New users should start with API v3 to access our latest features and improved performance. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Endpoints in maintenance mode: * [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) (`POST /parcels`) At the core of the Sendcloud Shipping API is the **Parcels API**. Parcels are data objects which can be announced, and have a shipping method and shipping label assigned to them. You can also think of parcels as **shipments**. You can use this resource to perform a number of activities: * Create a parcel and immediately announce it * Create a parcel and choose not to announce it (no shipping label is created) * Update the details, or create a label, for an unannounced parcel * Cancel an announced parcel International parcels require more information than domestic parcels. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your parcel request. Read more about [international shipping and its requirements](/docs/shipping/international-shipping). # Retrieve a parcel Source: https://sendcloud.dev/api/v2/parcels/retrieve-a-parcel /.openapi/v2/parcels/openapi.yaml get /parcels/{id} Retrieve a specific parcel by its `id`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a return portal URL Source: https://sendcloud.dev/api/v2/parcels/retrieve-a-return-portal-url /.openapi/v2/parcels/openapi.yaml get /parcels/{id}/return_portal_url Check which of your branded return portals is associated with a specific parcel using the parcel's `id`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The URL which is retrieved will link directly to the parcel in the Sendcloud Return portal, so a **return parcel** can be created immediately based on the outgoing shipment. If no Return portal is configured, or if no brand is connected to the parcel, this endpoint will return an error response with a 404 status code. # Retrieve parcels Source: https://sendcloud.dev/api/v2/parcels/retrieve-parcels /.openapi/v2/parcels/openapi.yaml get /parcels This endpoint allows you to retrieve a list of all the parcels which you have created or imported into your Sendcloud account under your API credentials. You can filter the results based on the query parameters provided below, in order to retrieve a specific parcel or list of parcels which match the defined criteria. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Update a parcel Source: https://sendcloud.dev/api/v2/parcels/update-a-parcel /.openapi/v2/parcels/openapi.yaml put /parcels Update a parcel which has **not yet been announced**, either to make changes to the original parcel data, or to request a shipping label if one hasn't yet been created. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). You'll need to include the `parcel_id` of the parcel you wish to update, which you can retrieve via the [Retrieve all parcels](/api/v2/parcels/retrieve-parcels) endpoint. Note that when updating a parcel with a `quantity` higher than 1 (e.g. a multicollo shipment), setting `request_label=true` is not allowed, since multiple parcels will be returned. Once a parcel is announced and a label is created, it's not possible to make further changes via this endpoint. ## Change address or parcel details If you need to make adjustments to details in the original parcel, such as customer address details, shipping method, etc., you can do so by adding any of the `POST` request parameters listed under the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. These request parameters must be nested under a `parcel` object. ## Create a shipping label for a parcel which is not yet announced Use this endpoint to update the `request_label: false` parameter to `true`for parcels which you chose not to announce at the time of parcel creation, and which now need a shipping label. ```json { "parcel": { "id": 1, "request_label": true } } ``` The shipping label will be announced and can be downloaded via an endpoint in the [Labels API](/api/v2/labels) or [Parcel documents API](/api/v2/parcel-documents). # Create a pickup Source: https://sendcloud.dev/api/v2/pickups/create-a-pickup /.openapi/v2/pickups/openapi.yaml post /pickups Schedule a pickup with a carrier (note that the carrier must support pickups). **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). See a list of [carriers which support pickups](/api/v2/pickups#which-carriers-support-pickups-via-the-api). You can schedule the pickup to take place from a location and time of your choosing, and include any additional instructions to the driver by including the `special_instructions` parameter. When a pickup is successfully scheduled a pickup `id` will be returned. If you have more than one active contract for a specific carrier, you must send the `contract` field with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v2/contracts/retrieve-a-list-ofcontracts) endpoint. # Pickups API overview Source: https://sendcloud.dev/api/v2/pickups/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Scheduling a pickup allows you to have your parcels collected by a driver from a location of your choosing. When scheduling a pickup via the **Pickups API**, the sender address is dynamic, which means that you don't have to have a sender address saved in your Sendcloud account settings. When you schedule a pickup via the API, you are only able to schedule a **one-time collection**. Depending on your shipping volume you may be able to schedule a recurring pick-up from your preferred location on a weekly or more than weekly basis. **Tip:** You should schedule your collection **at least 2 working days in advance** to allow for processing time. ## Which carriers support pickups via the API? Currently, you can use the API to schedule a pickup with the following carriers: * [DHL Express](https://support.sendcloud.com/hc/en-us/articles/360025147811-DHL-Express-shipping-conditions-Netherlands-) * [FedEx](https://support.sendcloud.com/hc/en-us/articles/360058873371-FedEx-shipping-conditions-) * [Correos Express](https://support.sendcloud.com/hc/en-us/articles/360031821112-Shipping-Conditions-Correos-Express-Spain-) * [DHL (Netherlands and Belgium)](https://support.sendcloud.com/hc/en-us/articles/360024846472-DHL-shipping-conditions-Netherlands-and-Belgium-) * DHL Parcel Iberia * [DPD Germany](https://support.sendcloud.com/hc/en-us/articles/360025834352-DPD-shipping-conditions-Germany-) * [Poste Italiane Delivery](https://support.sendcloud.com/hc/en-us/articles/6368506777236-Poste-Delivery-Business-shipping-conditions) * [Correos](https://support.sendcloud.com/hc/en-us/articles/360028511872-Shipping-Conditions-Correos-Spain-) * [UPS](https://support.sendcloud.com/hc/en-us/articles/7516003425812-UPS-shipping-conditions-) # Retrieve a list of pickups Source: https://sendcloud.dev/api/v2/pickups/retrieve-a-list-of-pickups /.openapi/v2/pickups/openapi.yaml get /pickups Retrieve information about all pickups which have been created from your account. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This is limited to the carriers which support pickups via the API. The response includes information about when the pickup was scheduled, the latest status, the parcel tracking number and the time frame in which the pickup is due to take place. # Retrieve a pickup Source: https://sendcloud.dev/api/v2/pickups/retrieve-a-pickup /.openapi/v2/pickups/openapi.yaml get /pickups/{id} Retrieve information about a specific pickup based on its `id`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Create a parcels report Source: https://sendcloud.dev/api/v2/reporting/create-a-parcels-report /.openapi/v2/reporting/openapi.yaml post /reporting/parcels Generate a CSV report containing information about outgoing or incoming parcels. The parcels included in the report will depend on the `filters` provided, and the columns will be determined by the `fields` parameter. Use this endpoint to create the report and obtain the report `id`, which you will use to obtain the actual CSV download via the [Retrieve a parcels report](/api/v2/reporting/retrieve-a-parcels-report) endpoint. # Reporting API overview Source: https://sendcloud.dev/api/v2/reporting/index The **Reporting API** endpoints allow you to generate and download a CSV report containing data related to your Sendcloud account for tracking and analysis purposes. You can refine the data which will be included by specifying the fields which you want to be shown on the report, and filter based on when the label was updated in the Sendcloud system or announced to the carrier. **Tip:** To create a report of your return shipments, include the property `direction: "incoming"`. Similarly, `direction: "outgoing"` will create a report of your outgoing shipments. The limitation for each report is 100K parcels. Try to select a shorter date range if you exceed that number. # Retrieve a parcels report Source: https://sendcloud.dev/api/v2/reporting/retrieve-a-parcels-report /.openapi/v2/reporting/openapi.yaml get /reporting/parcels/{report_id} Generate a URL to download a parcels report in CSV format. The report `id` is the one you obtained via the [Create a parcels report](/api/v2/reporting/create-a-parcels-report) endpoint. Depending on the size of the report, it may not be immediately available for download. The status of the report is indicated in the response body under the `status_message` field. The report will expire after a certain amount of time, after which you will have to generate it again. The time of expiry is indicated in the response body under the `expires_at` field. # Create a file upload for the return portal Source: https://sendcloud.dev/api/v2/return-portal/create-a-file-upload-for-the-return-portal /.openapi/v2/return-portal/openapi.yaml post /brand/{brand_domain}/return-portal/uploads Upload an image for use in the return portal. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). This endpoint allows users to upload media that may be used during the return creation purposes. The response from this endpoint contains filenames used to identify the files in later requests. Currently only images are supported. Note: * Files are only kept for 48 hours after upload, unless used somewhere else (for example, when creating a return). * The URLs returned in this response will only be available for 48 hours. * The endpoint allows a maximum of 10 files, so groups larger than that should be batched. * Files should be smaller than 10MB. This API is currently in in beta, and may change in the near future. # Create a return Source: https://sendcloud.dev/api/v2/return-portal/create-a-return /.openapi/v2/return-portal/openapi.yaml post /brand/{brand_domain}/return-portal/incoming Create a new return parcel based on an outgoing parcel. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The outgoing parcel and related data needed to make a request to this endpoint can be retrieved from the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. This endpoint also returns the JWT Token needed for authentication with this endpoint. # Return portal API overview Source: https://sendcloud.dev/api/v2/return-portal/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The Sendcloud Return portal is a convenient and easy to use feature which allows customers to create a return shipment for an order. The customer can enter both the tracking number for the original order and their postcode directly into the Return portal to perform an outgoing parcel lookup. Upon a successful lookup, they are prompted to select their return items and the reason for the return, select a refund or exchange method and choose how they want to make the return. The return parcel is then announced with the selected carrier, and a downloadable return label is provided to the customer. ## What can you do with this API? The **Return portal API** provides several endpoints which cover the entire return process: * Perform a lookup of your Return portal settings * Lookup an outgoing parcel and acquire JWT authentication tokens * Create a return parcel * Download the label for the return parcel ## Getting started Before you can begin using the Return portal API, you first need to have configured some settings related to the Return portal in your Sendcloud account. Read a step-by-step guide on how to set up your Return Portal in the Sendcloud help center. ## Authentication The Return portal API uses JWT authentication. Since this is a public facing API, the JWT token is generated upon a successful outgoing parcel lookup. 1. Look up the original shipment via the **Outgoing parcel lookup** endpoint 2. Two JWT authentication tokens will be provided - one for creating a new return parcel, and one for looking up service point locations 3. In order to create the return parcel, include an `Authorization` header with a `Bearer` schema in your request and enter the `access_token` you obtained by performing the **Outgoing parcel lookup**. # Retrieve a return label Source: https://sendcloud.dev/api/v2/return-portal/retrieve-a-return-label /.openapi/v2/return-portal/openapi.yaml get /brand/{brand_domain}/return-portal/label/download Download a return label as a PDF **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Once a return parcel has been successfully created and announced to the carrier, the label will be ready to download. This endpoint returns the return label file (in PDF format). You should not need to manually construct the URL for this endpoint, as it is returned in the response body for the [Retrieve the status of a return](/api/v2/return-portal/retrieve-the-status-of-a-return) endpoint. # Retrieve an outgoing parcel Source: https://sendcloud.dev/api/v2/return-portal/retrieve-an-outgoing-parcel /.openapi/v2/return-portal/openapi.yaml get /brand/{brand_domain}/return-portal/outgoing Find an outgoing parcel via two mandatory query parameters: either the tracking number or the order number, and the postal code. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). On a successful lookup, along with the parcel data, you will receive two JWT tokens: one for the incoming parcel creation, and one for service points lookup. # Retrieve return portal settings Source: https://sendcloud.dev/api/v2/return-portal/retrieve-return-portal-settings /.openapi/v2/return-portal/openapi.yaml get /brand/{brand_domain}/return-portal Retrieve information about the settings you have configured for your Sendcloud-hosted Return portal, including branding details, delivery options and return methods. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Due to the public nature of this API, you could potentially use this data for your own self-hosted returns solution. # Retrieve the status of a return Source: https://sendcloud.dev/api/v2/return-portal/retrieve-the-status-of-a-return /.openapi/v2/return-portal/openapi.yaml get /brand/{brand_domain}/return-portal/label/polling Find out the label creation status for a return parcel. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Once a return parcel has been successfully created, a polling URL is included in the response. Creating a label depends on the response time of the carrier, so you need to make a request to this endpoint to see the status of the label. The URL you received contains a token with the `id`, so you don't need to provide any additional lookup details or authentication. * A `200` response will indicate that the label is ready and can be downloaded. * A `202` response will indicate that the label is not ready to be downloaded but the return data has been accepted. If you have paid returns enabled this status is used to indicate we are waiting for payment. For more information take a look at [this help center article](https://support.sendcloud.com/hc/en-us/articles/5987289174420-Charge-customers-for-a-return-fee-via-the-return-portal). * A `500` response means that the label announcement failed. # Returns API overview Source: https://sendcloud.dev/api/v2/returns/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Sendcloud provides you with all the tools you need to make the return process hassle-free for your customers. You can create returns from any country in the world and ship them back home using a huge variety of dependable return shipping methods. The **Returns API** is responsible for providing details regarding your returns, including details of the original outgoing parcel, the incoming parcel and the returned items. The Returns API v2 is deprecated. Please plan to update to the [latest version of the Returns API](/api/v3/returns/) (v3), which has more features and improvements. # Retrieve a list of returns Source: https://sendcloud.dev/api/v2/returns/retrieve-a-list-of-returns /.openapi/v2/returns/openapi.yaml get /returns Retrieve a paginated list of all the returns belonging to the authenticated user, sorted by the creation date. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve a return Source: https://sendcloud.dev/api/v2/returns/retrieve-a-return /.openapi/v2/returns/openapi.yaml get /returns/{id} Retrieve the details of a specific return by its unique identifier. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Sender addresses API overview Source: https://sendcloud.dev/api/v2/sender-addresses/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Carriers require sender address information to be present on the shipping label. The **Sender addresses API** allows you to retrieve the sender addresses associated with your Sendcloud account. ## Default sender address You can have multiple sender addresses associated with your Sendcloud account, but one sender address must always be set as **default** in your account [address information](https://app.sendcloud.com/v2/settings/addresses/sender). If you choose not to specify a sender address when you use the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, the default sender address will be used. # Retrieve a list of sender addresses Source: https://sendcloud.dev/api/v2/sender-addresses/retrieve-a-list-of-sender-addresses /.openapi/v2/sender-addresses/openapi.yaml get /user/addresses/sender Returns a list of all the sender addresses which have been saved to your account. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The response will include the `id` of each address, which you can include as a parameter when [creating parcels](/api/v2/parcels/create-a-parcel-or-parcels) or [looking up shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) via the API. # Retrieve a sender address Source: https://sendcloud.dev/api/v2/sender-addresses/retrieve-a-sender-address /.openapi/v2/sender-addresses/openapi.yaml get /user/addresses/sender/{id} Retrieve information about a specific sender address saved to your account. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). A sender address `id` for use in this endpoint can be obtained from the [Retrieve a list of sender addresses](/api/v2/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint. # Service points API overview Source: https://sendcloud.dev/api/v2/service-points/index The **Service points API** provides you with the information you need to drop off or ship parcels to a service point. It allows you to retrieve service point locations, verify their availability and store them in the Sendcloud platform during the checkout process. ## Authentication Either [Basic Authentication](/docs/getting-started/authentication#basic-authentication) or an `access_token` query parameter can be used. You can find or obtain your key for Basic Authentication by following the instructions in our [Getting started guide](/docs/getting-started/) # Retrieve a list of service point carriers Source: https://sendcloud.dev/api/v2/service-points/retrieve-a-list-of-service-point-carriers /.openapi/v2/service-points/openapi.yaml get /carriers Retrieve a list of carriers which are enabled for service point delivery and can be accessed by the authenticating integration. Carriers can be enabled or disabled via the integration settings menu in the Sendcloud platform. # Retrieve a list of service points Source: https://sendcloud.dev/api/v2/service-points/retrieve-a-list-of-service-points /.openapi/v2/service-points/openapi.yaml get /service-points Retrieve a list of available service points and the associated service point `id`. Only service points which are applicable to the carriers you have enabled in the integration settings menu will be returned. You can filter the results based on GPS location or `address` in combination with a search `radius`. ## How carriers are selected * If the `carrier` parameter is **not provided**, service points for all carriers enabled in your integration settings are returned. * If the `carrier` parameter **is provided**, only service points for the specified carriers are returned. All requested carriers must be enabled in your integration settings — if any are not, a `400` error is returned. ## Notes * If provided, `latitude` and `longitude` specify a reference point from which a `distance` will be computed for each service point, and returned with the response. * Some carriers impose limits for certain service points. For this reason, you can specify the `weight` parameter to ensure that only usable service points are returned. Currently this only applies to Poste Italiane, which excludes `punto_poste` service points when the weight exceeds 15 kg. * If provided, `postal_code` will return a list of service points which are located **exactly within the bounds** of the specified postal code area. * The `address` parameter retrieves a list of service points closest to the geocoded location. You can limit the results through the `radius` parameter. * The `address` parameter accepts postal codes in addition to street names. * The `address` parameter should **not** be used together with `city`, `postal_code`, or `house_number`, as those perform exact matching. # Retrieve a service point Source: https://sendcloud.dev/api/v2/service-points/retrieve-a-service-point /.openapi/v2/service-points/openapi.yaml get /service-points/{service_point_id} Retrieve information about a specific service point location, including opening hours and applicable carriers, based on the service point `id`. # Retrieve availability of a service point Source: https://sendcloud.dev/api/v2/service-points/retrieve-availability-of-a-service-point /.openapi/v2/service-points/openapi.yaml get /service-points/{service_point_id}/check-availability Retrieve a `true` or `false` value which reflects the current availability of a given service point `id`. # Shipping methods API overview Source: https://sendcloud.dev/api/v2/shipping-methods/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Sendcloud partners with [160+ international carriers](https://www.sendcloud.com/how-it-works) who offer a wide variety of flexible **shipping methods**. Some methods are only available when you connect a [direct carrier contract](/docs/getting-started/carrier-contracts/), while others can be [enabled in your Sendcloud account](/docs/getting-started/) so you can start shipping with them straight away. A shipping method is a specific service offered by a carrier which determines the price and method of delivering a parcel to a customer. A parcel cannot be announced or have a shipping label created for it until a shipping method has been selected. The **Shipping methods API** lets you retrieve available shipping methods for your account and get detailed information about each one. For example, when you create a parcel via the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint and want to create a shipping label and announce it immediately, you first need to obtain a shipping method `id` to identify the service you want to use to deliver the parcel. You can do this via the endpoints in this API. # Retrieve a list of shipping methods Source: https://sendcloud.dev/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods /.openapi/v2/shipping-methods/openapi.yaml get /shipping_methods Returns a detailed list of all the shipping methods which are available to you under your Sendcloud credentials. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). You can use this endpoint to find a specific shipping method `id`, which you can then use in your request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. When creating a parcel via the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, if a shipping method `id` value is present, and if the `request_label` parameter has the value `true`, then a shipping label is created and the parcel is announced. The shipping methods returned from this endpoint are based on the following factors: 1. The carriers you have [enabled](/docs/getting-started/) in your Sendcloud account; 2. (Optional) The direct [carrier contracts](/docs/getting-started/carrier-contracts/) you have connected; 3. Your [sender address](/docs/getting-started/sender-address/) **Tip:** Via this endpoint you can only retrieve shipping methods based on three parameters: `sender_address`, `service_point_id` and `is_return`. If you need to filter the results because you require a method which contains a specific shipping functionality or other criteria, you can refer to the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint. In order to view **remote surcharges**, you are required to provide the `to_country` and `to_postal_code`. Similarly, to access **zonal prices**, you need to provide `to_country`, `from_postal_code` and `to_postal_code`. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones. ## Specifying a sender address You can have multiple sender addresses stored in your Sendcloud account. This endpoint will return the shipping methods associated with your **default** sender address, **unless** you provide a specific `sender_address` `id`. **Tip:** You can find the `id` for each of your sender addresses via the [Retrieve a sender address](/api/v2/sender-addresses/retrieve-a-sender-address) endpoint. For example, your default sender address may be based in the Netherlands, but you have a second sender address based in Austria. If you don't specify a `sender_address` `id`, this endpoint will **only** return shipping methods applicable for shipments from the Netherlands. To see shipping methods applicable for Austria, e.g. from DPD Austria, specify the `id` for your Austrian sender address in the HTTP request. The retrieved results will now include carriers such as Post AT, DPD Austria, etc, depending on your [enabled carriers](/docs/getting-started/). ```http Example request method and URL GET https://panel.sendcloud.sc/api/v2/shipping_methods?sender_address={ID} ``` ## Find a service point delivery shipping method If you want to retrieve a list of shipping methods which are applicable for **service point delivery**, provide a `service_point_id` as a query parameter. You can find an appropriate `service_point_id` via the [Service points API](/api/v2/service-points). ## Find a suitable shipping method for a return Return shipping methods are treated differently than methods for outgoing parcels. If you want to filter the results to show only the methods which you can apply to return parcels, include the query parameter `is_return=true`. ## Invalid shipment ID error message If you try to [Create a parcel](/api/v2/parcels/create-a-parcel-or-parcels) but receive the error message "Invalid shipment id", this could be because the specified `id` relates to a shipping method which is not possible for the given destination address. For example, if you need to ship a parcel internationally but the specific shipping method only supports national (domestic) shipping, then you would need to lookup a new shipping method `id` which supports method of delivery and change the request. # Retrieve a shipping method Source: https://sendcloud.dev/api/v2/shipping-methods/retrieve-a-shipping-method /.openapi/v2/shipping-methods/openapi.yaml get /shipping_methods/{id} Get information about a shipping method based on its `id` and your default sender address. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). As described in the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint, to retrieve information about a shipping method which operates in a different country than your default sender address, provide a different `sender_address` `id`. To see zonal carrier shipping methods, you need to provide the `to_country`, `from_postal_code` and `to_postal_code` query parameters. # Shipping prices API overview Source: https://sendcloud.dev/api/v2/shipping-prices/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The **Shipping prices API** allows you retrieve rates for a specific shipping method based on the specified `shipping_method_id`, which you can retrieve from the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint. If you don't have a direct carrier contract connected to your Sendcloud account, the rates returned via this endpoint will be provided by Sendcloud, discounted based on your current subscription plan. If you have connected your own carrier contract then rates for those carriers will be `null` **unless** you have uploaded your own contract pricing. Carriers that use pricing based on shipping zones (such as Spanish carriers which charge different rates based on the postal code of the shipment) are not supported. # Retrieve a shipping price Source: https://sendcloud.dev/api/v2/shipping-prices/retrieve-a-shipping-price /.openapi/v2/shipping-price/openapi.yaml get /shipping-price Retrieve shipping rate information for a specific `shipping_method_id` and `from_country`. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). For users that have uploaded their own prices, the response will show the prices that have been uploaded. The response is an array of prices for all available receiver countries. If the `to_country` query parameter is present, the array will only contain one item. Note that `price` and `currency` will be `null` when no pricing is available for a receiver country. If you have more than one active contract for a specific carrier, you must fill the `contract` attribute with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v2/contracts/retrieve-a-list-of-contracts) endpoint. In order to view **remote surcharges**, you are required to provide the `to_country` and `to_postal_code`. Similarly, to access **zonal prices**, you need to provide `to_country`, `from_postal_code` and `to_postal_code`. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones. # Shipping products API overview Source: https://sendcloud.dev/api/v2/shipping-products/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). A **shipping product** is the term used to refer to a **group of shipping methods** offered by a shipping carrier. The methods within the overall shipping product will share the same characteristics, but are differentiated from each other based on additional **shipping functionalities**, parcel **weight classes** or other criteria. The **Shipping products API** allows you to retrieve shipping products and their associated shipping methods, filtered by specific criteria and shipping functionalities. For example, the carrier PostNL offers several shipping products, one of which is *PostNL Standard*. The PostNL Standard shipping product consists of various individual **shipping methods**, such as: * PostNL Standard 0-23 kg * PostNL Standard with signature 0-23kg * PostNL Evening delivery + Home address only 0-23 kg, etc. In order to create a parcel and immediately announce it, an appropriate shipping method `id` is required. There are two methods of obtaining a shipping method `id` via the API: 1. Retrieve a list of all available shipping methods based on a default or specific sender address via the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint 2. Retrieve a list of shipping methods which **match a number of specific criteria and shipping functionalities** via the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint # Retrieve a list of shipping functionalities Source: https://sendcloud.dev/api/v2/shipping-products/retrieve-a-list-of-shipping-functionalities /.openapi/v2/shipping-products/openapi.yaml get /shipping-functionalities Lists all available shipping functionalities across the Sendcloud system. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). A shipping functionality is an additional characteristic or 'add on' service that defines one shipping method from another. Some functionalities are related to the form of the shipment that's accepted for shipment, such as letterbox, parcel or pallet, while other functionalities specify any additional handling that's required, such as Age check or Signature required. Functionalities can also denote specific delivery deadlines or weekend delivery availability. ## Glossary of shipping functionalities This glossary provides a description of every possible shipping functionality associated with a Sendcloud-supported shipping method. | Shipping functionality | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `age_check` | Indicates whether the recipient must be above a certain age (e.g., to accept alcohol products). | | `b2b` | Indicates whether the shipment is a b2b shipment. | | `b2c` | Indicates whether the shipment is a b2c shipment. | | `boxable` | Indicates whether the shipment fits in a box. | | `bulky_goods` | Indicates whether the shipment is bulky, e.g. it does not fit in a box. | | `carrier_billing_type` | Indicates whether the shipment is billed on a country to country basis, or based on a shipping zone to shipping zone. Example is shipping from mainland Spain to the Canary Islands (a zone) or Netherlands to the Netherlands (country to country). | | `cash_on_delivery` | Indicates whether the receiver of the shipment should pay for the shipment when receiving it. | | `dangerous_goods` | Indicates whether the shipment can contain dangerous goods. | | `delivery_attempts` | Indicates the number of delivery attempts the carrier should attempt before returning (or discarding) the parcel. | | `delivery_before` | Indicates whether the shipment will be delivered before a certain time of the day (Example: before 12:00). | | `delivery_deadline` | Indicates the period of time in which the shipment will be delivered (Example: 24 hours, 28 hours). | | `direct_contract_only` | Indicates whether shipping is only possible using your own carrier contract, or if it is possible using Sendcloud contract rates. | | `eco_delivery` | Indicates whether the shipping process will be environmentally friendly. | | `ers` | Indicates whether the shipment will use the ERS (Easy Return Solution) system. | | `first_mile` | Indicates how transportation of the first mile of the shipment will take place. Example is that the parcel is dropped of at a service point, or is picked up by the carrier. | | `flex_delivery` | Indicates whether the receiver of the parcel can, before delivery takes place, choose where and when the shipment should be delivered. | | `form_factor` | Indicates the form factor of the parcel. Examples are letter, pallet, parcel. | | `fragile_goods` | Indicates whether the shipment can contain fragile goods (glass, electronics, etcetera). | | `fresh_goods` | Indicates whether the shipment can contain fresh goods (e.g. food with an expiration date). | | `harmonized_label` | Indicates whether the shipment label contains the customs information on it as well. | | `id_check` | Indicates whether the receiver should identify him/herself to the carrier driver, conforming the identity of the receiver. | | `incoterm` | Indicates what incoterm is used for an (international) shipment. Mainly used to determine if the receiver or the sender pays the customs duties. | | `insurance` | Indicates whether the shipment has carrier insurance or not. | | `labelless` | Indicates whether a return shipment can be done using only a QR code or numerical number, needed by the end-consumer to return the parcel. In other words, no shipping label is required. | | `last_mile` | Indicates what the last mile of the shipment looks like. For instance, the shipment can be delivered to a service point or a home address. | | `manually` | Indicates a subset of Deutsche Post shipping methods where a consumer should manually attach the label to the parcel. | | `multicollo` | Indicates whether the shipment can be a multi-collo shipment. Note: Not all carriers support multicollo shipment. See the supported carriers and more in our help center | | `neighbor_delivery` | Indicates whether the shipment is allowed to be delivered at the neighbours of the receiver. | | `non_conveyable` | Indicates whether the shipment fits on a conveyor belt. | | `personalized_delivery` | Indicates a subset of Deutsche Post shipping methods shipping to a consumer. | | `premium` | Indicates whether the carrier identifies the shipment's shipping process as premium. | | `priority` | Indicates the priority level of the shipment. Examples are Express or Standard. | | `registered_delivery` | Indicates whether a Proof of Delivery (POD) is communicated to the sender. | | `returns` | Indicates whether the shipment should be a return shipment or not. | | `segment` | Indicates the international pricing zone for PostNL shipments. | | `service_area` | Indicates the service area of the shipment. Examples are domestic or international. | | `signature` | Indicates whether the shipment requires a signature upon delivery. | | `size` | Indicates the allowed size of the shipment. | | `sorted` | Indicates whether the shipment(s) are handed over the carrier in a sorted fashion, decreasing costs. | | `surcharge` | Indicates whether the carrier can surcharge the shipment later, based on (volumetric) weight. | | `tracked` | Indicates whether the shipment can be tracked online. | | `tyres` | Indicates whether the shipment can be used to ship tyres. | | `weekend_delivery` | Indicates whether the shipment can be delivered in the weekend or on a specific weekend-day. | # Retrieve a list of shipping products Source: https://sendcloud.dev/api/v2/shipping-products/retrieve-a-list-of-shipping-products /.openapi/v2/shipping-products/openapi.yaml get /shipping-products Retrieve a list of shipping methods that are associated with your account, filtered by specific criteria such as parcel dimensions, weight classes, from and to country and **shipping functionality.** **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). In situations where you need to find a method which supports a specific means of delivery, type of parcel or delivery deadline, for example, this endpoint allows you to filter all available shipping methods based on one or more query parameters. The response body will include the `id` of any suitable methods, which you can then use with the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint and announce the shipment directly. You must have either [enabled a carrier](/docs/getting-started/) in your Sendcloud account, or connected your own direct [carrier contract](/docs/getting-started/carrier-contracts/), in order to be able to retrieve shipping methods related to that carrier via this endpoint. If you have more than one active contract for a specific carrier, you must include the `contract` attribute with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/contracts/retrieve-a-list-of-contracts) endpoint. To see zonal carrier shipping methods, you need to provide the `from_postal_code` and `to_postal_code` query parameters. To filter by `shipping_functionality`, you can find a glossary of accepted values and a description of each functionality under the [Retrieve a list of shipping functionalities](/api/shipping-products/retrieve-a-list-of-shipping-functionalities) endpoint. ## Use cases Find a shipping method for a parcel weighing 5kg, shipping from the Netherlands to the United States with carrier PostNL. ```http GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=US&carrier=postnl&weight=5&weight_unit=kilogram ``` Find a shipping method which includes the Age Check functionality for shipping alcohol products from France to Belgium. ```http GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=BE&age_check=18 ``` Find a shipping method that supports same day delivery for a product shipping from the Netherlands to the Netherlands. ```http GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=NL&delivery_deadline=sameday ``` Find a **return** shipping method for a parcel returning from France to the Netherlands: ```http GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=FR&to_country=NL&returns=true ``` # Tracking API overview Source: https://sendcloud.dev/api/v2/tracking/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). The Tracking API allows you to obtain the status of a given parcel at any point during the delivery journey, across all Sendcloud supported carriers. At each new stage of the delivery journey, a status message will be returned to indicate the current progress of the shipment. The response body will also include the entire history of the parcel up until the current moment, plus dates and timestamps (UTC timezone) to indicate when each status was last updated. # Retrieve tracking information of a parcel Source: https://sendcloud.dev/api/v2/tracking/retrieve-tracking-information-of-a-parcel /.openapi/v2/tracking/openapi.yaml get /tracking/{tracking_number} Fetches detailed tracking information, including the status history of the parcel. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Retrieve your user data Source: https://sendcloud.dev/api/v2/users/retrieve-your-user-data /.openapi/v2/users/openapi.yaml get /user Request the data connected with your user account. The response includes your invoice address details, your Sendcloud username, and a list of all your invoices with the associated invoice `id`s. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Webhooks overview Source: https://sendcloud.dev/api/v2/webhooks/index **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). Sendcloud is able to actively communicate updates in a parcel (such as updates in the delivery status) to your application using webhooks. You should specify an JSON API endpoint in which Sendcloud will make requests to, whenever a change occurs. You can set this using the `webhook_url` field in your integration settings in Sendcloud. To verify a request is coming from Sendcloud, Sendcloud signs each request that we send to your endpoint using a HMAC signature (Hash-based Message Authentication Code) with SHA256 algorithm and the `Secret Key` or the `Webhook Signature Key` as secret, depending on your integration type. For your store to validate that the webhook is coming from us, you should hash the message received from us using your secret and compare against the `Sendcloud-Signature` header received from us. ```php PHP example icon=php theme={null} '1eed4b3d41f4653ac64fd56f1bf1cbfd349e4482cbc11dff7134bd93e5da4b0a' ``` To receive the parcel data for every update that happens in a parcel, you need to: * Visit your Integration settings within the Sendcloud platform. * Enable the webhook feedback checkbox. * Set the webhook url to your application that will process the data received. \* You can also test if the webhook works by sending a test webhook to your application by clicking on “Test API Webhook” button. * Save the shop settings. Additional notes: * Please note that the data your application will receive is the same as the payload you would get when retrieving information about a specific parcel. * If for any reason the call to your webhook fails, Sendcloud will retry sending the update 10 times with an exponential delay. Starting with a 5 minute delay, and a maximum delay of 1 hour between retries. If after 10 tries, the call is still failing, Sendcloud will stop trying, and report the issue to your Failed Request logs. * Because your shop might be unreachable for some time, the webhook arrival order might be scattered (unordered) which is why each webhook includes a timestamp which can be used to identify which webhook is the later one. * For return parcels, you will receive webhook updates only if the outgoing shipment was created through the API Shop. # Integration connected Source: https://sendcloud.dev/api/v2/webhooks/integration-connected /.openapi/v2/webhooks/openapi.yaml webhook IntegrationConnected A request is sent to the defined webhook whenever the integration is created within our system. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Integration deleted Source: https://sendcloud.dev/api/v2/webhooks/integration-deleted /.openapi/v2/webhooks/openapi.yaml webhook IntegrationDeleted A request is sent to the defined webhook whenever the integration is deleted from our system. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Integration modified Source: https://sendcloud.dev/api/v2/webhooks/integration-modified /.openapi/v2/webhooks/openapi.yaml webhook IntegrationModified A request is sent to the defined webhook whenever the integration is updated. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Parcel status changed Source: https://sendcloud.dev/api/v2/webhooks/parcel-status-changed /.openapi/v2/webhooks/openapi.yaml webhook ParcelStatusChanged Happens whenever a parcel within this integration shifts to a different status. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Return created Source: https://sendcloud.dev/api/v2/webhooks/return-created /.openapi/v2/webhooks/openapi.yaml webhook ReturnCreated Happens whenever a return is created from a parcel matching the integration. **API v2 is entering maintenance mode.** New users should start with API v3 to access our latest features and improved performance. Already using v2? Don't worry, your current integration remains fully functional. Read more about [maintenance mode](/docs/getting-started/api-version-guide), or check out the [migration guide for API v3](/docs/getting-started/migration-guidelines-for-api-v3). # Validate an address Source: https://sendcloud.dev/api/v3/address/validate /.openapi/v3/shipments/openapi.yaml post /addresses/validate This address validation endpoint allows you to validate shipping addresses before using them. By validating addresses in advance, you can ensure that the shipping information is accurate and complete, reducing the risk of delivery issues and improving overall shipping efficiency. Providing the carrier helps to tailor the address validation process according to specific carrier requirements. Using additional validation methods can further enhance the accuracy of the address verification. The default Sendcloud validation, will always be applied, has in 2 steps: 1. checks the address against the carrier limits (e.g. maximum length of the address line, existence of the postal code for the country, etc.). see also [Carrier address limits](/docs/addresses/address-field-limits#address-field-limits). 2. optimizes (washes) the address to fit within the carrier limits. (e.g. deduplication of address lines, abbreviations, etc.) This address validation endpoint allows you to validate shipping addresses before using them. By validating addresses in advance, you can ensure that the shipping information is accurate and complete, reducing the risk of delivery issues and improving overall shipping efficiency. Providing the carrier helps to tailor the address validation process according to specific carrier requirements. Using additional validation methods can further enhance the accuracy of the address verification. The default Sendcloud validation, will always be applied, has in 2 steps: 1. checks the address against the carrier limits (e.g. maximum length of the address line, existence of the postal code for the country, etc.). see also [Carrier address limits](/docs/addresses/address-field-limits#address-field-limits). 2. optimizes (washes) the address to fit within the carrier limits. (e.g. deduplication of address lines, abbreviations, etc.) # Analytics API overview Source: https://sendcloud.dev/api/v3/analytics/index **BETA** - The Analytics API is currently in beta. Endpoints and behavior may change as the feature evolves. The Analytics API exposes aggregated shipping insights derived from your account's shipping activity, so you can measure carrier performance and identify trends across origins, destinations, and time windows. Analytics endpoints are gated by per-feature access. Depending on your account's plan and enabled features, some endpoints in this API may not be available to you. ## What can you do with this API? ### Measure carrier transit times Retrieve median transit-time statistics for one or more carriers over a configurable date window. You can break the data down by origin and destination country to compare lanes, spot regressions, and benchmark carriers against each other. ### Measure shipping option transit times Retrieve median transit-time statistics for one or more shipping options over a configurable date window. Useful for comparing the options you offer in your checkout against each other and for setting realistic delivery promises per lane. # Retrieve carrier transit times Source: https://sendcloud.dev/api/v3/analytics/retrieve-carrier-transit-times /.openapi/v3/analytics/openapi.yaml get /analytics/transit-times/carriers Returns aggregated transit-time statistics per carrier, optionally filtered by origin and destination country and a date window. Transit times are aggregated from your account's recent shipping activity. The response contains one record per `(carrier_code, from_country_code, to_country_code)` row; rows with no transit-time data are omitted. When `start_date` and `end_date` are omitted, the response covers the last 90 days (UTC). `start_date` must be on or before `end_date`. # Retrieve shipping option transit times Source: https://sendcloud.dev/api/v3/analytics/retrieve-shipping-option-transit-times /.openapi/v3/analytics/openapi.yaml get /analytics/transit-times/shipping-options Returns aggregated transit-time statistics per shipping option, optionally filtered by origin and destination country and a date window. Transit times are aggregated from your account's recent shipping activity. The response contains one record per `(shipping_option_code, from_country_code, to_country_code)` row; rows with no transit-time data are omitted. When `start_date` and `end_date` are omitted, the response covers the last 90 days (UTC). `start_date` must be on or before `end_date`. # Retrieve a brand Source: https://sendcloud.dev/api/v3/brands/retrieve-a-brand /.openapi/v3/brands/openapi.yaml get /brands/{id} Retrieves a user's configured brand and its properties, identified by its unique ID. # Retrieve a list of brands Source: https://sendcloud.dev/api/v3/brands/retrieve-a-list-of-brands /.openapi/v3/brands/openapi.yaml get /brands Retrieves a list of all brands and their associated properties. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. # Finalize a Deutsche Post order Source: https://sendcloud.dev/api/v3/carriers-dp/finalize-a-deutsche-post-order /.openapi/v3/carriers-dp/openapi.yaml post /carriers/dp/finalize-order Closes the current open order/box and generates AWB (Air Waybill) documents for all parcels in that box. **How it works:** 1. As you create Deutsche Post International parcels, they are automatically added to the current box (identified by the current box_number). 2. When the box is full or you're ready to ship, call this endpoint to finalize the box. 3. The finalization process: - Generates a single AWB label that is shared by all parcels in the finalized box - Attaches the AWB label to all parcels in the box - Increments the box_number, automatically starting a new box for subsequent parcels 4. You can create and finalize multiple boxes throughout the day as needed. **Important notes:** - Each box has its own unique AWB label - All parcels within a single box share the same AWB label - The AWB document can be retrieved from any parcel that was in the finalized box - New parcels created after finalization will be added to the new box # API v3 Changelog Source: https://sendcloud.dev/api/v3/changelog ## Changed endpoints: * Changes for **POST** `/api/v3/shipments`: * Field `delivery_dates.earliest_delivery_time` added: earliest local time of day for delivery, in `HH:MM` format * Field `delivery_dates.latest_delivery_time` added: latest local time of day for delivery, in `HH:MM` format ## Changed endpoints: * Changes for address validation response: * Field `invalid_attributes` added to the `analysis` object, listing attributes that are invalid (i.e. below the field-level validation threshold) ## Changed endpoints: * Changes for **GET** `/api/v3/events`: * Field `actor_id` added to the event response ## Changed endpoints: * Changes for webhook **POST** `parcels.event.created`: * Field `order_number` added to the `parcel` object in the event payload ## Changed endpoints: * Changes for **POST** `/api/v3/shipments/announce`: * Field `tracking_numbers` added to parcel objects in response `201` * Changes for **GET** `/api/v3/shipments`: * Field `tracking_numbers` added to parcel objects in response `200` * Changes for **POST** `/api/v3/shipments`: * Field `tracking_numbers` added to parcel objects in response `201` * Changes for **POST** `/api/v3/shipments/announce-with-rules`: * Field `tracking_numbers` added to parcel objects in response `201` * Changes for **POST** `/api/v3/shipments/with-rules`: * Field `tracking_numbers` added to parcel objects in response `201` * Changes for **GET** `/api/v3/shipments/{id}`: * Field `tracking_numbers` added to parcel objects in response `200` ## Changed endpoints: * Changes for **POST** `/api/v3/shipments` and **POST** `/api/v3/shipments/announce`: * Field `carrier_fields` at the parcel level now supports Chronopost with `expiration_date` (string or null, `yyyy-mm-dd`): the best-before date of the parcel's contents. Required when shipping with a Chronopost Chrono Fresh product, in which case it must be at least 5 days from the current date; ignored for other Chronopost products. ## Changed endpoints: * Changes for **GET** `/api/v3/dsf/tickets`: * Parameter `tracking_number` added (filter by parcel tracking number) * Changes for **GET** `/api/v3/dsf/tickets/{ticket_id}`: * Response `200`: Field `tracking_number` added to ticket object ## Changed endpoints: * Changes for **POST** `/api/v3/sync/shipments`: * Response `409` added: returns the existing shipment when a duplicate `external_reference_id` is detected * Changes for **POST** `/api/v3/shipments`: * Response `409` added: returns the existing shipment when a duplicate `external_reference_id` is detected * Changes for **POST** `/api/v3/sync/shipments` (with shipping rules): * Response `409` added: returns the existing shipment when a duplicate `external_reference_id` is detected * Changes for **POST** `/api/v3/shipments` (with shipping rules): * Response `409` added: returns the existing shipment when a duplicate `external_reference_id` is detected ## Added endpoints: * **GET** `/shipping-rules/rules` * **POST** `/shipping-rules/rules` * **POST** `/shipping-rules/rules/reorder` * **GET** `/shipping-rules/rules/{rule_id}` * **PATCH** `/shipping-rules/rules/{rule_id}` * **DELETE** `/shipping-rules/rules/{rule_id}` * **GET** `/shipping-rules/actions` * **GET** `/shipping-rules/actions/{identifier}` * **GET** `/shipping-rules/operators` * **GET** `/shipping-rules/conditions` * **GET** `/shipping-rules/conditions/{identifier}` ## Changed endpoints: * Changes for **POST** `/api/v3/orders` and **PATCH** `/api/v3/orders/{id}`: * Field `service_point_details`: This field is for API usage only and will not be reflected in the Incoming Order View (IOV) ## Changed endpoints: * Changes for **GET** `/api/v3/parcels/{id}/documents/{type}`: * Added a new `proof-of-delivery` document type. It is retrieved directly from the carrier on request, is only available once the parcel has been delivered, and is only returned in PDF format (`application/pdf`). Availability depends on the carrier supporting proof of delivery. ## Changed endpoints: * Changes for **GET** `/api/v3/shipping-options`: * Field `lead_time` in the response is now nullable (previously required integer, now integer or null) ## Changed endpoints: * Corrected the Shipments API response field name from `delivery-dates` to `delivery_dates`. ## Changed endpoints: * Changes for **POST** `/api/v3/shipments` and **POST** `/api/v3/shipments/announce`: * `parcel_items` array now accepts two distinct item types based on shipment destination: * **Domestic shipments**: `quantity` defaults to `1`, `weight` defaults to `0.001 kg`, and `price` defaults to `0.00` if not provided * **International shipments**: `description`, `quantity`, `weight`, `price`, `hs_code`, and `origin_country` are required * Field descriptions for `hs_code` and `origin_country` updated to clarify requirements based on shipment type * Changes for **GET** `/api/v3/shipments/{id}` and related shipment response endpoints: * `parcel_items` in responses now always includes all fields: `hs_code`, `weight`, `description`, `price`, and `quantity` ## Deprecated endpoints: * **GET** `/api/v3/checkout/configurations/{configuration_id}/delivery-options` — Deprecated as of June 9, 2026. Use **POST** `/api/v3/checkout/delivery-options` instead, which does not require a `configuration_id` in the URL and accepts cart and order details in a request body. ## Changed endpoints: * **GET** `/api/v3/service-points` — Now generally available. * **GET** `/api/v3/service-points/{service_point_id}` — Now generally available. * **POST** `/api/v3/service-points/{service_point_id}/check-availability` — Now generally available. ## Added endpoints: **Invoice Items API** (beta): * **GET** `/api/v3/invoice-items` * **GET** `/api/v3/invoice-items/{invoice_item_id}` **Invoices API** (beta): * **GET** `/api/v3/invoices` * **GET** `/api/v3/invoices/{invoice_id}` ## Changed endpoints: * Changes for **POST** `/parcels/tracking`: * Response `409` now only occurs during concurrent race conditions; duplicate submissions now return `200` instead * Response now includes `created` field (boolean) indicating whether the parcel was newly created (`true`) or already existed (`false`); the endpoint is now idempotent based on `source_id`, `carrier_code`, and organization ## Changed endpoints: * Changes for shipment creation endpoints: * `carrier_shipment_extras`: Now explicitly supports an empty object, clarifying that the field can be omitted for carriers without declared shipment-level extras * `carrier_parcel_extras`: Now explicitly supports an empty object, clarifying that the field can be omitted for carriers without declared parcel-level extras ## Changed endpoints: * Changes for **POST** `/api/v3/dsf/files`: * Response `415` added: file type not allowed * Response `400` error message updated to clarify that the `file` field is required * Response `413` description updated to clarify maximum file size is 6 MB * Field `file` in request body: description added, documenting filename requirement, content type rules, and 6 MB size limit * Documentation expanded with guidance on multipart/form-data requirements, allowed content types, size limits, and error meanings ## Added endpoints: * **POST** `/checkout/delivery-options`: Generate a list of delivery options based on cart or order details. This endpoint uses the currently active Dynamic Checkout configuration for the authenticated API integration — no `configuration_id` is required. Returns `400` if no published configuration exists for the integration. ## Changed endpoints: * Changes for **GET** `/checkout/{configuration_id}/delivery-options`: * Response `400` and `404` error examples updated: `status` values corrected from integers to strings ## Changed endpoints: * Changes for **POST** `/api/v3/shipments` (and related shipment creation endpoints): * Field `carrier_fields` added to shipment-level request body: optional carrier-specific shipment-level fields; currently supports DHL Express with `hide_sender` (boolean or null) to omit the sender address from the shipping label * Field `carrier_fields` added to parcel-level request body: optional carrier-specific parcel-level fields; currently supports Dynalogic with `collo_barcode` (string or null) to override the collo barcode reported to Dynalogic ## Changed endpoints: * Changes for **POST** `/api/v3/shipments` (and related shipment creation endpoints): * Field `export_reason` now accepts two additional values: `returned_goods` and `personal_use` * Changes for **POST** `/api/v3/returns` (and related return creation endpoints): * Field `export_reason` now accepts an additional value: `personal_use` ## Changed endpoints: * Changes for **POST** `/shipments` and **POST** `/shipments/announce-with-shipping-rules`: * Field `manufacturer_product_id` added to parcel items (optional, max 70 characters) * Field `manufacturer_product_id_std` added to parcel items (optional, max 70 characters; use for standardized identifiers such as GTIN) * Changes for **GET** `/shipments/{id}`: * Field `manufacturer_product_id` added to parcel items in response * Field `manufacturer_product_id_std` added to parcel items in response * Changes for parcel tracking: * Field `manufacturer_product_id` added to parcel items (optional, max 70 characters) * Field `manufacturer_product_id_std` added to parcel items (optional, max 70 characters) * Changes for Returns API: * Fields `dangerous_goods`, `dds_reference`, and `taric_doc_code` added to return parcel items * Field `manufacturer_product_id` added to return parcel items (optional, max 70 characters) * Field `manufacturer_product_id_std` added to return parcel items (optional, max 70 characters) ## Changed endpoints: * Changes for **POST** `/api/v3/support/tickets`: * Response field `ticket_id` type changed from `string` to `integer` ## Added endpoints: * **GET** `/api/v3/analytics/transit-times/carriers` — Returns aggregated transit-time statistics per carrier, filterable by origin/destination country and date window. Marked as Beta. * **GET** `/api/v3/analytics/transit-times/shipping-options` — Returns aggregated transit-time statistics per shipping option, filterable by origin/destination country and date window. Marked as Beta. ## Added endpoints: * **POST** `/api/v3/reporting/parcels` — Create a parcels report (CSV export of outgoing or incoming parcels); returns a report `id` and initial `status` * **GET** `/api/v3/reporting/parcels/{report_id}` — Retrieve a parcels report by `id`; poll until `status` is `ready`, then download the CSV from the `url` field ## Changed endpoints: * Changes for **POST** `/api/v3/support/tickets`: * Response `202`: `ticket_id` is now returned as a numeric integer instead of a UUID string ## Changed endpoints: * **GET** `/api/v3/integrations`: OAuth2 authentication is now supported * **GET** `/api/v3/integrations/{id}`: OAuth2 authentication is now supported * **PATCH** `/api/v3/integrations/{id}`: OAuth2 authentication is now supported * **DELETE** `/api/v3/integrations/{id}`: OAuth2 authentication is now supported * **GET** `/api/v3/integrations/logs`: OAuth2 authentication is now supported * **GET** `/api/v3/integrations/{id}/logs`: OAuth2 authentication is now supported * **POST** `/api/v3/integrations/{id}/logs`: OAuth2 authentication is now supported * **GET** `/api/v3/shop-order-statuses`: OAuth2 authentication is now supported * **POST** `/api/v3/shop-order-statuses`: OAuth2 authentication is now supported * **GET** `/api/v3/shop-order-statuses/mapping`: OAuth2 authentication is now supported * **POST** `/api/v3/shop-order-statuses/mapping`: OAuth2 authentication is now supported ## Changed endpoints: * Changes for **GET** `/api/v3/service-points`: * Endpoint is now publicly visible * Parameter `country_code` now has a maximum length of 2 characters * Field `geocoding.formatted_address` added to the `200` response * Field `geocoding.status` now supports a new `partially_matched` value * Field `geocoding.precision` now supports a new `region` value * Response `400` now includes new error examples for service points not enabled for an integration and unsupported carriers * Response `503` added for cases where address geocoding is temporarily unavailable * Documentation updated: clarified that `address_house_number` must be combined with `address_street` or `address_postal_code`; clarified that bounding box diagonal must not exceed 50 km; added guidance on `partially_matched` geocoding status * Changes for **GET** `/api/v3/service-points/{service_point_id}`: * Endpoint is now publicly visible * Changes for **POST** `/api/v3/service-points/{service_point_id}/check-availability`: * Endpoint is now publicly visible ## Changed endpoints: * Changes for **POST** `/addresses/validate`: * Description updated to clarify the validation process: carrier limit checks and address optimization * Response `200` schema updated: * Field `input_address_is_valid` added (boolean, indicates if the input address is valid) ## Changed endpoints: * Changes for **POST** `/shipments`: * Field `package_type` added to parcel objects in the response * Changes for **GET** `/shipments`: * Field `package_type` added to parcel objects in the response * Changes for **GET** `/shipments/{id}`: * Field `package_type` added to parcel objects in the response ## Added fields: * Field `package_type` added to parcel objects. Defines how parcels are packed (e.g., `package`, `euro_pallet`, `block_pallet`, `mini_pallet`, `one_way_pallet`, `tube`, `over_size_pallet`, `bundle`, `half_pallet`, `letterbox`). Required for carriers with specific packaging needs such as pallet carriers. ## Added endpoints: * **POST** `/api/v3/shipping/duties-and-taxes` — Calculate import duties and taxes for an international shipment. Returns per-item duty and tax breakdown, shipment-level totals, and destination country de minimis thresholds. Currently in beta and available to enterprise customers only. ## Changed endpoints: * Changes for **Ship an Order API** document responses: * Field `type` in `documents` object marked as deprecated * Field `type` enum expanded with new values: `cn23`, `cp71`, `cn23-default`, `qr` * Field `document_type` added to `documents` object with values: `label`, `customs-declaration`, `air-waybill` * Changes for **Shipments API** document responses: * Field `type` in `documents` object marked as deprecated * Field `type` enum expanded with new values: `cn23`, `cp71`, `cn23-default`, `qr` * Field `document_type` added to `documents` object with values: `label`, `customs-declaration`, `air-waybill` ## Changed endpoints: * Changes across **Orders API**, **Parcel Tracking API**, **Pickups API**, **Returns API**, **Sender Addresses API**, and **Shipments API**: * Field `state_province_code` description updated to clarify it is required for certain countries, with a link to international shipping documentation * Changes for **Returns API** and **Shipments API** customs information: * Field `state_province_code` description updated to clarify it is required for certain countries (USA, Canada, Italy, Australia), with a link to international shipping documentation * Changes for **Pickups API** pickup address: * Field `state_province_code` description updated to clarify it is required for certain countries, with a link to international shipping documentation ## Changed endpoints: * Changes for **POST** `/api/v3/shipments/address-washer`: * Fixed typo in `validation_methods` field description ("optinal" → "optional") ## Changed endpoints: * Shipping option address fields no longer have default values: * `postal_code` * `address_line_1` * `city` ## Changed endpoints: * Changes for **POST** `/shipping-options`: * Field `state_province_code` example updated to `RM-IT` ## Changed endpoints: * Changes for **GET** `/parcels/tracking/{tracking_number}`: * Bearer token authentication removed as a supported authentication method * Changes for **POST** `/parcels/tracking`: * Bearer token authentication removed as a supported authentication method ## Changed endpoints: * Changes for **POST** `/shipping-options`: * Field `from_address` added to request body — accepts an address object with `country_code`, `postal_code`, `address_line_1`, `city`, and `state_province_code` fields. Cannot be combined with `from_country_code` or `from_postal_code`. * Field `to_address` added to request body — accepts an address object with `country_code`, `postal_code`, `address_line_1`, `city`, and `state_province_code` fields. Cannot be combined with `to_country_code` or `to_postal_code`. * Field `from_country_code` deprecated. Use `from_address` instead. * Field `to_country_code` deprecated. Use `to_address` instead. * Field `from_postal_code` deprecated. Use `from_address` instead. * Field `to_postal_code` deprecated. Use `to_address` instead. ## Changed endpoints: * Changes for **POST** `/shipments/announce-with-shipping-rules`: * Documentation updated to clarify that `from_address`, `ship_with`, and `parcels` fields must be provided if no shipping rules or defaults are configured to assign them automatically * Changes for **POST** `/shipments/create-with-shipping-rules`: * Documentation updated to clarify that `from_address`, `ship_with`, and `parcels` fields must be provided if no shipping rules or defaults are configured to assign them automatically ## Changed endpoints: * Changes for **POST** `/api/v3/shipments`: * Field `validation_methods` description expanded to clarify behavior when using the "Here" validation method: Sendcloud will attempt to verify and correct the provided address based on the best available match; if no suitable match is found, the request returns an error; only address components recognised by the provider will be kept, and additional details (e.g. delivery notes) should be passed via `parcels.label_notes` instead ## Removed endpoints: * **GET** `/event-subscriptions/connections/authorization/callback` ## Changed endpoints: * Changes for **POST** `/parcels/tracking`: * Documentation updated ## Changed endpoints: * Changes for **POST** `/parcels/tracking`: * Documentation updated to note that including `shipping_option_code` in the `ship_with` property is required for parcels to appear in Analytics ## Changed endpoints: * Changes for **POST** `/parcels/tracking`: * Summary updated from "Create a tracking-only parcel" to "Create an external parcel for tracking" * Description updated to clarify the endpoint registers an external parcel for tracking ## Added endpoints: * **GET** `/api/v3/service-points` — Search for service points by carrier, country, location (coordinates, free-text address, or structured address), bounding box, or carrier-specific identifiers. Supports filtering by shop type and search radius. * **GET** `/api/v3/service-points/{service_point_id}` — Retrieve a single service point by its Sendcloud identifier. * **POST** `/api/v3/service-points/{service_point_id}/check-availability` — Check whether a specific service point is currently available. ## Changed endpoints: * Changes for **POST** `/api/v3/shipments` and **PUT** `/api/v3/shipments/{id}`: * Field `from_address` is now explicitly required on shipment request and response objects * Field `from_address` now accepts either a full address object or a `sender_address_id` referencing a pre-configured sender address * When using `sender_address_id`, if the referenced sender address has a brand or tax numbers configured, those will be used by default. However, explicitly provided `brand_id` or `tax_numbers` in the request will take precedence ## Added endpoints: * **GET** `/api/v3/dsf/tickets` — Retrieve a paginated list of support tickets with optional filters for status, carrier, parcel ID, and date range * **GET** `/api/v3/dsf/tickets/{ticket_id}` — Retrieve a single support ticket by ID ## Changed endpoints: * **GET** `/api/v3/dsf/tickets`: * Query parameters added: `page`, `size`, `status`, `parcel_id`, `carrier`, `created_after`, `created_before` * Response includes paginated results with: `total`, `page`, `pages`, `size`, `items` * Each ticket includes: `id`, `status`, `stage`, `type`, `parcel_id`, `carrier`, `order_number`, `brand_id`, `created_at`, `updated_at`, `requested_actions`, `resolution` * Response `400` added for invalid filter values * **GET** `/api/v3/dsf/tickets/{ticket_id}`: * Response includes ticket fields: `id`, `status`, `stage`, `type`, `parcel_id`, `carrier`, `order_number`, `brand_id`, `created_at`, `updated_at`, `requested_actions`, `resolution` * Response `404` added when ticket does not exist or does not belong to the organization ## Changed endpoints: * Changes for **POST** `/api/v3/support/provide-requested-data`: * Field `sales_date` added to `sales_data` array items — an optional date-time field specifying the date of the sale, used as the invoice date when generating sales invoices; if omitted, the parcel announcement date is used ## Added endpoints: * **POST** `webhooks/ParcelEventCreated` — Webhook event delivered to your connection endpoint when a parcel tracking event occurs (e.g., status changes such as shipped, delivered, or returned). Subscribe using event type `parcels.event.created`. ## Removed endpoints: * **GET** `/event-subscriptions/connections/type/{connection_type}` ## Changed endpoints: * **POST** `/event-subscriptions/broadcast/test/{subscription_id}`: * Summary updated from "Test event delivery" to "Broadcast test event" ## Removed endpoints: * **GET** `/event-subscriptions/subscriptions/event/{event_type}` ## Changed endpoints: * Changes for **GET** `/event-subscriptions/connections`: * Query parameter `connection_type` added (enum: `webhook`, `klaviyo`) — filter connections by type * Changes for **GET** `/event-subscriptions/subscriptions`: * Query parameter `event_type` added — filter subscriptions by event type * Query parameter `is_active` added — filter subscriptions by active status ## Changed endpoints: * Changes for **POST** `/api/v3/shipments` (sync) and **POST** `/api/v3/shipments` (async): * Field `goods_description` added to `customs_information` request body and response (optional string, max 255 characters; used for customs clearance purposes — note: not supported by all carriers) * Field `general_notes` in `customs_information` no longer has a minimum length requirement ## Changed endpoints: * Changes for **POST** `/api/v3/shipments/announce` (announce shipment with rules): * Response `201` now includes field `applied_shipping_rules` — a list of shipping rules that were applied to the shipment, each containing the rule `id`, rule `name`, and a `result` object describing the modifications made * Changes for **POST** `/api/v3/shipments` (create shipment with rules): * Response `201` now includes field `applied_shipping_rules` — a list of shipping rules that were applied to the shipment, each containing the rule `id`, rule `name`, and a `result` object describing the modifications made ## Changed endpoints: * Changes for **POST** `/shipping-options`: * Field `message` added to response `200` / `application/json` ## Changed endpoints: * Changes for **POST** `/api/v3/support/provide-requested-data`: * Field `request_id` description updated with reference to the GET endpoint for retrieval * Field `comment` description clarified as optional * Field `attachments` description updated with links to file upload and document generation endpoints * Field `attachments[].file_token` description updated to reference the file upload endpoint * Field `sales_data` description clarified as required when `data_type` is `sales_data` * Field `force` added (boolean, default `false`): bypasses the maximum invoice amount validation of 5000 EUR * Response `404` now returns `request_id not found` detail instead of generic `Not found` * Documentation updated: clarified that `comment` field is not required for providing data contents * Example updated to include `force: true` for sales data requests * Changes for **POST** `/api/v3/support/generate-claim-letter`: * Documentation updated: the generated PDF returns a file token usable with the Create a requested data response endpoint or when creating tickets ## Changed endpoints: * Changes for **POST** `ParcelStatusChanged`: * Description updated to clarify that only parcels created through the specific integration will trigger this webhook ## Changed endpoints: * Changes for **POST** `/shipment` (sync): * Response `201` / `application/json` changed: * Field `carrier` added to shipment response object (contains `code` and `name` subfields) * Changes for **POST** `/shipments` (async): * Response `201` / `application/json` changed: * Field `carrier` added to shipment response object (contains `code` and `name` subfields) * Changes for **POST** `/shipments` (with rules): * Response `201` / `application/json` changed: * Field `carrier` added to shipment response object (contains `code` and `name` subfields) * Changes for `base-shipment-response` schema: * Field `carrier` added: a read-only object containing carrier `code` (Sendcloud unique identifier) and `name` (friendly name) ## Changed endpoints: * Changes for `last_mile` field in shipping product/method properties (Returns API and Shipping Options API): * Enum value `pobox` removed from `last_mile` field * Enum value `locker` added to `last_mile` field (shipment delivered to a locker) * Enum value `locker_or_service_point` added to `last_mile` field (shipment delivered to a locker or a service point) * Fixed typo in `MAILBOX` description: `recepient` → `recipient` ## Added endpoints: * **POST** `/api/v3/dsf/documents/generate/invoice` — Generate a sales invoice PDF for a parcel * **POST** `/api/v3/dsf/documents/generate/claim-letter` — Generate a claim letter PDF for a parcel ## Changed endpoints: * Changes for **POST** `/api/v3/dsf/files`: * Description updated: file token can now be used when attaching files to tickets or when submitting requested data * Response `429` now references endpoint-specific rate limit response (30 requests per minute) * Changes for **GET** `/api/v3/dsf/carrier-support-contacts`: * Response `429` added * Changes for **PATCH** `/api/v3/dsf/carrier-support-contacts/{id}`: * Response `429` added * Changes for **DELETE** `/api/v3/dsf/carrier-support-contacts/{id}`: * Response `429` added * Changes for **POST** `/api/v3/dsf/tickets/damage`: * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **POST** `/api/v3/dsf/tickets/delay`: * `deprecated: true` flag removed * Description updated: endpoint now explicitly scoped to Sendcloud rates parcels only * Request body no longer accepts own contract parcel schema (`CreateDelayedOwnContract`); only `CreateDelayedTransactional` is accepted * Schema `CreateDelayedOwnContract` removed * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **POST** `/api/v3/dsf/tickets/late-delivery`: * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **POST** `/api/v3/dsf/tickets/lost`: * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **POST** `/api/v3/dsf/tickets/delivered-but-not-received`: * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **POST** `/api/v3/dsf/tickets/unjust-return`: * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **POST** `/api/v3/dsf/tickets/address-change`: * Response `429` now references endpoint-specific rate limit response (15 requests per minute) * Changes for **GET** `/api/v3/dsf/tickets/requested-data` (previously `/support/dsf/tickets/requested-data`): * Path corrected to `/api/v3/dsf/tickets/requested-data` * `data_type` enum values reduced to: `claim_letter`, `sales_invoice`, `sales_data`, `purchase_invoice`, `description_of_contents` * Response `429` added * Changes for **POST** `/api/v3/dsf/tickets/requested-data`: * Endpoint summary updated to "Create a requested data response" * Accepted `data_type` values for file attachments reduced to: `sales_invoice`, `purchase_invoice`, `claim_letter` * Accepted `data_type` values for textual input reduced to: `description_of_contents` * Field `selling_price` description updated: value must now be tax-included * Response `429` added ## Added endpoints: * **GET** `/brands` * **GET** `/brands/{id}` ## Changed endpoints: * Changes for **POST** `/returns`: * Documentation updated: label retrieval now references [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint instead of the v2 Labels API * Changes for **GET** `/returns`: * Field `shipping_option` added to `Return` response object * `label_url` example URLs updated from v2 Labels API (`/api/v2/labels/...`) to v3 Parcel Documents API (`/api/v3/parcels/{id}/documents/label`) * `label.label_printer` example URL updated to v3 Parcel Documents API * `label.normal_printer` example URLs updated to v3 Parcel Documents API; description updated to clarify the array always contains 4 identical URLs for backward compatibility * Changes for **GET** `/returns` and **GET** `/returns/{id}` (Return schema): * Field `shipping_option` added (object with nullable `code` string referencing the shipping option code) * `label_url` example updated to v3 Parcel Documents API URL format * `label.label_printer` example updated to v3 Parcel Documents API URL format * `label.normal_printer` description and examples updated to v3 Parcel Documents API URL format * `shipping_option` added to required fields ## Added endpoints: * **GET** `/shipments/{id}/return-portal-url` ## Changed endpoints: * Changes for **GET** `/support/dsf/tickets/requested-data`: * Added `page` query parameter (integer, default: 1) * Added `size` query parameter (integer, default: 50, maximum: 100) * Response `200` schema changed: * Field `data` removed from required properties and replaced with `items` * Field `total` added (integer, total number of items across all pages) * Field `page` added (integer, current page number) * Field `pages` added (integer, total number of pages) * Field `size` added (integer, number of items per page) * Field `items` added (array, replaces `data` array) * Field `description` removed from individual item objects * Changes for **POST** `/support/dsf/tickets/requested-data`: * Response `400` now references `ProvideRequestedDataBadRequest` instead of `BadRequestResponse`, adding more specific error examples: validation errors, action not allowed, and sales data required ## Changed endpoints: * Changes for **POST** `IntegrationConnected` webhook: * Operation ID updated from `sc-public-v2-webhooks-integration_connected` to `sc-public-v3-webhooks-integration_connected` * Changes for **POST** `IntegrationDeleted` webhook: * Operation ID updated from `sc-public-v2-webhooks-integration_deleted` to `sc-public-v3-webhooks-integration_deleted` * Changes for **POST** `IntegrationModified` webhook: * Operation ID updated from `sc-public-v2-webhooks-integration_modified` to `sc-public-v3-webhooks-integration_modified` * Changes for **POST** `ParcelStatusChanged` webhook: * Operation ID updated from `sc-public-v2-webhooks-parcel_status_changed` to `sc-public-v3-webhooks-parcel_status_changed` * Changes for **POST** `ReturnCreated` webhook: * Operation ID updated from `sc-public-v2-webhooks-return_created` to `sc-public-v3-webhooks-return_created` * Documentation link corrected from `/api/v3x/webhooks/return-created` to `/api/v3/webhooks/return-created` ## Changed endpoints: * Changes for **POST** `IntegrationConnected` webhook: * Operation ID updated from `sc-public-v2-webhooks-integration_connected` to `sc-public-v3-webhooks-integration_connected` * Changes for **POST** `IntegrationDeleted` webhook: * Operation ID updated from `sc-public-v2-webhooks-integration_deleted` to `sc-public-v3-webhooks-integration_deleted` * Changes for **POST** `IntegrationModified` webhook: * Operation ID updated from `sc-public-v2-webhooks-integration_modified` to `sc-public-v3-webhooks-integration_modified` * Changes for **POST** `ParcelStatusChanged` webhook: * Operation ID updated from `sc-public-v2-webhooks-parcel_status_changed` to `sc-public-v3-webhooks-parcel_status_changed` * Changes for **POST** `ReturnCreated` webhook: * Operation ID updated from `sc-public-v2-webhooks-return_created` to `sc-public-v3-webhooks-return_created` * Documentation link corrected from `/api/v3x/webhooks/return-created` to `/api/v3/webhooks/return-created` ## Changed endpoints: * Changes for **POST** `/pickups` and related FedEx pickup endpoints: * Schema `fedex-origin-detail`: Field `company_close_time` example updated to include UTC timezone suffix (`17:00:00Z`) ## Changed endpoints: * Changes for **POST** `/store-locations`: * Added `x-mint` documentation metadata including href, Beta tag, and descriptive content * Changes for **GET** `/store-locations`: * Added `x-mint` documentation metadata including href and Beta tag * Changes for **GET** `/store-locations/{id}`: * Added `x-mint` documentation metadata including href, Beta tag, and usage notes * Changes for **PATCH** `/store-locations/{id}`: * Added `x-mint` documentation metadata including href, Beta tag, and partial update behavior note * Changes for **DELETE** `/store-locations/{id}`: * Added `x-mint` documentation metadata including href, Beta tag, and soft-delete behavior notes ## Changed endpoints: * Changes to `IntegrationWebhookBase` schema: * Field `integration.failing_since` example updated to include UTC timezone suffix (`2019-02-03T06:48:07Z`) * Field `integration.last_fetch` example updated to include UTC timezone suffix (`2019-02-03T06:48:07Z`) * Field `integration.last_updated_at` example updated to include UTC timezone suffix (`2019-02-03T06:48:07Z`) ## Changed endpoints: * Changes for **POST** `/api/v3/orders/{order_id}/shipments/label`: * Request body schema changed: * Field `shipping_option_code` description updated to clarify it is mandatory when `ship_with.type` is set to `shipping_option_code` * Changes for **POST** `/api/v3/shipments/{shipment_id}/label`: * Request body schema changed: * Field `shipping_option_code` description updated to clarify it is mandatory when `ship_with.type` is set to `shipping_option_code` ## Added endpoints: * **POST** `/event-subscriptions/connections` – Create a connection * **GET** `/event-subscriptions/connections` – List connections * **GET** `/event-subscriptions/connections/{id}` – Get a connection * **PATCH** `/event-subscriptions/connections/{id}` – Update a connection * **DELETE** `/event-subscriptions/connections/{id}` – Delete a connection * **GET** `/event-subscriptions/connections/type/{connection_type}` – List connections by type * **POST** `/event-subscriptions/connections/{id}/authorization` – Start OAuth2 authorization * **GET** `/event-subscriptions/connections/authorization/callback` – OAuth2 callback * **POST** `/event-subscriptions/subscriptions` – Create a subscription * **GET** `/event-subscriptions/subscriptions` – List subscriptions * **GET** `/event-subscriptions/subscriptions/{id}` – Get a subscription * **PATCH** `/event-subscriptions/subscriptions/{id}` – Update a subscription * **DELETE** `/event-subscriptions/subscriptions/{id}` – Delete a subscription * **GET** `/event-subscriptions/subscriptions/event/{event_type}` – List subscriptions by event type * **POST** `/event-subscriptions/broadcast/test/{subscription_id}` – Test event delivery ## Changed endpoints: * Changes for **POST** `/address-washer`: * Request body `application/json` changed: * Field `validation_methods` added to `address-washer-request` schema ## Changed endpoints: * Changes for **POST** `/parcels/tracking`: * Beta notice updated with more detailed information about endpoint stability and guidance for integration reviews ## Changed endpoints: * Changes for **GET** `/shipping-options`: * Response schema `shipping-quote` changed: * Field `estimated_surcharges` added to quote object. This field contains an array of estimated surcharges that may be applied to the quote, presented separately from the base price as they are only estimates. ## Changed endpoints: * Changes for **GET** `/shipping-options`: * Response schema `shipping-quote` changed: * Field `estimated_surcharges` added (array of surcharge objects with `price`, `label`, and `type` properties) ## Changed endpoints: * Changes for **GET** `/integrations/logs`: * Parameter `cursor` example changed from `'2023-03-01T02:02:00'` to `'2023-03-01T02:02:00+01:00'` * Changes for **GET** `/integrations/{id}/logs`: * Parameter `cursor` example changed from `'2023-03-01T02:02:00'` to `'2023-03-01T02:02:00+01:00'` ## Changed schemas: * `base-pickup-request`: * Field `quantity` added (type: integer, minimum: 1) * Field `total_weight` added (type: str-weight) * Required fields changed from `time_slot`, `parcel_quantity` to `time_slots`, `quantity` * `dhl-parcel-gb-pickup-request`: * Required field `parcel_quantity` changed to `quantity` * `fedex-request`: * Required fields changed from `time_slot`, `parcel_quantity` to `time_slots`, `quantity` * `ups-pickup-request`: * Required field `time_slot` changed to `time_slots` * `IntegrationWebhookBase`: * Field `action` added (type: string) ## Changed endpoints: * Changes for **POST** `/oauth2/token`: * Request body schema changed: * Field `grant_type` moved from property-level to object-level required fields ## Changed endpoints: * Changes for **POST** `/shipments`: * Request schema changed: * Schema `service-point` renamed to `service-point-request` * Field `to_service_point` now uses `anyOf` instead of `oneOf` * Description updated to clarify `carrier_service_point_id` takes priority when both `id` and `carrier_service_point_id` are provided * Changes for **POST** `/shipping-options/quote`: * Request schema `shipping-option-filter` changed: * Field `to_service_point_id` deprecated: "Use `to_service_point` instead" * Field `to_service_point` added with reference to `service-point-request` schema * Request examples added: * New example `ServicePointDelivery` showing service point delivery with Sendcloud ID * New example `ServicePointDeliveryWithCarrierId` showing service point delivery with carrier ID ## Added schemas: * Schema `service-point-request` added to Shipping Options API: * Supports identification by either `id` (Sendcloud ID) or `carrier_service_point_id` (carrier's ID) * Description clarifies priority when both fields are provided ## Changed endpoints: * Changes for **POST** `/api/v3/dsf/forms/{form_type}/support-request` (CreateAddressChangeTransactional schema): * Request body required field changed: * Field `is_parcel_returned` removed * Field `new_address` added ## Changed endpoints: * Changes for **POST** `/parcels/tracking`: * Endpoint marked as Beta * Documentation updated with detailed description and beta notice * Field `tracking_number` added to request schema * Field `carrier` added to request schema * Field `sender` address fields added to request schema * Field `recipient` address fields added to request schema * Optional fields `parcel_items`, `measurements`, and `insurance` added to request schema ## Added endpoints: * **GET** `/integrations/logs` - Retrieve all integration exception logs * **GET** `/integrations/{id}/logs` - Retrieve exception logs for a specific integration * **POST** `/integrations/{id}/logs` - Create integration exception logs ## Changed endpoints: * Changes for **DELETE** `/integrations/{id}`: * Response `404` / `application/json` changed: * Error response field `status` changed from string to integer type * Error response field `title` changed from "Not found" to "Not Found" * Changes for **PATCH** `/integrations/{id}`: * Response `404` / `application/json` changed: * Error response field `status` changed from string to integer type * Error response field `title` changed from "Not found" to "Not Found" * Changes for **GET** `/integrations/{id}`: * Response `404` / `application/json` changed: * Error response field `status` changed from string to integer type * Error response field `title` changed from "Not found" to "Not Found" ## Added schemas: * `integration-log` - Integration exception log object with fields: `id`, `integration_id`, `base_url`, `full_url`, `method`, `response_code`, `response`, `request`, `created_at`, `exception_type`, `exception`, `protected`, `additional_data` * `integration-log-create` - Request body schema for creating integration exception logs ## Changed endpoints: * Changes for **GET** `/contracts`: * Description updated to include cursor-based pagination information * Changes for **GET** `/pickups`: * Description updated to include cursor-based pagination information * Changes for **GET** `/addresses/sender-addresses`: * Description updated to include cursor-based pagination information * Changes for **GET** `/shipments`: * Description updated to include cursor-based pagination information * Response `200` / `application/json` header `Link`: * Description updated to standardize pagination link format (RFC8288) * Example added showing cursor-based pagination format ## Changed endpoints: * Changes for **GET** `/api/v3/shipments`: * Query parameter `ids` description updated: now clarifies this filters by *parcels IDs* * Query parameter `shipment_uuids` added: filter results using a comma-separated list of *shipments IDs* (max 100 IDs) ## Changed endpoints: * Changes for **POST** `/api/v3/orders`: * Request body schema changed: * Field `service_point_details` now supports two identification methods: * Sendcloud `id` (existing) * Carrier's native `carrier_service_point_id` (new) * Field `carrier_service_point_id` added to service point schema * Response `201` / `application/json` changed: * Field `service_point_details` now supports two identification methods: * Sendcloud `id` (existing) * Carrier's native `carrier_service_point_id` (new) * Field `carrier_service_point_id` added to service point schema * Changes for **PATCH** `/api/v3/orders/{id}`: * Request body schema changed: * Field `service_point_details` now supports two identification methods: * Sendcloud `id` (existing) * Carrier's native `carrier_service_point_id` (new) * Field `carrier_service_point_id` added to service point schema * Response `200` / `application/json` changed: * Field `service_point_details` now supports two identification methods: * Sendcloud `id` (existing) * Carrier's native `carrier_service_point_id` (new) * Field `carrier_service_point_id` added to service point schema ## Changed endpoints: * Changes for **POST** `/dsf/tickets/damage`: * Query parameter `is_portal_claim` added * Changes for **POST** `/dsf/tickets/delay`: * Query parameter `is_portal_claim` added * Changes for **POST** `/dsf/tickets/late-delivery`: * Query parameter `is_portal_claim` added * Changes for **POST** `/dsf/tickets/lost`: * Query parameter `is_portal_claim` added * Changes for **POST** `/dsf/tickets/delivered-but-not-received`: * Query parameter `is_portal_claim` added * Changes for **POST** `/dsf/tickets/unjust-return`: * Query parameter `is_portal_claim` added * Changes for **POST** `/dsf/tickets/address-change`: * Query parameter `is_portal_claim` added ## Schema changes: * `CreateDamagedOwnContract`: Field `carrier_contract_id` added * `CreateDelayedOwnContract`: Field `carrier_contract_id` added * `CreateLateDeliveryOwnContract`: Field `carrier_contract_id` added * `CreateLostOwnContract`: Field `carrier_contract_id` added * `CreateDeliveredButNotReceivedOwnContract`: Field `carrier_contract_id` added * `CreateUnjustReturnOwnContract`: Field `carrier_contract_id` added * `CreateAddressChangeOwnContract`: Field `carrier_contract_id` added * New schema `CarrierContractIdField` added ## Changed endpoints: * Changes for **GET** `/checkout/configurations/{configuration_id}/delivery-options`: * Documentation metadata updated with Beta tag ## Changed endpoints: * Changes for **POST** `/carriers/dp/finalize-order`: * Description updated: Removed "Required Permission: manage\_shipping" note ## Changed endpoints: * Changes for **POST** `/carriers/dp/finalize-order`: * Description updated with detailed workflow and behavior documentation * Response `400` description changed to clarify `copy_count` parameter validation requirements * Response `200` example `success_without_awb` summary changed to "No eligible parcels found" * Field `awb_document_url` description updated to clarify behavior when no eligible parcels are found and that the AWB document is shared across all parcels in the box * Field `next_order_id` description updated to clarify behavior when parcels are successfully finalized versus when no eligible parcels are found ## Added endpoints: * **POST** `/carriers/dp/finalize-order` ## Added endpoints: * **POST** `/dsf/tickets/late-delivery` ## Deprecated endpoints: * **POST** `/dsf/tickets/delay` ## Changed endpoints: * Changes for **POST** `/dsf/tickets/delay`: * Endpoint marked as deprecated with migration guidance to use late delivery endpoint instead * Changes for **POST** `/dsf/tickets/late-delivery`: * New schema `CreateLateDeliveryOwnContract` added with properties: * Field `tracking_number` (required) * Field `additional_remarks` (optional) ## Added endpoints: * **POST** `/addresses/validate` ## Added schemas: * `raw-address` - Raw address object with address line, house number, postal code, city, state/province code, and country code * `address-washer-request` - Request object for address validation containing address and carrier code * `address-washer-response` - Response object for address validation containing results with address, recommendation status, and validation analysis ## Changed endpoints: * Changes for **POST** `/api/v3/contracts`: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **GET** `/api/v3/contracts`: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **GET** `/api/v3/checkout/configurations/{configuration_id}/delivery-options`: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **GET** `/api/v3/orders`: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **POST** `/api/v3/orders`: * Field `unit_price` description updated: documentation reference changed from "Sendcloud platform" to "Sendcloud Panel" * Field `total_price` description updated: documentation reference changed from "Sendcloud platform" to "Sendcloud panel" * Changes for **GET** `/parcels/statuses`: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **GET** `/api/v3/parcel-tracking/{tracking_number}`: * Field `brand_id` description updated: documentation reference changed from "Sendcloud platform" to "Sendcloud panel" * Changes for **POST** `/api/v3/shipments`: * Field `sender_address_id` description updated: documentation reference changed from "Sendcloud platform" to "Sendcloud panel" * Field `brand_id` description updated: documentation reference changed from "Sendcloud platform" to "Sendcloud panel" * Field `to_service_point` moved from `shipment-common-with-optional-fields` to `shipment-request` * Field `validation_methods` removed from `shipment-common-with-optional-fields` * Schema `service-point` changed: now supports both Sendcloud ID and carrier service point ID via `oneOf` * Schema `service-point-response` added to responses with both `id` and `carrier_service_point_id` fields * Changes for **POST** `/api/v3/shipments/async`: * Field `to_service_point` moved and schema updated to support both Sendcloud ID and carrier service point ID * Field `validation_methods` removed * Documentation updated regarding shipping rules: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **GET** `/api/v3/shipments/{id}/cancel`: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" * Changes for **Webhooks**: * Documentation updated: "Sendcloud platform" changed to "Sendcloud panel" ## Changed endpoints: * Changes for **POST** `/shipments/announce-with-shipping-rules`: * Description updated: Removed beta status notice and breaking changes warning * Changes for **POST** `/shipments/create-with-shipping-rules`: * Description updated: Removed beta status notice and breaking changes warning ## Changed endpoints: * Changes for **POST** `/shipments/announce_with_rules`: * Documentation updated: * Removed "Set customs export reason" from available shipping rules actions * Removed "Set customs export type" from available shipping rules actions * Changes for **POST** `/shipments/create_with_rules`: * Documentation updated: * Removed "Set customs export reason" from available shipping rules actions * Removed "Set customs export type" from available shipping rules actions ## Changed endpoints: * Changes for **POST** `/store-locations`: * Documentation metadata updated * Changes for **GET** `/store-locations`: * Documentation metadata updated * Changes for **GET** `/store-locations/{id}`: * Documentation metadata updated * Changes for **PATCH** `/store-locations/{id}`: * Documentation metadata updated * Changes for **DELETE** `/store-locations/{id}`: * Documentation metadata updated ## Changed endpoints: * Changes for **POST** `/orders`: * Request body schema updated: * Field `id` added to order creation requests (optional, must be sent as string) * Response `400` / `application/json` changed: * Error response documentation expanded with detailed error examples and JSON Pointer notation explanation * New error examples added: `MissingRequiredField`, `InvalidFieldValue`, `DuplicateOrderProcessing`, `BatchSizeLimitExceeded`, `MultipleValidationErrors`, `IntegrationNotFound`, `ImmutableFieldChange`, `InvalidIdType` * Endpoint documentation expanded with comprehensive upsert behavior, batch processing details, limitations, and best practices * Changes for **POST** `/shipments`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Changes for **GET** `/shipments`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Changes for **PATCH** `/shipments/{id}`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Changes for **GET** `/shipments/{id}`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Changes for **POST** `/shipments/announce-with-shipping-rules`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Documentation updated with note on carrier-specific parcel limits * Changes for **POST** `/shipments/create-with-shipping-rules`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Changes for **POST** `/parcels`: * Field `dds_reference` added to parcel items (optional) * Field `taric_doc_code` added to parcel items (optional) * Field `dangerous_goods` added to parcel items (optional) * Field `tracking_identifier` added to tracking numbers (optional) * `ship_with` schema restructured: Now supports discriminated union with two types: `shipping_option_code` and `contract` * Field `user_shipping_method_name` added to ship\_with properties (optional) * Field `user_shipping_method_id` added to ship\_with properties (optional) * Field `contract_id` made required for `shipping_option_code` type * Changes for **POST** `/ship-orders`: * Field renamed: `order_items` changed to `parcel_items` in multicollo parcel definitions * Changes for **POST** `/returns`: * Field `return_fee` added to return response (optional) * Changes for **GET** `/returns`: * Field `return_fee` added to return response (optional) * Changes for **GET** `/returns/{id}`: * Field `return_fee` added to return response (optional) ## Removed endpoints: * **PUT** `/api/v3/orders/{id}` ## Added endpoints: * **GET** `/api/v3/dsf/forms/categories` * **GET** `/api/v3/dsf/forms/{form_type}/fields` * **POST** `/api/v3/dsf/forms/{form_type}/support-request` * **POST** `/api/v3/support/dsf/forms/fileupload` ## Changed endpoints: * Changes for **POST** `/api/v3/shop-order-statuses/mapping/`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **GET** `/api/v3/shop-order-statuses/mapping/`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **POST** `/api/v3/shop-order-statuses`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **GET** `/api/v3/shop-order-statuses`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **GET** `/api/v3/integrations/{id}`: * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **PATCH** `/api/v3/integrations/{id}`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **DELETE** `/api/v3/integrations/{id}`: * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **PATCH** `/api/v3/orders/{id}`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **DELETE** `/api/v3/orders/{id}`: * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **PUT** `/api/v3/orders/{id}`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **GET** `/api/v3/orders/{id}`: * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **GET** `/api/v3/orders`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas * Changes for **POST** `/api/v3/orders`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas ## Added endpoints: * **DELETE** `/api/v3/integrations/{id}` * **PATCH** `/api/v3/integrations/{id}` * **GET** `/api/v3/integrations/{id}` * **GET** `/api/v3/integrations` * **GET** `/api/v3/shop-order-statuses` * **POST** `/api/v3/shop-order-statuses` * **GET** `/api/v3/shop-order-statuses/mapping/` * **POST** `/api/v3/shop-order-statuses/mapping/` ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `data` added * Field `id` removed * Field `order_id` removed * Field `order_number` removed * Changes for **PUT** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `data` added * Field `id` removed * Field `order_id` removed * Field `order_number` removed * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `data` added * Field `order_id` removed * Field `order_number` removed * Field `order_details` removed * Field `payment_details` removed * Field `id` removed * Field `created_at` removed * Field `modified_at` removed * Field `customs_details` removed * Field `customer_details` removed * Field `billing_address` removed * Field `shipping_address` removed * Field `shipping_details` removed * Field `service_point_details` removed ## Changed endpoints: * Changes for **POST** `/api/v3/returns/validate`: * Parameters changed: * Request body param `customs_information` added * Changes for **GET** `/api/v3/returns/{id}`: * Response `200` / `application/json` changed: * Field `customs_information` added * Changes for **GET** `/api/v3/returns`: * Response `200` / `application/json` changed: * Field `data.items.customs_information` added * Changes for **POST** `/api/v3/returns`: * Parameters changed: * Request body param `customs_information` added ## Changed endpoints: * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `shipping_details.is_local_pickup` added * Request body param `payment_details.is_cash_on_delivery` added * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `shipping_details.is_local_pickup` added * Field `payment_details.is_cash_on_delivery` added * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.shipping_details.is_local_pickup` added * Field `items.payment_details.is_cash_on_delivery` added * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.shipping_details.is_local_pickup` added * Request body param `items.payment_details.is_cash_on_delivery` added ## Added endpoints: * **POST** `/oauth2/token` ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `payment_details.invoice_date` added * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `payment_details.invoice_date` added * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `payment_details.invoice_date` added * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.payment_details.invoice_date` added * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.payment_details.invoice_date` added ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `tax_numbers` added * Request body param `payment_details.discount_granted` added * Request body param `payment_details.insurance_costs` added * Request body param `payment_details.freight_costs` added * Request body param `payment_details.other_costs` added * Request body param `order_details.order_items.items.mid_code` added * Request body param `order_details.order_items.items.material_content` added * Request body param `order_details.order_items.items.intended_use` added ## Changed endpoints: * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `payment_details.discount_granted` added * Request body param `payment_details.insurance_costs` added * Request body param `payment_details.freight_costs` added * Request body param `payment_details.other_costs` added * Request body param `order_details.order_items.items.mid_code` added * Request body param `order_details.order_items.items.material_content` added * Request body param `order_details.order_items.items.intended_use` added * Request body param `customs_details` now can be null * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `payment_details.discount_granted` added * Field `payment_details.insurance_costs` added * Field `payment_details.freight_costs` added * Field `payment_details.other_costs` added * Field `order_details.order_items.items.mid_code` added * Field `order_details.order_items.items.material_content` added * Field `order_details.order_items.items.intended_use` added * Field `customs_details` now can be null * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.payment_details.discount_granted` added * Field `items.payment_details.insurance_costs` added * Field `items.payment_details.freight_costs` added * Field `items.payment_details.other_costs` added * Field `items.order_details.order_items.items.mid_code` added * Field `items.order_details.order_items.items.material_content` added * Field `items.order_details.order_items.items.intended_use` added * Field `items.customs_details` now can be null * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.payment_details.discount_granted` added * Request body param `items.payment_details.insurance_costs` added * Request body param `items.payment_details.freight_costs` added * Request body param `items.payment_details.other_costs` added * Request body param `items.order_details.order_items.items.mid_code` added * Request body param `items.order_details.order_items.items.material_content` added * Request body param `items.order_details.order_items.items.intended_use` added * Request body param `items.customs_details` now can be null ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `401` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Changes for **DELETE** `/api/v3/orders/{id}`: * Response `401` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Changes for **PUT** `/api/v3/orders/{id}`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `401` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Changes for **GET** `/api/v3/orders/{id}`: * Response `401` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Changes for **GET** `/api/v3/orders`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `401` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `404` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Changes for **POST** `/api/v3/orders`: * Response `400` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` * Response `401` / `application/json` changed: * Polymorphism object: * `errors.allOf` changed supported schemas, `['Error']` added * Field `errors` changed its type to `['array', 'object']` ## Changed endpoints: * Changes for **GET** `/api/v3/returns/{id}`: * Response `200` / `application/json` changed: * Field `status_history.items.carrier_update_timestamp` has new format: `date-time` * Changes for **GET** `/api/v3/returns`: * Response `200` / `application/json` changed: * Field `data.items.status_history.items.carrier_update_timestamp` has new format: `date-time` ## Changed endpoints: * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `shipping_details.delivery_indicator` added * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `shipping_details.delivery_indicator` added * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.shipping_details.delivery_indicator` added * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.shipping_details.delivery_indicator` added ## Added endpoints: * **POST** `/api/v3/returns/validate` * **GET** `/api/v3/returns/{id}` * **POST** `/api/v3/returns` * **GET** `/api/v3/returns` ## Changed endpoints: * Changes for **GET** `/api/v3/orders`: * Parameters changed: * Query param `sort` added ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Response `400` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `401` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `404` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Changes for **DELETE** `/api/v3/orders/{id}`: * Response `401` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `404` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Changes for **PUT** `/api/v3/orders/{id}`: * Response `400` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `401` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `404` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Changes for **GET** `/api/v3/orders/{id}`: * Response `401` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `404` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Changes for **GET** `/api/v3/orders`: * Response `400` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `401` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `404` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Changes for **POST** `/api/v3/orders`: * Response `400` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed * Response `401` / `application/json` changed: * Field `errors.status` removed * Field `errors.code` removed * Field `errors.detail` removed ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `shipping_address.po_box` now can be null * Request body param `shipping_address.po_box` is not nullable anymore * Request body param `billing_address.po_box` now can be null * Request body param `billing_address.po_box` is not nullable anymore * Request body param `order_details.order_items.items.delivery_dates` now can be null * Request body param `order_details.order_items.items.delivery_dates` is not nullable anymore * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `shipping_address.oneOf.0.po_box` now can be null * Request body param `shipping_address.oneOf.0.po_box` is not nullable anymore * Request body param `billing_address.oneOf.0.po_box` now can be null * Request body param `billing_address.oneOf.0.po_box` is not nullable anymore * Request body param `order_details.order_items.items.delivery_dates` now can be null * Request body param `order_details.order_items.items.delivery_dates` is not nullable anymore * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `shipping_address.oneOf.0.po_box` now can be null * Field `shipping_address.oneOf.0.po_box` is not nullable anymore * Field `billing_address.oneOf.0.po_box` now can be null * Field `billing_address.oneOf.0.po_box` is not nullable anymore * Field `order_details.order_items.items.delivery_dates` now can be null * Field `order_details.order_items.items.delivery_dates` is not nullable anymore * Changes for **GET** `/api/v3/orders`: * Parameters changed: * Query param `order_id` added * Response `200` / `application/json` changed: * Field `items.shipping_address.oneOf.0.po_box` now can be null * Field `items.shipping_address.oneOf.0.po_box` is not nullable anymore * Field `items.billing_address.oneOf.0.po_box` now can be null * Field `items.billing_address.oneOf.0.po_box` is not nullable anymore * Field `items.order_details.order_items.items.delivery_dates` now can be null * Field `items.order_details.order_items.items.delivery_dates` is not nullable anymore * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.shipping_address.oneOf.0.po_box` now can be null * Request body param `items.shipping_address.oneOf.0.po_box` is not nullable anymore * Request body param `items.billing_address.oneOf.0.po_box` now can be null * Request body param `items.billing_address.oneOf.0.po_box` is not nullable anymore * Request body param `items.order_details.order_items.items.delivery_dates` now can be null * Request body param `items.order_details.order_items.items.delivery_dates` is not nullable anymore ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Parameters changed: * Polymorphism object: * `shipping_address.oneOf` changed supported schemas, `['Address Object']` removed * `billing_address.oneOf` changed supported schemas, `['Address Object']` removed * Request body param `shipping_address` changed its type to `object` * Request body param `billing_address` changed its type to `object` * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Polymorphism object: * `payment_details.estimated_tax_price.oneOf` changed supported schemas, `['Price Object']` added * `payment_details.estimated_shipping_price.oneOf` changed supported schemas, `['Price Object']` added * `payment_details.subtotal_price.oneOf` changed supported schemas, `['Price Object']` added * `payment_details.total_price.oneOf` changed supported schemas, `['Price Object']` added * Request body param `order_details.status.code` has new minimal length restriction: `1` * Request body param `order_id` has new minimal length restriction: `1` * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Polymorphism object: * `payment_details.estimated_tax_price.oneOf` changed supported schemas, `['Price Object']` added * `payment_details.estimated_shipping_price.oneOf` changed supported schemas, `['Price Object']` added * `payment_details.subtotal_price.oneOf` changed supported schemas, `['Price Object']` added * `payment_details.total_price.oneOf` changed supported schemas, `['Price Object']` added * Field `order_details.status.code` has new minimal length restriction: `1` * Field `order_id` has new minimal length restriction: `1` * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Polymorphism object: * `items.payment_details.estimated_tax_price.oneOf` changed supported schemas, `['Price Object']` added * `items.payment_details.estimated_shipping_price.oneOf` changed supported schemas, `['Price Object']` added * `items.payment_details.subtotal_price.oneOf` changed supported schemas, `['Price Object']` added * `items.payment_details.total_price.oneOf` changed supported schemas, `['Price Object']` added * Field `items.order_details.status.code` has new minimal length restriction: `1` * Field `items.order_id` has new minimal length restriction: `1` * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Polymorphism object: * `items.payment_details.estimated_tax_price.oneOf` changed supported schemas, `['Price Object']` added * `items.payment_details.estimated_shipping_price.oneOf` changed supported schemas, `['Price Object']` added * `items.payment_details.subtotal_price.oneOf` changed supported schemas, `['Price Object']` added * `items.payment_details.total_price.oneOf` changed supported schemas, `['Price Object']` added * Request body param `items.order_details.status.code` has new minimal length restriction: `1` * Request body param `items.order_id` has new minimal length restriction: `1` ## Changed endpoints: * Changes for **GET** `/api/v3/orders`: * Parameters changed: * Query param `order_number` added * Query param `status` added * Query param `order_created_at` added * Query param `order_created_at_min` added * Query param `order_created_at_max` added * Query param `order_updated_at` added * Query param `order_updated_at_min` added * Query param `order_updated_at_max` added ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `order_details.order_items.items.delivery_dates` added * Changes for **PUT** `/api/v3/orders/{id}`: * Parameters changed: * Request body param `order_details.order_items.items.delivery_dates` added * Changes for **GET** `/api/v3/orders/{id}`: * Response `200` / `application/json` changed: * Field `order_details.order_items.items.delivery_dates` added * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.order_details.order_items.items.delivery_dates` added * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.order_details.order_items.items.delivery_dates` added ## Added endpoints: * **GET** `/api/v3/orders/{id}` * **PUT** `/api/v3/orders/{id}` * **DELETE** `/api/v3/orders/{id}` * **PATCH** `/api/v3/orders/{id}` ## Removed endpoints: * **GET** `/api/v3/orders/{id}/` * **PUT** `/api/v3/orders/{id}/` * **DELETE** `/api/v3/orders/{id}/` * **PATCH** `/api/v3/orders/{id}/` ## Changed endpoints: * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.shipping_details.shipping_method` removed * Field `items.order_details.shipping_functionalities` removed * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.shipping_details.shipping_method` removed * Request body param `items.order_details.shipping_functionalities` removed ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}/`: * Parameters changed: * Request body param `id` is read only now * Changes for **PUT** `/api/v3/orders/{id}/`: * Parameters changed: * Request body param `id` is read only now * Changes for **GET** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Field `id` is read only now * Changes for **GET** `/api/v3/orders`: * Parameters changed: * Path param `Link` removed * Response `200` / `application/json` changed: * Field `items.id` is read only now * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.id` is read only now ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}/`: * Parameters changed: * Polymorphism object: * `shipping_address.oneOf` changed supported schemas, `['Address Object']` added * `billing_address.oneOf` changed supported schemas, `['Address Object']` added * Changes for **PUT** `/api/v3/orders/{id}/`: * Parameters changed: * Polymorphism object: * `shipping_address.oneOf` changed supported schemas, `['Address Object']` added * `billing_address.oneOf` changed supported schemas, `['Address Object']` added * Changes for **GET** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Polymorphism object: * `shipping_address.oneOf` changed supported schemas, `['Address Object']` added * `billing_address.oneOf` changed supported schemas, `['Address Object']` added * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Polymorphism object: * `items.shipping_address.oneOf` changed supported schemas, `['Address Object']` added * `items.billing_address.oneOf` changed supported schemas, `['Address Object']` added * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Polymorphism object: * `items.shipping_address.oneOf` changed supported schemas, `['Address Object']` added * `items.billing_address.oneOf` changed supported schemas, `['Address Object']` added ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}/`: * Parameters changed: * Request body param `order_details.order_created_at` added * Request body param `order_details.order_updated_at` added * Request body param `order_details.order_date` removed * Changes for **PUT** `/api/v3/orders/{id}/`: * Parameters changed: * Request body param `order_details.order_created_at` added * Request body param `order_details.order_updated_at` added * Request body param `order_details.order_date` removed * Changes for **GET** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Field `order_details.order_created_at` added * Field `order_details.order_updated_at` added * Field `order_details.order_date` removed * Changes for **GET** `/api/v3/orders`: * Response `200` / `application/json` changed: * Field `items.order_details.order_created_at` added * Field `items.order_details.order_updated_at` added * Field `items.order_details.order_date` removed * Changes for **POST** `/api/v3/orders`: * Parameters changed: * Request body param `items.order_details.order_created_at` added * Request body param `items.order_details.order_updated_at` added * Request body param `items.order_details.order_date` removed ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Field `created_at` removed * Field `modified_at` removed * Changes for **PUT** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Field `created_at` removed * Field `modified_at` removed ## Added endpoints: * **POST** `/api/v3/orders` * **GET** `/api/v3/orders` ## Removed endpoints: * **POST** `/api/v3/orders/` * **GET** `/api/v3/orders/` * **POST** `/api/v3/orders/{id}/split/` ## Changed endpoints: * Changes for **PATCH** `/api/v3/orders/{id}/`: * Parameters changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `400` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Response `401` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Field `errors` changed its type to `object` * Response `404` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Changes for **DELETE** `/api/v3/orders/{id}/`: * Response `401` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Field `errors` changed its type to `object` * Response `404` / `text/html; charset=utf-8` changed: * Field `root` removed * Response `404` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Changes for **PUT** `/api/v3/orders/{id}/`: * Parameters changed: * Polymorphism object: * `root.allOf` changed supported schemas * Request body param `order_id` added * Request body param `order_number` added * Request body param `order_details` added * Request body param `payment_details` added * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `400` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Response `401` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Field `errors` changed its type to `object` * Response `404` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Changes for **GET** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Field `order_id` added * Field `order_number` added * Field `order_details` added * Field `payment_details` added * Response `401` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added * Field `errors` changed its type to `object` * Response `404` / `text/html; charset=utf-8` changed: * Field `root` removed * Response `404` / `application/json` changed: * Field `errors.status` added * Field `errors.code` added * Field `errors.detail` added ## Changed endpoints: * Changes for **POST** `/api/v3/orders/{id}/split/`: * Parameters changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `201` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Changes for **PATCH** `/api/v3/orders/{id}/`: * Parameters changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Changes for **PUT** `/api/v3/orders/{id}/`: * Parameters changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Changes for **GET** `/api/v3/orders/{id}/`: * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Changes for **GET** `/api/v3/orders/`: * Response `200` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas * Changes for **POST** `/api/v3/orders/`: * Parameters changed: * Polymorphism object: * `root.allOf` changed supported schemas * Response `201` / `application/json` changed: * Polymorphism object: * `root.allOf` changed supported schemas # Retrieve a list of shipping options Source: https://sendcloud.dev/api/v3/compat/retrieve-a-list-of-shipping-options /.openapi/v3/compat/openapi.yaml post /compat/shipping-options Retrieve a list of shipping options based on the provided shipping method ids. This endpoint is intended to smooth the transition from shipping methods to shipping options. It accepts a list of shipping method IDs and returns their corresponding shipping option identifiers. Ordering of the shipping options is not guaranteed, and the response may contain null values for shipping methods that do not have a corresponding shipping option. Shipping methods that do not exist will not be returned in the response. This API is deprecated and intended for compatibility purposes only. It may be removed in the future, so it is recommended to transition to use the [Shipping options API](/api/v3/shipping-options) as soon as possible. # Create a contract for a carrier Source: https://sendcloud.dev/api/v3/contracts/create-a-contract-for-a-carrier /.openapi/v3/contracts/openapi.yaml post /contracts Create a contract for a supported carrier. This endpoint **creates** a contract for a carrier. Creating a carrier contract via the API is **not supported for 2FA carriers**, including UPS, Hermes, Amazon, Bol, and FedEx. To create a carrier contract for these carriers, please use the Sendcloud platform. After creating a contract, its initial state will be `"validating"`. This means the system is verifying the contract data with carriers, which typically takes only a few seconds, depending on the carriers. Once validation is complete, the contract's state will change to one of the following: * `"active"` or `"inactive"`: The contract has been successfully processed. * `"validation_failed"`: An error occurred during validation. Additional information about the failure will be provided. You can check the current state of the contract using the [Retrieve a contract](/api/v3/contracts/retrieve-a-contract) endpoint. # Delete a contract Source: https://sendcloud.dev/api/v3/contracts/delete-a-contract /.openapi/v3/contracts/openapi.yaml delete /contracts/{id} Delete a specific contract by including the `id` of the contract as a path parameter. Include the `id` of the contract as a path parameter to delete information for that specific contract. If you have multiple active contracts for the same carrier and you delete the default contract, we will automatically pick the first added contract as the new default. If you delete the last contract for a specific carrier, we will disable this carrier and its shipping options to prevent that you will accidentally use Sendcloud's transactional rates. # Contracts API overview Source: https://sendcloud.dev/api/v3/contracts/index Sendcloud supports the connection of your own direct shipping contract with your Sendcloud account for any [Sendcloud-supported shipping carrier](https://www.sendcloud.com/carriers/). Once you've successfully connected your contract, your shipping label prices will be invoiced directly via your chosen carrier/s, and the price you pay for labels in Sendcloud will appear as 0,00 EUR. ## How to enable your direct carrier contract * [Log in](https://account.sendcloud.com/login/) to your Sendcloud account * Find your shipping carrier on the [Carriers](https://app.sendcloud.com/v2/shipping/carriers/list) page and click **Add Contract**. * Fill in the required information and click **Add this contract** The type of information you need to enter differs from carrier to carrier. You can find out specifically what information you need to submit and how to obtain it by finding your carrier on our help center's [carriers page](https://support.sendcloud.com/hc/en-us/categories/360001511752-Carriers-) and reading its contract activation guide. # Retrieve a contract Source: https://sendcloud.dev/api/v3/contracts/retrieve-a-contract /.openapi/v3/contracts/openapi.yaml get /contracts/{id} Retrieve information about a specific contract by including the `id` of the contract as a path parameter. # Retrieve a list of contract schemas Source: https://sendcloud.dev/api/v3/contracts/retrieve-a-list-of-contract-schemas /.openapi/v3/contracts/openapi.yaml get /contracts/schemas Retrieve information about contract schemas (by carrier) to help with creating/updating contracts. # Retrieve a list of contracts Source: https://sendcloud.dev/api/v3/contracts/retrieve-a-list-of-contracts /.openapi/v3/contracts/openapi.yaml get /contracts Retrieve the list of contracts you have in your Sendcloud account. It will also return the `id` of each contract, which you can use to retrieve information about a specific contract. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. # Update a contract Source: https://sendcloud.dev/api/v3/contracts/update-a-contract /.openapi/v3/contracts/openapi.yaml patch /contracts/{id} Update or replace a contract by including the `id` of the contract as a path parameter. This endpoint will either **update** or **replace** a contract. Changes to unused contracts or the contract's state and description will be done in place and not cause a new contract to be created (`name`, `is_active`, `is_default`, `is_per_carrier_default`). **However, used contracts are immutable, if you change the contract\_data of a contract that has already been used for shipments, it will cause a new contract ID to be created. In this case, the old one will no longer be active for use.** After updating a contract with `contract_data`, we need to validate it again and its state will be `"validating"`. During the validation the contract is not active and cannot be used for creating shipments. The validation process is asynchronous and will happen in the background. Once validation is complete, the contract's state will change to one of the following: * `"active"` or `"inactive"`: The contract has been successfully processed. * `"validation_failed"`: An error occurred during validation. Additional information about the failure will be provided. # Create a duties and taxes calculation Source: https://sendcloud.dev/api/v3/duties-and-taxes/create-a-duties-and-taxes-calculation /.openapi/v3/duties-and-taxes/openapi.yaml post /shipping/duties-and-taxes Calculate import duties and taxes for an international shipment based on its origin, destination, items, and shipping cost. This endpoint is currently in beta and available to **enterprise customers** in a pilot program. Contact your Customer Success Manager to enable it for your account. While the core functionality is stable, some details or behavior may change as the API is finalized. ## What this endpoint does For a given shipment (from/to country, items with HS codes), this endpoint returns: * The customs **duty** payable on each item (a tariff charged on goods crossing a border) * The import **tax** (VAT/GST) payable on each item * The destination country's **de minimis** thresholds (below which duty/tax is waived) * A shipment-level **total** including items, duty, tax, and shipping cost ## Improving accuracy The more information you provide, the more accurate the calculation: * **`hs_code`** — the 6-digit Harmonized System code is the most important input. Without it, classification falls back to the description and accuracy drops. * **`description`** — should be a plain product description (e.g. "leather oxford shoes"), not a marketing title (e.g. "Premium Italian Handcrafted Genuine Leather Dress Shoe — Free Shipping"). Vague terms like "gift", "sample", or "parts" reduce accuracy. * **`origin_country`** — affects duty rates. Goods from countries with trade agreements may have lower rates. * **`shipping_cost`** — some destinations (e.g. US) include shipping in the dutiable value. * **`weight`** — required for some destinations (e.g. Switzerland) and improves accuracy on heavy shipments. ## Authentication Use [Sendcloud Basic Auth](/docs/getting-started/authentication) — your Public Key as username, Secret Key as password. # Generate a list of delivery options Source: https://sendcloud.dev/api/v3/dynamic-checkout/generate-a-list-of-delivery-options /.openapi/v3/dynamic-checkout/openapi.yaml post /checkout/delivery-options Generates a list of delivery options based on the provided cart or order details. To use this API, you first need to [create your own Dynamic Checkout configuration](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout) in the Sendcloud platform. Follow these steps to get started: 1. Log in to your Sendcloud account and navigate to the **Dynamic Checkout** tab. 2. Select your API integration from the **Shops** section to customize your delivery options. 3. When you're done, click **Publish** to connect your configuration to the selected API integration. This API allows your customers to choose their preferred delivery options during checkout. The delivery options returned by this endpoint are computed from the [delivery methods](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4) configured in the currently active Dynamic Checkout configuration. The endpoint also takes into account the cart or order details provided in the request body, such as parcel weight, total order value, destination country, and other parameters. You can display the returned delivery options to your customers on your checkout page, where they can select their preferred option for their order. ## How do delivery options correspond to configured delivery methods? This API returns one delivery option per carrier configured in Dynamic Checkout. If a delivery method is configured with multiple carriers, then multiple delivery options will be returned - one per carrier. In cases when delivery options correspond to the same delivery method, delivery options' ids will refer to the same delivery method id, leaving API users with a flexibility to perform grouping based on a delivery method id, if desired. ## Which Dynamic Checkout configuration is used? This endpoint uses the currently active Dynamic Checkout configuration for the authenticated API integration. Unlike previous Dynamic Checkout endpoints, you do not need to provide a `configuration_id` in the URL. Instead, the configuration is determined by the API integration used to authenticate the request. When you publish a Dynamic Checkout configuration in the Sendcloud platform, it becomes the active configuration for the selected API integration. An API integration can have only one published Dynamic Checkout configuration at a time. If the authenticated API integration does not have a published configuration, this endpoint returns a `400` response. ## How can I create a shipment out of the selected delivery option? The `checkout_identifier` field of the selected delivery option contains the shipping option code required to create a shipment. To create and announce the shipment, call the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint, setting `ship_with.type` to `"shipping_option_code"` and `ship_with.properties.shipping_option_code` to the value of the `checkout_identifier` field. # Dynamic Checkout API overview Source: https://sendcloud.dev/api/v3/dynamic-checkout/index Enhance your conversion rates and deliver an exceptional shipping experience with Sendcloud. [Dynamic Checkout](https://support.sendcloud.com/hc/en-us/articles/360057943512-Dynamic-Checkout) gives you the tools to optimize your checkout process and let customers choose when and how they want to receive their orders. With access to [over 160 supported carriers](https://sendcloud.com/carriers/), including more than 10 international options, you can create a premium shipping experience. Customize delivery methods for each country and decide which options appear at checkout: * **Nominated day delivery** allows your customers to pick a preferred delivery day * **Same-day delivery** lets you stay ahead of the competition with the fastest possible delivery services * **Standard delivery** provides next-day, standard and international shipping options via a huge range of flexible shipping methods * **Service point delivery** allows your customers to pick a preferred service point Delivery options are configured directly via the Sendcloud platform, so you can create, customize and publish your checkout page in a matter of minutes. **Tip:** You can find the full documentation for setting up your [Dynamic Checkout](https://support.sendcloud.com/hc/en-us/sections/4404607546132-Dynamic-Checkout) configuration, and learn more about the different delivery options and supporting carriers, in our Help Center. ### Development status The Dynamic Checkout v3 API is currently in [beta](https://support.sendcloud.com/hc/en-us/articles/4417167140756-What-is-beta-), meaning that it is still under development. During this phase, we continually monitor and test the API to improve its performance, review the requested and the returned data, and uncover any potential bugs that could have a future impact on our users. Please note that there is a possibility of experiencing breaking changes while the API is still in beta. # Retrieve a list of delivery options Source: https://sendcloud.dev/api/v3/dynamic-checkout/retrieve-a-list-of-delivery-options /.openapi/v3/dynamic-checkout/openapi.yaml get /checkout/configurations/{configuration_id}/delivery-options The options returned by this endpoint are based on the [delivery methods](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4) previously configured in addition to cart or order information, such as parcel weight, total order value, destination country, and more. This endpoint is deprecated as of Tue, 09 Jun 2026. We recommend using the [Generate a list of delivery options](/api/v3/dynamic-checkout/generate-a-list-of-delivery-options) endpoint instead. ## Why is this endpoint deprecated? We've introduced a simpler, more flexible way to fetch delivery options, and we're focusing future Dynamic Checkout improvements there. With the [Generate a list of delivery options](/api/v3/dynamic-checkout/generate-a-list-of-delivery-options) endpoint, you no longer need to keep track of a configuration ID or pass it in the URL. It automatically picks up the Dynamic Checkout configuration you've published for your API integration, so there's nothing to hardcode and your checkout always reflects your latest published setup. It also accepts your cart and order details in a request body instead of as query parameters. This makes room for richer, nested information today and lets us keep adding new Dynamic Checkout features over time. *** To use this API, you first need to [create your own Dynamic Checkout configuration](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout) in the Sendcloud platform. Follow these steps to get started: 1. Log in to your Sendcloud account and navigate to the **Dynamic Checkout** tab. 2. Select your API integration from the **Shops** section to customize your delivery options. 3. When you're done, click **Publish** to connect your configuration to the selected API integration. This API allows your customers to choose their preferred delivery options during checkout. The options returned by this endpoint are based on the [delivery methods](https://support.sendcloud.com/hc/en-us/articles/360057944932-How-to-configure-Dynamic-Checkout#4) previously configured in addition to cart or order information, such as parcel weight, total order value, destination country, and more. You can display the returned delivery options to your customers on your checkout page, where they can select their preferred option for their order. ## How do delivery options correspond to configured delivery methods? This API returns one delivery option per carrier configured in Dynamic Checkout. If a delivery method is configured with multiple carriers, then multiple delivery options will be returned - one per carrier. In cases when delivery options correspond to the same delivery method, delivery options' ids will refer to the same delivery method id, leaving API users with a flexibility to perform grouping based on a delivery method id, if desired. ## How can I create a shipment out of the selected delivery option? Use the `checkout_identifier_type=shipping_option_code` parameter when requesting delivery options. This makes the `checkout_identifier` field of the selected delivery option contain the shipping option code required for creating a shipment. To proceed, call the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint, setting `ship_with.type` to `"shipping_option_code"` and `ship_with.properties.shipping_option_code` to the value of the `checkout_identifier` field. # Create a connection Source: https://sendcloud.dev/api/v3/event-subscriptions/create-a-connection /.openapi/v3/event-subscriptions/openapi.yaml post /event-subscriptions/connections Create a new connection to an external endpoint where event notifications will be delivered. Create a new connection that defines an external endpoint for event delivery. **Webhook connections** require a `url` and optionally authentication configuration. Supported authentication types are `none`, `bearer`, `basic`, and `api_key`. **Klaviyo connections** require only the `type` field set to `klaviyo` with an empty `configuration` object. After creating the connection, use the [Start OAuth2 authorization](/api/v3/event-subscriptions/start-oauth2-authorization) endpoint to connect your Klaviyo account. Webhook URLs must be publicly accessible and respond with a `2xx` status code to acknowledge event delivery. # Create a subscription Source: https://sendcloud.dev/api/v3/event-subscriptions/create-a-subscription /.openapi/v3/event-subscriptions/openapi.yaml post /event-subscriptions/subscriptions Create a new subscription that routes events of a specific type to a connection. Create a subscription that routes a specific event type to a connection for delivery. A subscription links an event type (e.g., `parcels.event.created`) to a connection endpoint. When the event occurs, the event payload is delivered to the connection's configured endpoint. Subscriptions are active by default. Set `is_active` to `false` to create a paused subscription. # Delete a connection Source: https://sendcloud.dev/api/v3/event-subscriptions/delete-a-connection /.openapi/v3/event-subscriptions/openapi.yaml delete /event-subscriptions/connections/{id} Delete a specific connection by its id. Any subscriptions associated with this connection will also be deleted. Delete a connection and all its associated subscriptions. This action is irreversible. All subscriptions linked to this connection will be permanently deleted and event delivery will stop immediately. # Delete a subscription Source: https://sendcloud.dev/api/v3/event-subscriptions/delete-a-subscription /.openapi/v3/event-subscriptions/openapi.yaml delete /event-subscriptions/subscriptions/{id} Delete a specific subscription by its id. Event delivery for this subscription will stop immediately. # Get a connection Source: https://sendcloud.dev/api/v3/event-subscriptions/get-a-connection /.openapi/v3/event-subscriptions/openapi.yaml get /event-subscriptions/connections/{id} Retrieve a specific connection by its id. # Get a subscription Source: https://sendcloud.dev/api/v3/event-subscriptions/get-a-subscription /.openapi/v3/event-subscriptions/openapi.yaml get /event-subscriptions/subscriptions/{id} Retrieve a specific subscription by its id. # Event Subscriptions API overview Source: https://sendcloud.dev/api/v3/event-subscriptions/index **BETA** - The Event Subscriptions API is currently in beta. Endpoints and behavior may change as the feature evolves. The Event Subscriptions API allows you to subscribe to parcel events and have them delivered to external endpoints such as webhooks or Klaviyo. This API uses a two-part model: * **Connections** define *where* events are delivered (e.g., a webhook URL or a Klaviyo account). * **Subscriptions** define *which* events are routed to a connection. ## Supported connection types | Type | Description | | --------- | ---------------------------------------------------------------- | | `webhook` | Delivers event payloads via HTTP POST to a URL you specify. | | `klaviyo` | Sends event data to your Klaviyo account via OAuth2 integration. | ## Supported event types | Event type | Description | | ----------------------- | ----------------------------------------------------------------------------------------------------- | | `parcels.event.created` | Triggered when a parcel event occurs (e.g., a status change such as shipped, delivered, or returned). | ## Webhook authentication When creating a webhook connection, you can configure authentication for event delivery requests. The following authentication types are supported: | Auth type | Description | Configuration | | --------- | ------------------------------------------------ | ------------------------------------------------------- | | `none` | No authentication. | No `auth_config` needed. | | `bearer` | Bearer token in the `Authorization` header. | `{ "token": "your-token" }` | | `basic` | Basic authentication with username and password. | `{ "username": "user", "password": "pass" }` | | `api_key` | API key sent as a custom header. | `{ "header_name": "X-Api-Key", "api_key": "your-key" }` | You can also add custom headers to webhook requests using the `extra_headers` field. ## Retry behavior When delivering events to a webhook endpoint, Sendcloud will retry failed deliveries up to **5 times** using exponential backoff. A delivery is considered failed when the endpoint returns a non-2xx HTTP status code or is unreachable. ## Testing event delivery You can verify that your connection is configured correctly by using the [Broadcast test event](/api/v3/event-subscriptions/test-event-delivery) (`/broadcast/test/{subscription_id}`) endpoint. This sends a sample event payload to the connection endpoint and returns the result, including the HTTP status code and response body. # List connections Source: https://sendcloud.dev/api/v3/event-subscriptions/list-connections /.openapi/v3/event-subscriptions/openapi.yaml get /event-subscriptions/connections Retrieve all connections for the authenticated user's organization. # List subscriptions Source: https://sendcloud.dev/api/v3/event-subscriptions/list-subscriptions /.openapi/v3/event-subscriptions/openapi.yaml get /event-subscriptions/subscriptions Retrieve all subscriptions for the authenticated user's organization. # Parcel event created Source: https://sendcloud.dev/api/v3/event-subscriptions/parcel-event-created /.openapi/v3/event-subscriptions/openapi.yaml webhook ParcelEventCreated Delivered to your connection endpoint when a parcel tracking event occurs (e.g., a status change such as shipped, delivered, or returned). Subscribe to this event type using `parcels.event.created` when creating a subscription. # Start OAuth2 authorization Source: https://sendcloud.dev/api/v3/event-subscriptions/start-oauth2-authorization /.openapi/v3/event-subscriptions/openapi.yaml post /event-subscriptions/connections/{id}/authorization Initiate the OAuth2 authorization flow for a connection that requires it (e.g., Klaviyo). Returns an authorization URL to redirect the user to. Start the OAuth2 authorization flow for a Klaviyo connection. This endpoint returns an authorization URL that the user should be redirected to in their browser. After the user authorizes access, the OAuth provider will redirect back to the Sendcloud callback URL, completing the connection setup. Use the [Create a connection](/api/v3/event-subscriptions/create-a-connection) endpoint with `type: "klaviyo"`. Call this endpoint to get the authorization URL. Open the `authorization_url` in the user's browser to complete the OAuth2 flow. # Broadcast test event Source: https://sendcloud.dev/api/v3/event-subscriptions/test-event-delivery /.openapi/v3/event-subscriptions/openapi.yaml post /event-subscriptions/broadcast/test/{subscription_id} Send a test event to the connection endpoint configured for a specific subscription. Use this to verify that your connection is set up correctly before relying on it for production events. Send a test event to the connection endpoint configured for this subscription. This is useful for verifying that your webhook URL or Klaviyo integration is set up correctly. The test event will contain a sample payload matching the subscription's event type. The test broadcast will use the same authentication and headers configured on the connection. # Update a connection Source: https://sendcloud.dev/api/v3/event-subscriptions/update-a-connection /.openapi/v3/event-subscriptions/openapi.yaml patch /event-subscriptions/connections/{id} Update an existing connection by its id. Only the fields provided in the request body will be updated. Update the configuration of an existing connection. Only the fields provided in the request body will be updated. For example, you can update just the webhook URL or authentication settings without changing other fields. Updating a connection's configuration may affect all subscriptions that use this connection. # Update a subscription Source: https://sendcloud.dev/api/v3/event-subscriptions/update-a-subscription /.openapi/v3/event-subscriptions/openapi.yaml patch /event-subscriptions/subscriptions/{id} Update an existing subscription by its id. Only the fields provided in the request body will be updated. Update an existing subscription. You can change the connection, event type, or toggle the active state. Set `is_active` to `false` to pause event delivery without deleting the subscription. # Retrieve a list of events Source: https://sendcloud.dev/api/v3/events/retrieve-a-list-of-events /.openapi/v3/events/openapi.yaml get /events Retrieves a list of events for the authenticated organization. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. # Introduction Source: https://sendcloud.dev/api/v3/index API v3 is the latest version of the Sendcloud API. It brings a redesigned, resource-oriented interface for shipping, tracking, returns, and post-purchase experiences, with consistent pagination, richer error handling, and webhooks for real-time events. Before your first request, [set up authentication](/docs/getting-started/authentication/). If you're authenticating with OAuth 2.0, head to the [OAuth2 token endpoint](/api/v3/oauth2/token) reference. ## Featured APIs A selection of what you can build with API v3. Browse the sidebar for the complete list of endpoints. Moving from API v2? Read the [migration guidelines for API v3](/docs/getting-started/migration-guidelines-for-api-v3/) to see an overview of changes and plan your upgrade. ### Shipping Compare carriers and prices across available shipping options for a shipment. Create and manage orders before they're shipped. Create a shipment and request a label in one step. Announce shipments synchronously or asynchronously, then retrieve or cancel them. ### Checkout & delivery options Show delivery options at checkout based on your configuration. Find service points and check their availability for delivery. Calculate duties and taxes for cross-border shipments. ### Tracking & post-purchase Track parcels and create external parcels for tracking. Create, validate, retrieve, and cancel returns. Raise support tickets for lost, damaged, or delayed parcels. ### Events & notifications Receive real-time payloads for status changes, returns, and integrations. Manage connections and subscriptions to Sendcloud events. ### Carrier & account setup Configure carrier contracts for your account. Schedule and manage carrier pickups. Retrieve the sender addresses configured for your account. Retrieve the brands configured for your account. ### Data & insights Retrieve transit times for carriers and shipping options. Generate and download parcel reports. ### Integrations Manage integrations, order statuses, status mapping, and exception logs. # Create integration exception logs Source: https://sendcloud.dev/api/v3/integrations/create-integration-exception-logs /.openapi/v3/integrations/openapi.yaml post /integrations/{id}/logs Create integration exception logs, which will appear in the connection issue log screen of the user's integration. # Create or overwrite shop order statuses Source: https://sendcloud.dev/api/v3/integrations/create-or-overwrite-shop-order-statuses /.openapi/v3/integrations/openapi.yaml post /shop-order-statuses Insert shop-specific custom statuses into the Sendcloud system. Only the Prestashop V2 integration is supported. Note that: * Integrations can have their own custom shop statuses. * To get your order updates in time, Sendcloud needs to know what statuses are available. * This endpoint updates all existing statuses. That includes creating new statuses, changing existing ones, and deleting ones that no longer exist. # Create or update custom status mapping for an integration Source: https://sendcloud.dev/api/v3/integrations/create-or-update-custom-status-mapping-for-an-integration /.openapi/v3/integrations/openapi.yaml post /shop-order-statuses/mapping Upsert a map of available shop order statuses and Sendcloud's internal status category for an integration Only the Prestashop V2 integration is supported. # Delete an integration Source: https://sendcloud.dev/api/v3/integrations/delete-an-integration /.openapi/v3/integrations/openapi.yaml delete /integrations/{id} Safely delete one of your integrations from the Sendcloud system # Integrations API overview Source: https://sendcloud.dev/api/v3/integrations/index ## What can you do with this API? * Control some parts of your integrations, e.g. configuring service-point carriers and deleting an integration. * Retrieve and create integration exception logs. These logs are generated when integrations have problems making API requests to shop systems. * Set and retrieve available shop order statuses. These can be used to decide when to trigger certain actions for an order feedback. # Retrieve a list of integrations Source: https://sendcloud.dev/api/v3/integrations/retrieve-a-list-of-integrations /.openapi/v3/integrations/openapi.yaml get /integrations Retrieve all valid integrations from the Sendcloud system for a given user. # Retrieve all integration exception logs Source: https://sendcloud.dev/api/v3/integrations/retrieve-all-integration-exception-logs /.openapi/v3/integrations/openapi.yaml get /integrations/logs Retrieve all integration exception logs. These logs are created when integrations have problems making API requests to shop systems. Integration exception logs might be generated, for example: * if some resource cannot be found * if API credentials are no longer valid Each log record may contain information about the request and response, the status code and code exception, and can be used as a reference to identify issues between Sendcloud and a webshop. Pagination is cursor-based. Use the `cursor` query parameter to navigate through pages. The `Link` response header contains the URL for the next page when more results are available. # Retrieve an integration Source: https://sendcloud.dev/api/v3/integrations/retrieve-an-integration /.openapi/v3/integrations/openapi.yaml get /integrations/{id} Get a valid integration from the Sendcloud system # Retrieve custom status mapping for an integration Source: https://sendcloud.dev/api/v3/integrations/retrieve-custom-status-mapping-for-an-integration /.openapi/v3/integrations/openapi.yaml get /shop-order-statuses/mapping Fetch a map of available shop order statuses and Sendcloud's internal status category for the integration. Only the Prestashop V2 integration is supported. # Retrieve exception logs for a specific integration Source: https://sendcloud.dev/api/v3/integrations/retrieve-exception-logs-for-a-specific-integration /.openapi/v3/integrations/openapi.yaml get /integrations/{id}/logs Retrieve exception logs for a specific integration. These logs are created when integrations have problems making API requests to shop systems. Integration exception logs might be generated, for example: * if some resource cannot be found * if API credentials are no longer valid Each log record may contain information about the request and response, the status code and code exception, and can be used as a reference to identify issues between Sendcloud and a webshop. Pagination is cursor-based. Use the `cursor` query parameter to navigate through pages. The `Link` response header contains the URL for the next page when more results are available. # Retrieve shop order statuses for an integration Source: https://sendcloud.dev/api/v3/integrations/retrieve-shop-order-statuses-for-an-integration /.openapi/v3/integrations/openapi.yaml get /shop-order-statuses Fetch all available shop order statuses for the Prestashop v2 integration, in the default or selected language. Only the Prestashop V2 integration is supported. Note that: * If the user hasn't picked a language, they will receive the status in the default language, `en-gb`. * If `en-gb` is not present, the user receives the status in the first language of the alphabetically ordered list. # Update certain parts of an integration Source: https://sendcloud.dev/api/v3/integrations/update-certain-parts-of-an-integration /.openapi/v3/integrations/openapi.yaml patch /integrations/{id} Update the shop name, shop URL, service point settings, webhook settings, and feedback type of an integration. You can update certain parts of an integration with this endpoint: * Update the shop name of an integration * Update the shop URL of an integration * Enable service points and select the appropriate service point carriers * Enable webhooks and set the webhook URL * Change the type of feedback you would like the integration to follow # Invoice Items API overview Source: https://sendcloud.dev/api/v3/invoice-items/index The **Invoice Items API** lets you retrieve the billable line items charged to your Sendcloud account. An invoice item is a single billable line — for example a parcel fee, a pickup fee, or a subscription charge. This API is currently in **beta**. Its shape may change in backwards-incompatible ways while we collect feedback. ## Pending vs invoiced items Invoice items are returned **before** they are consolidated onto an invoice, so you can reconcile expected spend in near real-time. * **Invoiced** items have `invoice_id` set, along with `tax` and `tax_rate`. * **Pending** items have `invoice_id`, `tax`, and `tax_rate` set to `null`. Tax is only computed when the item is invoiced. Pending invoice items are **not final**. Amounts and types can still change, and Sendcloud may remove items, up until they are consolidated onto an invoice. Treat pending items as a preview, not a guarantee. ## Filtering Filter the list with `created_after` / `created_before` (compared against the item's billing date, both inclusive), `parcel_id`, `invoice_id`, or `type`. See the [Retrieve a list of invoice items](/api/v3/invoice-items/retrieve-a-list-of-invoice-items) endpoint for the full list of supported parameters. ## Pagination This endpoint uses cursor-based pagination via `Link` response headers. See [Pagination](/api/v3/pagination) for details. # Retrieve a list of invoice items Source: https://sendcloud.dev/api/v3/invoice-items/retrieve-a-list-of-invoice-items /.openapi/v3/invoice-items/openapi.yaml get /invoice-items Retrieve a paginated list of invoice items for your organization. The response includes both **invoiced** items (where `invoice_id` is set) and **pending** items that have been billed but not yet consolidated onto an invoice (where `invoice_id` is `null` and `tax` / `tax_rate` are `null`). Use the date filters to scope the result set; the cursor in the `Link` response header to page through results. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. Pending invoice items (where `invoice_id` is `null`) are **not final**. Amounts and types can still change, and Sendcloud may remove items, up until they are consolidated onto an invoice. Treat pending items as a preview, not a guarantee. This endpoint is currently in **beta**. Its shape may change in backwards-incompatible ways while we collect feedback. # Retrieve an invoice item Source: https://sendcloud.dev/api/v3/invoice-items/retrieve-an-invoice-item /.openapi/v3/invoice-items/openapi.yaml get /invoice-items/{invoice_item_id} Retrieve a single invoice item by id. The item may be **invoiced** (`invoice_id` set, `tax` and `tax_rate` populated) or **pending** (`invoice_id`, `tax`, and `tax_rate` are `null`). Pending invoice items (where `invoice_id` is `null`) are **not final**. Amounts and types can still change, and Sendcloud may remove items, up until they are consolidated onto an invoice. Treat pending items as a preview, not a guarantee. This endpoint is currently in **beta**. Its shape may change in backwards-incompatible ways while we collect feedback. # Invoices API overview Source: https://sendcloud.dev/api/v3/invoices/index The **Invoices API** lets you retrieve the invoices issued to your Sendcloud account. Each invoice consolidates a set of [invoice items](/api/v3/invoice-items/retrieve-a-list-of-invoice-items) — for example parcel fees, pickup fees, or subscription charges — into a single billable document. This API is currently in **beta**. Its shape may change in backwards-incompatible ways while we collect feedback. ## Categories Invoices have one of two categories: * `transactional` — invoices that consolidate shipping-related charges (parcels, pickups, surcharges, etc.). * `subscription` — invoices for your Sendcloud subscription plan. ## Issuer The `issuer` block reflects the Sendcloud subsidiary that issued the invoice (business name, address, VAT id, chamber-of-commerce id). Use it to reconcile against your bookkeeping records. ## Pagination This endpoint uses cursor-based pagination via `Link` response headers. See [Pagination](/api/v3/pagination) for details. # Retrieve a list of invoices Source: https://sendcloud.dev/api/v3/invoices/retrieve-a-list-of-invoices /.openapi/v3/invoices/openapi.yaml get /invoices Retrieve a paginated list of invoices for your organization. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. This endpoint is currently in **beta**. Its shape may change in backwards-incompatible ways while we collect feedback. # Retrieve an invoice Source: https://sendcloud.dev/api/v3/invoices/retrieve-an-invoice /.openapi/v3/invoices/openapi.yaml get /invoices/{invoice_id} Retrieve a single invoice by id. This endpoint is currently in **beta**. Its shape may change in backwards-incompatible ways while we collect feedback. # OAuth 2.0 token Source: https://sendcloud.dev/api/v3/oauth2/token /.openapi/v3/auth/openapi.yaml post /oauth2/token Use this endpoint to get a new OAuth 2.0 access token. OAuth 2.0 authentication is currently available as a beta feature for a limited number of clients. Following this beta phase, we are planning a gradual rollout of the OAuth2 authentication feature to all users. Our aim is to ensure a smooth transition and to continue providing an optimal user experience throughout the process. You can find a list of open-source libraries to help with OAuth 2.0 authentication at [https://oauth.net/code/](https://oauth.net/code/) # Create/Update orders in batch Source: https://sendcloud.dev/api/v3/orders/create-update-orders-in-batch /.openapi/v3/orders/openapi.yaml post /orders Use this endpoint to insert orders into a Sendcloud API integration. Each order can have a different integration id, so you can create/update orders for multiple integrations in one request. ## Upsert behavior This is an **upsert** endpoint, which means: * If an order with the same `order_id` and `integration.id` combination **already exists**, it will be **updated** * If no matching order exists, a **new order will be created** * **Optional**: You can include the Sendcloud `id` field to explicitly update a specific order * **Important**: When returned in responses, `id` is an **integer**, but when sending it in requests, it must be a **string** * Example: Response returns `"id": 669`, but request must send `"id": "669"` ## Batch processing * Process multiple orders in a single request (up to **100 orders maximum**) * Orders from different integrations can be included in the same batch * **All-or-nothing transaction**: If any order in the batch fails validation, the entire batch is rejected and zero orders are created or updated. There is no partial success — either all orders are processed or none are * On failure (HTTP 400), the response includes error details with `source.pointer` indicating which order in the array caused the issue (e.g., `[1]` for the second order, 0-indexed) * If you send multiple orders and one fails, you need to fix the failing order and resubmit the entire batch ## Limitations and constraints * **Maximum batch size**: 100 orders per request * **Upsert matching**: Orders are matched by the combination of `order_id` + `integration.id` * **Immutable fields**: When updating existing orders, certain fields like `order_id` cannot be changed * **Concurrent processing**: If the same `order_id` is being processed by another request, you'll receive a conflict error. Wait a moment and retry * **Integration access**: You can only create/update orders for integrations that belong to your account ## Asynchronous processing Order saving happens **asynchronously**. A successful `201` response means the request was accepted, but the order may not be immediately available for other operations (e.g., creating a label via the [Ship an Order API](/api/v3/ship-an-order)). * After creating an order, **verify it exists** by retrieving it with the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint before attempting to ship it * If you plan to create an order and immediately ship it, allow a short delay and confirm the order is available before calling the Ship an Order API ## Best practices * Ensure all required fields are present before sending the request * Handle errors gracefully and implement retry logic for transient failures # Delete an order Source: https://sendcloud.dev/api/v3/orders/delete-an-order /.openapi/v3/orders/openapi.yaml delete /orders/{id} Delete an order by its unique id. # Orders API overview Source: https://sendcloud.dev/api/v3/orders/index The Orders API allows you to manage orders within Sendcloud in the following ways: * Retrieve a list of orders per integration * Retrieve a single order * Partially update a single order * Create and update orders in batch * Delete a single order # Retrieve a list of orders Source: https://sendcloud.dev/api/v3/orders/retrieve-a-list-of-orders /.openapi/v3/orders/openapi.yaml get /orders Get a list of orders filtered by integration, order number, order ID, order status, creation date, and update date. You can also optionally sort the results and pass a `cursor` value. This endpoint lets you get a list of orders from the API in the same way you can find it on the Incoming Orders overview in the Sendcloud platform. The endpoint is paginated. You can navigate through the results by using the URLs of the `next` and `prev` fields in the `Link` response header. # Retrieve an order Source: https://sendcloud.dev/api/v3/orders/retrieve-an-order /.openapi/v3/orders/openapi.yaml get /orders/{id} Find a specific order by its order ID. # Update an order Source: https://sendcloud.dev/api/v3/orders/update-an-order /.openapi/v3/orders/openapi.yaml patch /orders/{id} Partially update some fields of an order. # Retrieve organization information Source: https://sendcloud.dev/api/v3/organization/retrieve-information-about-the-organization /.openapi/v3/organization/openapi.yaml get /organization Retrieves detailed information about your organization account, including the organization ID, name, and registration date. This endpoint is useful for: - Verifying your organization's account details and settings - Obtaining your organization ID for use in other API calls or integrations - Confirming registration date and account metadata # Pagination Source: https://sendcloud.dev/api/v3/pagination Paginated endpoints in the Sendcloud v3 API use **cursor-based pagination** with HTTP `Link` headers. Unlike offset-based pagination, cursor-based pagination provides stable results even when data changes between requests. ## How it works Pagination links (`next`, `prev`) are returned in the HTTP **`Link` response header**, not in the JSON response body. The response body only contains a `data` array. ### Query parameters | Parameter | Type | Required | Description | | ----------- | ------- | -------- | -------------------------------------------------------------------------- | | `cursor` | string | No | The pagination cursor value from a previous response's `Link` header. | | `page_size` | integer | No | Number of results per page. Clamped between 0 and the endpoint's max size. | ### Link header format When there are more pages available, the response includes a `Link` header with `next` and/or `prev` URLs: ``` Link: ; rel="next", ; rel="prev" ``` The `cursor` values are **base64-encoded and opaque**. Do not parse or construct them manually — pass them back as-is from the `Link` header. ### Example response **Response headers:** ``` HTTP/1.1 200 OK Content-Type: application/json Link: ; rel="next" ``` **Response body:** ```json theme={null} { "data": [ { "id": 1, "...": "..." }, { "id": 2, "...": "..." } ] } ``` ## Iterating through all pages To retrieve all results, follow the `next` link from each response until no `next` link is returned: 1. Make an initial request to the list endpoint (optionally with `page_size`). 2. Parse the `Link` header from the response. 3. If a `rel="next"` URL is present, make a request to that URL. 4. Repeat until no `next` link is returned. # Retrieve a parcel document Source: https://sendcloud.dev/api/v3/parcel-documents/retrieve-a-parcel-document /.openapi/v3/parcel-documents/openapi.yaml get /parcels/{id}/documents/{type} Retrieve a specific document for a given parcel, and download it in your preferred format and resolution. Sendcloud generates the correct type of document for your shipment when you [Create a parcel](/api/v2/parcels/create-a-parcel-or-parcels), provided that you have filled in all the information related to the parcel contents, value and invoice. Use this endpoint to retrieve these documents in your preferred format. This endpoint supports the following document types: * `label` * `customs-declaration` * `air-waybill` * `proof-of-delivery` For international shipments, customs declaration must be attached (either physically or [digitally](https://support.sendcloud.com/hc/en-us/articles/4417349714452-Send-your-customs-documents-digitally-via-Paperless-Trade-) for some carriers) to the shipment for customs officials to access. `proof-of-delivery` is retrieved directly from the carrier on request and is only available once the parcel has been delivered. It is only returned in PDF format (`application/pdf`), and availability depends on the carrier supporting proof of delivery. # Retrieve multiple parcel documents Source: https://sendcloud.dev/api/v3/parcel-documents/retrieve-multiple-parcel-documents /.openapi/v3/parcel-documents/openapi.yaml get /parcel-documents/{type} Download multiple parcel documents of the same type in bulk. Sendcloud generates the correct type of document for your shipment when you [Create a parcel](/api/v2/parcels/create-a-parcel-or-parcels), provided that you have filled in all the information related to the parcel contents, value and invoice. Use this endpoint to retrieve these documents in bulk. This endpoint supports the following document types: * `label` * `customs-declaration` * `air-waybill` For international shipments, customs declaration must be attached (either physically or [digitally](https://support.sendcloud.com/hc/en-us/articles/4417349714452-Send-your-customs-documents-digitally-via-Paperless-Trade-) for some carriers) to the shipment for customs officials to access. `proof-of-delivery` is not available on this bulk endpoint. Unlike the other document types, which are generated and stored by Sendcloud, proof of delivery is fetched with a live call to the carrier for each individual parcel, so it cannot be retrieved in bulk. Use [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) to request proof of delivery for a single parcel. # Retrieve a list of parcel statuses Source: https://sendcloud.dev/api/v3/parcel-statuses/retrieve-a-list-of-parcel-statuses /.openapi/v3/parcel-statuses/openapi.yaml get /parcels/statuses Get a list of all parcel statuses available in the Sendcloud system, with their unique code and friendly description. # Create an external parcel for tracking Source: https://sendcloud.dev/api/v3/parcel-tracking/create-an-external-parcel-for-tracking /.openapi/v3/parcel-tracking/openapi.yaml post /parcels/tracking Register an external parcel in the Sendcloud system for tracking, based on the provided details. It requires a valid tracking number and parcel information. Register a parcel in the Sendcloud system exclusively for tracking, without creating a shipment label. This is useful when you create labels outside of Sendcloud but still want to track the parcels within the platform. Provide the tracking number, carrier, sender and recipient addresses, and optionally include parcel items, measurements, and insurance details. This endpoint is currently in beta. While the core functionality is stable, some details or behavior may change as the API is finalized. Review your integration periodically and check release notes for updates. To see the parcel in [Analytics](https://support.sendcloud.com/hc/en-us/sections/28788521497745-Analytics), include the `shipping_option_code` in the `ship_with` property. Parcels created without a shipping option code will not appear in analytics. You can retrieve valid shipping option codes via the [Shipping Options API](/docs/shipments/shipping-options-and-quotes). # Retrieve tracking information for a parcel Source: https://sendcloud.dev/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel /.openapi/v3/parcel-tracking/openapi.yaml get /parcels/tracking/{tracking_number} Get information about a parcel, including its current status and recent tracking events, using its tracking number # Create a pickup Source: https://sendcloud.dev/api/v3/pickups/create-a-pickup /.openapi/v3/pickups/openapi.yaml post /pickups Schedule a one-time pickup with a supported carrier. This endpoint allows you to schedule a pickup with one of the [supported carriers](/api/v3/pickups#which-carriers-support-pickups-via-the-api). Schedule a pickup time and choose a location, and include any additional instructions to the driver by including the `special_instructions` parameter. Once a pickup is successfully scheduled, a pickup `id` will be returned. If you have more than one active contract for the carrier, you must include the `contract` field with your desired contract ID in your request. You can get your contract ID from the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint. # Pickups API overview Source: https://sendcloud.dev/api/v3/pickups/index Scheduling a pickup allows you to have your parcels collected by a driver from a location of your choice. When scheduling a pickup via the **Pickups API**, the sender address is dynamic, which means you don't have to have a sender address saved in your Sendcloud account settings. When you schedule a pickup via the API, you can only schedule a **one-time collection**. Depending on your shipping volume, it's possible to schedule a recurring pick-up from your preferred location weekly or more often. **Tip:** Schedule your collection **at least 2 working days in advance** to keep some time for processing. ## Which carriers support pickups via the API? Currently, you can use the Pickups API to schedule a pickup with the following carriers: * [BRT](https://support.sendcloud.com/hc/en-us/articles/360044948452-BRT-Bartolini-shipping-conditions) * [Correos](https://support.sendcloud.com/hc/en-us/articles/360031819932-Correos-shipping-conditions) * [Correos Express](https://support.sendcloud.com/hc/en-us/articles/360031821112-Correos-Express-shipping-conditions) * [DHL](https://support.sendcloud.com/hc/en-us/articles/360024846472-DHL-shipping-conditions-Netherlands) * [DHL Express](https://support.sendcloud.com/hc/en-us/articles/360025147811-DHL-Express-shipping-conditions-Netherlands-) * [DHL Germany](https://support.sendcloud.com/hc/en-us/articles/7372563091092-DHL-DE-shipping-conditions-Germany) * [DHL Parcel GB](https://support.sendcloud.com/hc/en-us/articles/8797021719316-DHL-eCommerce-UK-contract-activation) * [DHL Parcel Iberia](https://support.sendcloud.com/hc/en-us/articles/12898927670545-DHL-Parcel-Iberia-contract-activation) * [DPD](https://support.sendcloud.com/hc/en-us/articles/360025834352-DPD-shipping-conditions-Germany) * [DPD Austria](https://support.sendcloud.com/hc/en-us/articles/4413515365012-DPD-Surcharges-Austria) * [FedEx](https://support.sendcloud.com/hc/en-us/articles/360058873371-FedEx-shipping-conditions-) * [GLS Italy](https://support.sendcloud.com/hc/en-us/articles/19744693801361-GLS-Italy-shipping-conditions) * [Poste Italiane Delivery](https://support.sendcloud.com/hc/en-us/articles/6368506777236-Poste-Delivery-Business-shipping-conditions) * [UPS](https://support.sendcloud.com/hc/en-us/articles/7516003425812-UPS-shipping-conditions) # Retrieve a list of pickups Source: https://sendcloud.dev/api/v3/pickups/retrieve-a-list-of-pickups /.openapi/v3/pickups/openapi.yaml get /pickups Get information about all the pickups which have been created from your account. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. This is limited to the [carriers which support pickups via the API](/api/v3/pickups#which-carriers-support-pickups-via-the-api). The response includes information about when the pickup was scheduled, the latest status, the parcel tracking number and the time frame in which the pickup is due to take place. # Retrieve a pickup Source: https://sendcloud.dev/api/v3/pickups/retrieve-a-pickup /.openapi/v3/pickups/openapi.yaml get /pickups/{id} Retrieve information about a specific pickup based on the pickup `id`. # Create a parcels report Source: https://sendcloud.dev/api/v3/reporting/create-a-parcels-report /.openapi/v3/reporting/openapi.yaml post /reporting/parcels Generate a CSV report containing information about outgoing or incoming parcels. The parcels included in the report are determined by the `filters` you send, and the columns are determined by the `fields` you select. Use this endpoint to create the report and obtain the report `id`, which you then poll with [Retrieve a parcels report](/api/v3/reporting/retrieve-a-parcels-report) until the CSV is ready for download. # Reporting API overview Source: https://sendcloud.dev/api/v3/reporting/index The **Reporting API** lets you generate and download CSV reports containing data related to your Sendcloud account for tracking and analysis purposes. You can refine the data which will be included by selecting which fields to show on the report, and filter on when the parcel was announced or updated in the Sendcloud system. Reports are generated asynchronously: create the report, then poll its status until the CSV is ready to download. Reporting endpoints are gated by per-feature access. Depending on your account's plan and enabled features, the Reporting API may not be available to you. ## What can you do with this API? * Create a parcels CSV report filtered by date window, direction, integration, brand, or shipping option * Retrieve a parcels report by id to check its status and download the CSV once it's ready **Tip:** To create a report of your return shipments, include the property `direction: "incoming"`. Similarly, `direction: "outgoing"` will create a report of your outgoing shipments. Omit the field to include both incoming and outgoing parcels. Each report is capped at 100,000 parcels. If your filters match more, the report fails with a `400` response and a detail message like `CSV export exceeds row limit of 100000, ...`. Narrow the date range or apply additional filters to stay under the cap. # Retrieve a parcels report Source: https://sendcloud.dev/api/v3/reporting/retrieve-a-parcels-report /.openapi/v3/reporting/openapi.yaml get /reporting/parcels/{report_id} Retrieve a parcels report by id, including its current status and download URL when ready. Use the `id` returned by [Create a parcels report](/api/v3/reporting/create-a-parcels-report). The report is generated asynchronously, so poll this endpoint until `status` is `ready`; the CSV is then available at the `url` field. Reports expire after a fixed period (see `expires_at`). Once expired, the download URL is no longer valid and the report must be regenerated. # Create a return Source: https://sendcloud.dev/api/v3/returns/create-a-return /.openapi/v3/returns/openapi.yaml post /returns Create a standalone return The Create a return endpoint is the heart of the Returns API; it allows you to create a stand-alone return, based mainly on the `to` and `from_address`, parcel `weight` and the `ship_with` object. You can provide a list of items and item descriptions to be included in the return via the `parcel_items` field (optional). The `parcel_items` field is **mandatory** if you're creating a return from outside the EU. This is because information about the parcel contents must be provided in order to generate the required customs documents. ## The `ship_with` object This object is used to select a shipping method for the return. There are two ways of selecting a shipping method: * By providing a `shipping_option_code` (find the code using the [Shipping options API](/api/v3/shipping-options)). * By providing a `shipping_product_code` and a set of `functionalities`. Functionalities are used to filter the right shipping method within the product. Find this data using the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint. The `contract` attribute refers to the ID of a direct contract you have with the carrier. Get the IDs for your contracts from the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint. If you have more than one active contract for a specific carrier, you must fill the `contract` attribute with your desired contract ID in your request. ## Retrieve return shipping products In your request, you must provide an appropriate `shipping_product_code` and a set of `functionalities` inside the `ship_with` object. To find a suitable product, refer to the [Retrieve a list of shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint. You can filter for a return method by flagging the `returns` field as `true`, and by including the `from_country` and `to_country` fields. The more fields you specify, the more refined the results will be. This helps you find the most appropriate shipping product for your return parcel. It's also possible to filter based on your preferred [shipping functionality](/api/v2/shipping-products/retrieve-a-list-of-shipping-functionalities), e.g. `age_check=18`, `delivery_before`, etc. ## Add return reasons You can (optionally) assign a **return reason** to `parcel_items` by providing a`return_reason_id` and entering a value from the key below. Assigning return reasons to items provides you with analyzable data you can use to predict return trends or identify issues with particular products. | Return Reason ID | Description | | ---------------- | -------------------------------------------- | | 1 | Product did not match expectations | | 3 | Other (explain in message) | | 4 | Incorrect product ordered | | 6 | Product did not match description on website | | 7 | Wrong product shipped | | 8 | No reason | | 9 | Rent | | 10 | Does not work | | 11 | Changed my mind | | 12 | Did not meet expectations | | 13 | Excessive amount | | 14 | Better price available | | 15 | Accidental order | | 16 | No longer needed | | 17 | Sample products | | 18 | Looks different than expected | | 19 | Ordered more than one size | | 20 | Arrived too late | | 21 | Poor quality / Faulty | | 22 | Does not fit properly | | 23 | Does not suit me | | 24 | Incorrect product received | | 25 | Parcel damaged on arrival | | 26 | Wrong size ordered | | 27 | Wrong color ordered | | 28 | Does not function as expected | | 29 | Recycle or reuse packaging | | 30 | Size too large | | 31 | Size too small | | 32 | Holiday season return | ## Retrieve the shipping label for this return Once the parcel for the created return is announced, you can download the shipping label for it. Find the documentation on how to retrieve a label for a parcel on the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint. The url for downloading the label is also available on the Return object (Only if the parcel is announced). To retrieve a return, take a look at the [Retrieve a return](/api/v3/returns/retrieve-a-return) endpoint. To learn more about all the options for retrieving labels and customs declaration documents, refer to the [Parcel documents API](/api/v3/parcel-documents) documentation. # Create a return synchronously Source: https://sendcloud.dev/api/v3/returns/create-a-return-synchronously /.openapi/v3/returns/openapi.yaml post /returns/announce-synchronously Create a return synchronously, i.e. wait for a response from the carrier before continuing. This endpoint will create a return, similarly to the [Create a return](/api/v3/returns/create-a-return) endpoint, but via a synchronous API request. This means that the API will wait for a response from the carrier before you can continue. This endpoint is primarily used for **debugging purposes** in the event that a return parcel announcement fails, as it will retrieve the carrier announcement error. Creating a return synchronously can impact the performance of the endpoint, as the process will take longer than calls to the [Create a return](/api/v3/returns/create-a-return) endpoint. **Note:** The `parcel_items` field is mandatory if you're creating a return from outside the EU. # Returns API overview Source: https://sendcloud.dev/api/v3/returns/index The Sendcloud **Returns API** lets you create standalone returns easily and efficiently, so you can seamlessly incorporate returns into your existing workflow, ERP or WMS system. This API can be used in conjunction with other core Sendcloud features or independently. ## What can you do with this API? * Create a return parcel from national and international destinations * Retrieve a list of returns created within a specified time period, or with a specific parcel status * Retrieve return data, including up-to-date tracking information and return reasons per item * Validate a return before you create the shipping label to avoid unwanted carrier charges * Request a cancellation for a return parcel ## How does the Returns API differ from the Return portal API? The [Return portal API](/api/v2/return-portal) is designed to allow you to **build your own custom version** of the Sendcloud Return portal. It requires an outgoing parcel lookup step in order to create a return. Via the Returns API, you **don't need to have created the original outgoing parcel in Sendcloud** in order to create a return. This makes the Returns API an ideal solution for e-commerce retailers at every scale, even if you don't currently use Sendcloud to ship parcels or process orders. # Request cancellation of a return Source: https://sendcloud.dev/api/v3/returns/request-cancellation-of-a-return /.openapi/v3/returns/openapi.yaml patch /returns/{id}/cancel You can request cancellation for a return by providing the return `id` to this endpoint. Not all carriers support upstream label cancellation via an API request, therefore this endpoint will only send a cancellation **request**. A successful response indicates that the request is received and the carrier supports label cancellation. You can check the `parent_status` of the return via the [Retrieve a return](/api/v3/returns/retrieve-a-return) endpoint to confirm whether the actual cancellation was successful. You can find more information about carriers which do not support label cancellation requests in our [help center](https://support.sendcloud.com/hc/en-us/articles/4461608475284-How-to-cancel-a-return-shipment). # Retrieve a list of returns Source: https://sendcloud.dev/api/v3/returns/retrieve-a-list-of-returns /.openapi/v3/returns/openapi.yaml get /returns Retrieve a list of returns which have been created under your API credentials. The response includes return data for each parcel, plus up-to-date tracking history. The returned data is paginated and has a default number of items per page of `40`, which can be controlled by the `page_size` query param. You can filter the results to only include return parcels created within a specific time frame using the `from_date` and `to_date` parameters, or based on the `parent_parcel_status`. # Retrieve a return Source: https://sendcloud.dev/api/v3/returns/retrieve-a-return /.openapi/v3/returns/openapi.yaml get /returns/{id} Retrieve information about a specific return parcel based on the return `id`. This endpoint allows you to retrieve information about a specific return parcel based on the return `id`. A return `id` is assigned to every return you create in Sendcloud, and can be retrieved for all return parcels via the [Retrieve a list of returns](/api/v3/returns/retrieve-a-list-of-returns) endpoint. The returned object contains all relevant information about the return parcel, including up-to-date tracking information. # Validate a return Source: https://sendcloud.dev/api/v3/returns/validate-a-return /.openapi/v3/returns/openapi.yaml post /returns/validate Check if a return can be announced **without** actually creating the return, or announcing it with the carrier. This endpoint allows you to validate whether a return can be announced **without** actually creating the return or announcing it with the carrier. You can structure the request body exactly as you would if you were making a request to the [Create a return](/api/v3/returns/create-a-return) endpoint. When you make the request, the response will indicate whether the parcel is valid and can be announced. Validation is based mainly on the `to` and `from` address, the parcel `weight` and the shipping product `id` provided. The `parcel_items` field is **mandatory** if you're creating a return from outside the EU. # Retrieve a list of sender addresses Source: https://sendcloud.dev/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses /.openapi/v3/sender-addresses/openapi.yaml get /addresses/sender-addresses Returns a list of all the sender addresses which have been saved to your account. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. # Retrieve a sender address Source: https://sendcloud.dev/api/v3/sender-addresses/retrieve-a-sender-address /.openapi/v3/sender-addresses/openapi.yaml get /addresses/sender-addresses/{id} Retrieve information about a specific sender address saved to your account. A sender address `id` for use in this endpoint can be obtained from the [Retrieve a list of sender addresses](/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint. # Check availability of a service point Source: https://sendcloud.dev/api/v3/service-points/check-availability-of-a-service-point /.openapi/v3/service-points/openapi.yaml post /service-points/{service_point_id}/check-availability Check whether a service point is currently available. Service point availability can change over time. Although we try our best to return only service points that are considered up to date, search results may still include service points that are no longer available. The way availability is checked varies by carrier. For some carriers, this involves a live availability check with the carrier. For others, availability is determined using our best estimate based on the information available at the time of the request. # Service Points API overview Source: https://sendcloud.dev/api/v3/service-points/index Service points are carrier-operated locations where parcels can be sent or received instead of being delivered to a home address. These include parcel shops, post offices, automated lockers, and carrier depots. The Service Points API helps integrate service point delivery into checkout and shipment flows. ## Endpoints * [Search service points](/api/v3/service-points/retrieve-a-list-of-service-points) to find service points for selected carriers in a given area. * [Retrieve a service point](/api/v3/service-points/retrieve-a-service-point) to get the details of a specific service point by its identifier. * [Check availability](/api/v3/service-points/check-availability-of-a-service-point) to confirm whether a selected service point is still available. A typical flow starts by searching for service points, then showing the results to the customer, and finally confirming the selected service point before creating the shipment. ## Creating a shipment to a service point Once a customer selects a service point, pass the service point `id` in the `to_service_point` field when [creating a shipment](/api/v3/shipments/create-and-announce-a-shipment-synchronously) # Retrieve a list of service points Source: https://sendcloud.dev/api/v3/service-points/retrieve-a-list-of-service-points /.openapi/v3/service-points/openapi.yaml get /service-points Find service points for selected carriers in a given area. Returns service points in a given country for selected carriers. This endpoint is designed for checkout and delivery flows where customers need to choose a pickup location. It can be used to display service points on a map, show them as a list, or support automatic service point selection. ## Carrier selection A carrier scope must always be provided. Use `carrier_code` to search service points for specific carriers, or set `use_integration_carriers` to `true` to use the carriers enabled in the authenticated [integration's settings](https://app.sendcloud.com/v2/settings/integrations/manage). `carrier_code` and `use_integration_carriers` are mutually exclusive. Exactly one of them must be provided. In some cases, returned service points may belong to a different carrier than the one that was requested. This can happen when a carrier has been deprecated and superseded by another carrier, or when the requested carrier uses different carrier networks depending on the country. As a result, `carrier.code` in the response may differ from the requested `carrier_code`. This is expected behavior. When a carrier has been deprecated, switching to the replacement carrier code is recommended as soon as the deprecation is announced. Deprecated carrier codes may continue to work for some time through internal mapping, but compatibility after the deprecation deadline is not guaranteed. ## Reference point and geocoding A reference point is the location used to search for nearby service points. It can be provided as coordinates, as a free-text address, or as a structured address split into street, house number, postal code, and city. Free-text address input is usually the best fit when the address comes directly from a checkout form as a single string. Structured address input is useful when address parts are already available separately, because it removes ambiguity and can improve geocoding quality. For example, it makes it clearer which part of the input is the street, house number, postal code, or city. `address`, the structured `address_*` parameters, and `latitude`/`longitude` are mutually exclusive. Only one way of providing the reference point can be used in a single request. When using structured address parameters, `address_house_number` must be combined with `address_street` or `address_postal_code` - a house number on its own is not specific enough to locate an address. The geocoding result can be used to understand whether the address was resolved successfully and, if so, how precise the match is. When `data.geocoding.status` is `not_found`, the address could not be resolved and no service points are returned. When `data.geocoding.status` is partially\_matched, the address was matched, but not all parts of the input could be used. For example, a full address may be provided, but only the postal code could be matched. The search still runs based on the matched parts, and `data.geocoding.precision` reflects the resulting match level. When the address is resolved, `data.geocoding.precision` can be used to understand how specific the match is. This can help decide whether the result is precise enough for the current flow. For example, a full address may still resolve only to `postal_code` or `city`, which means the search is based on a broader area than the full address. Address geocoding depends on an external service. If this service is temporarily unavailable, the API returns 503 Service Unavailable, even when the request is valid. We do our best to keep this reliable, but if it happens, retrying after a short delay usually resolves it. ## Search area When a reference point is available, the API returns the closest matching service points around that location. By default, the closest `limit` results are returned. The search area can be narrowed in two ways: * use `radius` to return only service points within a given distance from the reference point * use `ne_latitude`, `ne_longitude`, `sw_latitude`, and `sw_longitude` to search within a bounding box Bounding boxes are especially useful for map-based interfaces where results should match the area currently visible on the map. `radius` and the bounding box parameters are mutually exclusive. When using a bounding box, all four bounding box parameters must be provided, and its diagonal must not exceed 50 km. ## Data freshness Service point details are refreshed regularly based on carrier updates. Because carriers differ in update frequency and coverage, some records may become outdated over time. This is reflected by the `is_expired` field. In area-based searches, only service points that are considered fresh enough are returned. When service points are requested explicitly by their identifier, expired service points may still be included in the response. ## Results Requests around a reference point return service points ordered by proximity to that location. Searches based on other filters, such as carrier-specific identifiers, do not have a guaranteed sort order. This endpoint is designed for service point discovery in checkout and map-based flows, so results are not paginated by design. Use `limit` to control the maximum number of service points returned for the use case. For example, if only the 5 closest service points need to be shown, a lower limit can reduce response size and avoid returning unnecessary results. # Retrieve a service point Source: https://sendcloud.dev/api/v3/service-points/retrieve-a-service-point /.openapi/v3/service-points/openapi.yaml get /service-points/{service_point_id} Retrieve a single service point. Returns a single service point. This endpoint can be used to retrieve the latest available details for a specific service point after it has been selected or stored in a checkout or delivery flow. The returned service point may be expired. Check `is_expired` before using the result in your flow. # Ship an Order API overview Source: https://sendcloud.dev/api/v3/ship-an-order/index The Ship an Order API allows you to create a shipment and request a label for an existing order in Sendcloud in one step, both asynchronously and synchronously. ## What you can do with this API | Action | Endpoint | | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Create a shipment and request the label immediately (asynchronously) | [Request a label for one or more orders asynchronously](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) | | Create a shipment and request the label later (synchronously) | [Request a label for a single order synchronously](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) | # Request a label for a single order synchronously Source: https://sendcloud.dev/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously /.openapi/v3/ship-an-order/openapi.yaml post /orders/create-label-sync Request a label for a single order and wait for the results. The label and any other documents will be provided in the response to this request. If you create orders via the [Orders API](/api/v3/orders/create-update-orders-in-batch) and then immediately request a label, the order may not yet be available. Order saving is **asynchronous**. A successful `201` response from the Orders API does not guarantee the order is immediately ready for shipping. Before calling this endpoint, verify the order exists by retrieving it with the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint. # Request a label for one or more orders asynchronously Source: https://sendcloud.dev/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously /.openapi/v3/ship-an-order/openapi.yaml post /orders/create-labels-async Request a label for a single or multiple orders. This endpoint will fail gracefully if some orders cannot be processed, returning any successfully created labels along with error details for the orders that failed. To retrieve your documents or view announcement errors, use the `id` of the relevant shipment with the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint. To apply shipping rules to the orders, make sure to set `apply_shipping_rules` to `true`. This endpoint will attempt to generate labels for each order. If a request for one label errors, it will still attempt to generate the other labels. Because of this, the response might return a mix of labels and errors. Use the errors `source` `pointer` field to see which labels encountered a problem. If you create orders via the [Orders API](/api/v3/orders/create-update-orders-in-batch) and then immediately request labels, the orders may not yet be available. Order saving is **asynchronous**. A successful `201` response from the Orders API does not guarantee the order is immediately ready for shipping. Before calling this endpoint, verify the order exists by retrieving it with the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint. # Cancel a shipment Source: https://sendcloud.dev/api/v3/shipments/cancel-a-shipment /.openapi/v3/shipments/openapi.yaml post /shipments/{id}/cancel Use this endpoint to cancel an announced shipment, if the carrier supports cancellation. You can use this endpoint to **Cancel** an announced shipment. ## Cancelling a shipment When you **cancel** a shipment which is already announced (has shipping labels attached to it), you will still be able to find it via the `id` and the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint. In the Sendcloud platform, it will appear in your **Cancelled labels** overview. **Insurance Notice**: If you proceed to send a shipment that was initially cancelled, the parcel's insurance coverage will become void, and any insurance claims will not be valid for that shipment. After 42 days, it's no longer possible to cancel a shipment, even if it hasn't been sent. ## Conditions for label cancellation It's not always possible to cancel a shipment whose parcel has already been announced. As a result, cancellation is not guaranteed and may be asynchronous depending on the state of the shipment parcel. When you send a cancellation request via this endpoint, the response will indicate the status of the cancellation request. Each carrier will have different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the label is cancelled within the deadline. You can find more information about cancellation deadlines on our [help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-). # Create a shipment with rules and/or defaults and announce it asynchronously Source: https://sendcloud.dev/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously /.openapi/v3/shipments/openapi.yaml post /shipments/create-with-shipping-rules Create and announce a shipment applying shipping rules and/or defaults asynchronously. The main advantage of this endpoint over the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint (and also the difference between them) is the ability to apply [shipping rules](https://app.sendcloud.com/v2/shipping/rules) and [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) to a shipment. Because of this, more fields in this endpoint are optional. If no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully: * `from_address` (from Ship with address) * `ship_with` (from Ship with) * `parcels` (from Set number of parcels) **Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).** ## Shipping rules * **Due to the data (shipments) that we receive in this API, NOT all of the shipping rules (actions or conditions) can (and will) be applied.** * **Shipping rules do not fully apply to multicollo shipments. In such cases, the rule conditions for weight, parcel dimensions (height, length, width), total order value, item name, item quantity, item SKU and total parcel item value will not be matched. Additionally, the following actions will not be triggered:** * Using a box (Use box) * Setting the weight (Set weight) * Setting the number of parcels (Set number of parcels) * Insuring the shipment value (Insure shipment value by) * Insuring it by percentage (Insure shipment value by %) * Increasing item value by percentage (Decrease item value by %) * Setting item HS code (Set Item HS Code) * Setting item name (Set item name) * Setting item origin country (Set Item Origin Country) * Setting item value (Set item value) * Setting item weight (Set item weight) **Please consider these limitations when defining rules.** ### Shipping rules conditions (IF) that can be applied * Carrier * Checkout delivery method * Company name * Customer email * Integration * Item SKU * Item name * Item quantity * Parcel height (cm) * Parcel length (cm) * Parcel width (cm) * Phone number * Postal code * To country * Total order value * Total parcel item value * Weight (kg) ## Shipping rules actions (THEN) that can be applied * Add customs declaration statement * Use box * Decrease item value by % * Insure shipment value by * Insure shipment value by % * Set customs general notes * Set customer email * Set Item HS Code * Set item name * Set Item Origin Country * Set item value * Set item weight * Set number of parcels * Phone number * Ship with address * Ship with * Set weight * Use shipping contract # Create a shipment with rules and/or defaults and announce it synchronously Source: https://sendcloud.dev/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously /.openapi/v3/shipments/openapi.yaml post /shipments/announce-with-shipping-rules Create and announce a shipment applying shipping rules and/or defaults The main advantage of this endpoint over the [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) endpoint (and also the difference between them) is the ability to apply [shipping rules](https://app.sendcloud.com/v2/shipping/rules) and [shipping defaults](https://app.sendcloud.com/v2/shipping/shipping-defaults) to a shipment. Because of this, more fields in this endpoint are optional. If no shipping rules or defaults are configured to automatically assign the fields listed below, those fields must be provided to create a shipment successfully: * `from_address` (from Ship with address) * `ship_with` (from Ship with) * `parcels` (from Set number of parcels) **Note: the shipment (parcels) will be linked to the integration identified by the API credentials you supply as request authentication (`Basic ...`).** ## Shipping rules * **Due to the data (shipments) that we receive in this API, NOT all of the shipping rules (actions or conditions) can (and will) be applied.** * **Shipping rules do not fully apply to multicollo shipments. In such cases, the rule conditions for weight, parcel dimensions (height, length, width), total order value, item name, item quantity, item SKU and total parcel item value will not be matched. Additionally, the following actions will not be triggered:** * Using a box (Use box) * Setting the weight (Set weight) * Setting the number of parcels (Set number of parcels) * Insuring the shipment value (Insure shipment value by) * Insuring it by percentage (Insure shipment value by %) * Increasing item value by percentage (Decrease item value by %) * Setting item HS code (Set Item HS Code) * Setting item name (Set item name) * Setting item origin country (Set Item Origin Country) * Setting item value (Set item value) * Setting item weight (Set item weight) **Please consider these limitations when defining rules.** ### Shipping rules conditions (IF) that can be applied * Carrier * Checkout delivery method * Company name * Customer email * Integration * Item SKU * Item name * Item quantity * Parcel height (cm) * Parcel length (cm) * Parcel width (cm) * Phone number * Postal code * To country * Total order value * Total parcel item value * Weight (kg) ## Shipping rules actions (THEN) that can be applied * Add customs declaration statement * Use box * Decrease item value by % * Insure shipment value by * Insure shipment value by % * Set customs general notes * Set customer email * Set Item HS Code * Set item name * Set Item Origin Country * Set item value * Set item weight * Set number of parcels * Phone number * Ship with address * Ship with * Set weight * Use shipping contract # Create and announce a shipment asynchronously Source: https://sendcloud.dev/api/v3/shipments/create-and-announce-a-shipment-asynchronously /.openapi/v3/shipments/openapi.yaml post /shipments This endpoint **announces a shipment asynchronously** under your API credentials. ## International shipments If you want to create a shipment to be sent to a destination country outside the EU, it's mandatory to include additional information related to the shipment contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping option selected. After the shipping label and associated documents are generated, you can retrieve and download them via the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint. Note that when passing along prices, mixed currencies are not accepted. Therefore, ensure that all price fields use the same currency. ## Multicollo Learn more about multicollo in our [Multicollo guide](/docs/shipping/multicollo). # Create and announce a shipment synchronously Source: https://sendcloud.dev/api/v3/shipments/create-and-announce-a-shipment-synchronously /.openapi/v3/shipments/openapi.yaml post /shipments/announce This endpoint **announces a shipment synchronously** under your API credentials. ## International shipments If you want to create a shipment to be sent to a destination country outside the EU, it's mandatory to include additional information related to the shipment contents. This allows Sendcloud to automatically generate the required customs documentation based on the international shipping option selected. After the shipping label and associated documents are generated, you can retrieve and download them via the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint. Note that when passing along prices, mixed currencies are not accepted. Therefore, ensure that all price fields use the same currency. # Shipments API overview Source: https://sendcloud.dev/api/v3/shipments/index The core of the Sendcloud Shipments API are the Shipment and Parcels resources. Shipments contain parcels, which are data objects that can be announced, and have a shipping label assigned to them. The Shipments API v3 only supports the creation of outgoing shipments. For incoming shipments, please use the [Returns API v3](/api/v3/returns). ## Multicollo shipments For shipments that need to be announced with more than one parcel (also called multicollo), please refer to the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint. ## International shipments International shipments require more information than domestic ones. Certain customs documents must be created when shipping to countries outside the EU. For Sendcloud to successfully generate these documents, all the necessary information must be available in your shipment request. For more in-depth information on international shipping and the requirements, please check our [guide to international shipping](/docs/shipping/international-shipping/). # Retrieve a return portal URL Source: https://sendcloud.dev/api/v3/shipments/retrieve-a-return-portal-url /.openapi/v3/shipments/openapi.yaml get /shipments/{id}/return-portal-url Retrieve a return portal link for a specific shipment using the shipment's id. The URL which is retrieved will link directly to the shipment in the Sendcloud Return portal, so a **return parcel** can be created immediately based on the outgoing shipment. If no Return portal is configured, or if no brand is connected to the shipment, this endpoint will return an error response with a 404 status code. # Retrieve a shipment Source: https://sendcloud.dev/api/v3/shipments/retrieve-a-shipment /.openapi/v3/shipments/openapi.yaml get /shipments/{id} This endpoint allows you to retrieve a specific shipment created under your Sendcloud credentials, based on the shipment `id`. # Retrieve shipments Source: https://sendcloud.dev/api/v3/shipments/retrieve-shipments /.openapi/v3/shipments/openapi.yaml get /shipments This endpoint allows you to retrieve a list of all the shipments which you have created or imported into your Sendcloud account under your API credentials. You can filter the results based on several query parameters. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. # Create a list of shipping options Source: https://sendcloud.dev/api/v3/shipping-options/create-a-list-of-shipping-options /.openapi/v3/shipping-options/openapi.yaml post /fetch-shipping-options Allows you to retrieve available shipping options along with their corresponding prices, referred to as shipping quotes. This endpoint is deprecated as of Wed, 14 Jan 2026 00:00:00 GMT. We recommend using the [Return a list of available shipping options](/api/v3/shipping-options/return-a-list-of-available-shipping-options) endpoint instead. A shipping option is a shipping product that the carrier offers in combination with a unique set of shipping functionalities. The quotes serve to indicate the cost of this shipping option. You must have either [enabled a carrier](/docs/getting-started/) in your Sendcloud account, or connected your own direct [carrier contract](/docs/getting-started/carrier-contracts/), in order to be able to retrieve shipping options related to that carrier via this endpoint. When shipping to a remote area, it's possible that a remote surcharge will be invoiced. Make sure to provide the `from_country_code`, `to_country_code` and `to_postal_code` to see remote surcharges in the price breakdown. Similarly, to access **zonal prices**, provide `from_country_code`, `to_country_code`, `from_postal_code`, and `to_postal_code`. This information ensures accurate and customized pricing based on the specific location, enabling you to understand any additional charges associated with remote areas and access pricing based on their designated zones. # Return a list of available shipping options Source: https://sendcloud.dev/api/v3/shipping-options/return-a-list-of-available-shipping-options /.openapi/v3/shipping-options/openapi.yaml post /shipping-options Retrieve available shipping options along with their corresponding prices for entire shipments, supporting multicollo as well. Unlike the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint, this endpoint accepts multiple parcels with individual dimensions and weights, and returns total pricing for the entire shipment. You must have either [enabled a carrier](/docs/getting-started/) in your Sendcloud account, or connected your own direct [carrier contract](/docs/getting-started/carrier-contracts/), to retrieve shipping options for that carrier. Use `from_address` and `to_address` objects to specify origin and destination. The more address details you provide (e.g. `postal_code`, `city`, `address_line_1`, `state_province_code`), the more accurate the pricing — including zonal prices and remote area surcharges. The legacy flat fields (`from_country_code`, `from_postal_code`, `to_country_code`, `to_postal_code`) are still supported but deprecated. The two approaches are **mutually exclusive**. For the most accurate pricing, use `from_address` and `to_address` with as many fields filled in as possible. When no origin or destination is provided, shipping options are returned without quotes regardless of `calculate_quotes`. # Create a shipping rule Source: https://sendcloud.dev/api/v3/shipping-rules/create-a-shipping-rule /.openapi/v3/shipping-rules/openapi.yaml post /shipping-rules/rules Create a shipping rule that applies its actions to a shipment whenever the shipment matches its conditions. # Delete a shipping rule Source: https://sendcloud.dev/api/v3/shipping-rules/delete-a-shipping-rule /.openapi/v3/shipping-rules/openapi.yaml delete /shipping-rules/rules/{rule_id} Delete a shipping rule by its unique ID. The rule stops being applied to new shipments immediately. # Shipping Rules API overview Source: https://sendcloud.dev/api/v3/shipping-rules/index Shipping rules let you automate how shipments are handled. A rule applies one or more actions to a shipment whenever the shipment matches its conditions, so you can set shipping methods, add insurance, or update other properties without manual work. ## Endpoints ### Managing rules * [Retrieve a list of shipping rules](/api/v3/shipping-rules/retrieve-a-list-of-shipping-rules) — list all rules for your account in evaluation order, including their conditions and actions. * [Create a shipping rule](/api/v3/shipping-rules/create-a-shipping-rule) — create a new rule with conditions and actions. * [Retrieve a shipping rule](/api/v3/shipping-rules/retrieve-a-shipping-rule) — get a single rule by its ID. * [Update a shipping rule](/api/v3/shipping-rules/update-a-shipping-rule) — update the name, status, conditions, or actions of a rule. * [Delete a shipping rule](/api/v3/shipping-rules/delete-a-shipping-rule) — remove a rule permanently. * [Reorder your shipping rules](/api/v3/shipping-rules/reorder-your-shipping-rules) — change the order in which rules are evaluated. ### Possibilities Use these endpoints to discover the valid values for building rule conditions and actions. * [Retrieve a list of available actions](/api/v3/shipping-rules/retrieve-a-list-of-available-actions) — list all actions without their accepted values. * [Retrieve an action](/api/v3/shipping-rules/retrieve-an-action) — get a single action including the full list of accepted values. * [Retrieve a list of available conditions](/api/v3/shipping-rules/retrieve-a-list-of-available-conditions) — list all condition properties and operators without their accepted values. * [Retrieve a condition property](/api/v3/shipping-rules/retrieve-a-condition-property) — get a single condition property including the full list of accepted values. * [Retrieve a list of available operators](/api/v3/shipping-rules/retrieve-a-list-of-available-operators) — list all operators. ## How rules work Rules are evaluated in order, from first to last. When a shipment matches a rule's conditions, its actions are applied. Multiple rules can match the same shipment — all matching rules are applied in order. Use [Reorder your shipping rules](/api/v3/shipping-rules/reorder-your-shipping-rules) to control evaluation order. ### Development status The Shipping Rules v3 API is currently in [beta](https://support.sendcloud.com/hc/en-us/articles/4417167140756-What-is-beta-), meaning that it is still under development. During this phase, we continually monitor and test the API to improve its performance, review the requested and the returned data, and uncover any potential bugs that could have a future impact on our users. Please note that there is a possibility of experiencing breaking changes while the API is still in beta. # Reorder your shipping rules Source: https://sendcloud.dev/api/v3/shipping-rules/reorder-your-shipping-rules /.openapi/v3/shipping-rules/openapi.yaml post /shipping-rules/rules/reorder Change the order in which your shipping rules are evaluated. Rules are applied from first to last. # Retrieve a condition property Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-a-condition-property /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/conditions/{identifier} Retrieve a single condition property, including the full list of values it accepts, by its identifier. # Retrieve a list of available actions Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-a-list-of-available-actions /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/actions Retrieve the actions you can apply in a shipping rule. The accepted values for each action are omitted. # Retrieve a list of available conditions Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-a-list-of-available-conditions /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/conditions Retrieve the properties and operators you can combine to build shipping rule conditions. The accepted values for each property are omitted. # Retrieve a list of available operators Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-a-list-of-available-operators /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/operators Retrieve the operators you can use to compare a property to a value when building a rule condition. # Retrieve a list of shipping rules Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-a-list-of-shipping-rules /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/rules Retrieve the shipping rules configured for your account, in the order they are evaluated. This endpoint uses cursor-based pagination via `Link` headers. See [Pagination](/api/v3/pagination) for details. # Retrieve a shipping rule Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-a-shipping-rule /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/rules/{rule_id} Retrieve a single shipping rule, including its conditions and actions, by its unique ID. # Retrieve an action Source: https://sendcloud.dev/api/v3/shipping-rules/retrieve-an-action /.openapi/v3/shipping-rules/openapi.yaml get /shipping-rules/actions/{identifier} Retrieve a single action, including the full list of values it accepts, by its identifier. # Update a shipping rule Source: https://sendcloud.dev/api/v3/shipping-rules/update-a-shipping-rule /.openapi/v3/shipping-rules/openapi.yaml patch /shipping-rules/rules/{rule_id} Update the name, status, conditions, or actions of an existing shipping rule. # Create a ticket for a damaged parcel Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-a-damaged-parcel /.openapi/v3/support/openapi.yaml post /dsf/tickets/damage Create a ticket for a damaged parcel. It works with both your own contract and parcels created using Sendcloud rates. # Create a ticket for a delayed parcel Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-a-delayed-parcel /.openapi/v3/support/openapi.yaml post /dsf/tickets/delay Create a ticket for a delayed parcel. This support type is only available for parcels created using Sendcloud rates. # Create a ticket for a delivered but not received parcel Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-a-delivered-but-not-received-parcel /.openapi/v3/support/openapi.yaml post /dsf/tickets/delivered-but-not-received Create a ticket for a delivered but not received parcel. It works with both your own contract and parcels created using Sendcloud rates. # Create a ticket for a late delivery Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-a-late-delivery /.openapi/v3/support/openapi.yaml post /dsf/tickets/late-delivery Create a ticket for a late delivery. This support type is only available for parcels sent under your own carrier contract. # Create a ticket for a lost parcel Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-a-lost-parcel /.openapi/v3/support/openapi.yaml post /dsf/tickets/lost Create a ticket for a lost parcel. It works with both your own contract and parcels created using Sendcloud rates. # Create a ticket for an address change Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-an-address-change /.openapi/v3/support/openapi.yaml post /dsf/tickets/address-change Create a ticket for an address change. It works with both your own contract and parcels created using Sendcloud rates. # Create a ticket for an unjustly returned parcel Source: https://sendcloud.dev/api/v3/support/create-a-ticket-for-an-unjustly-returned-parcel /.openapi/v3/support/openapi.yaml post /dsf/tickets/unjust-return Create a ticket for an unjustly returned parcel. It works with both your own contract and parcels created using Sendcloud rates. # Create carrier support contact Source: https://sendcloud.dev/api/v3/support/create-carrier-support-contact /.openapi/v3/support/openapi.yaml post /dsf/carrier-support-contacts A carrier support contact is required in order to create tickets for shipments sent under your own carrier contract so that we can forward the claim correctly. Note that ticket creation will fail if a carrier support contact is missing for a carrier you use with your own contract. # Delete a carrier support contact Source: https://sendcloud.dev/api/v3/support/delete-a-carrier-support-contact /.openapi/v3/support/openapi.yaml delete /dsf/carrier-support-contacts/{id} A carrier support contact is required in order to create tickets for shipments sent under your own carrier contract so that we can forward the claim correctly. Ticket creation will fail if a carrier support contact is missing for a carrier you use with your own contract. # Upload a file Source: https://sendcloud.dev/api/v3/support/files /.openapi/v3/support/openapi.yaml post /dsf/files API for uploading a file. The uploaded file is stored in the system, and a unique file token is returned in response. Use this token when attaching files to tickets or when submitting requested data. The request must be `multipart/form-data` with a single part named `file`. That part has to be a real **file part**: its `Content-Disposition` must include a `filename`, and it must carry a per-part `Content-Type` that is in the allowed list below. Most server-side HTTP clients (Python `requests`, PHP Guzzle, `fetch`, axios, OkHttp, ...) do **not** set a `filename` or a per-part `Content-Type` automatically — unlike the `curl --form file=@...` shorthand, which sets both for you. If the `file` part is sent without a `filename`, the server treats it as a plain text field and responds with `422` ("`file` field must contain a file object."). Make sure your client sets both explicitly on the `file` part. **Limits and allowed types** * **Maximum file size:** 6 MB. Larger uploads are rejected with `413 Content Too Large`. * **Allowed content types:** `image/*`, `video/*`, `text/*`, `application/pdf`, `application/rtf`, `application/msword`, `application/vnd.openxmlformats-officedocument.*` (`.docx`, `.xlsx`, `.pptx`), `application/vnd.ms-*`, `application/vnd.oasis.opendocument.*` (`.odt`, `.ods`, `.odp`), `application/xml`, `application/yaml`, `application/json`. A part whose `Content-Type` is not in this list is rejected with `415 Unsupported Media Type`. Generic types such as `application/octet-stream` and `application/zip` are **not** accepted, so make sure your client sends an accurate per-part `Content-Type`. **Which error means what** * `400` ("`file` field is required.") — there is no part named `file` in the request at all. * `422` ("`file` field must contain a file object.") — a part named `file` is present, but it was sent without a `filename`, so it is not recognized as a file. # Create a claim letter Source: https://sendcloud.dev/api/v3/support/generate-claim-letter /.openapi/v3/support/openapi.yaml post /dsf/documents/generate/claim-letter Generate a claim letter PDF for a parcel. The claim letter is created based on the provided items, currency, tax rate, and ticket category, combined with parcel and sender details fetched from the system. Company details and addresses are auto-populated from the parcel and sender information stored in the system. **Note:** Claim letters are currently generated in French only. The generated PDF returns a file token that can be used with the [Create a requested data response](/api/v3/support/provide-requested-data) endpoint or when creating tickets. # Create a sales invoice Source: https://sendcloud.dev/api/v3/support/generate-sales-invoice /.openapi/v3/support/openapi.yaml post /dsf/documents/generate/invoice Generate a sales invoice PDF for a parcel. The invoice is created based on the provided items, currency, and tax rate, combined with parcel and sender details fetched from the system. Company details and addresses are auto-populated from the parcel tracking information. # Support API overview Source: https://sendcloud.dev/api/v3/support/index The Sendcloud Support API lets you create support tickets easily and efficiently. This API can be used in conjunction with other core Sendcloud features or independently. ## Development status The Support API is currently in [beta](https://support.sendcloud.com/hc/en-us/articles/4417167140756-What-is-beta-), meaning that it is still under development. During this phase, we continually monitor and test the API to improve its performance, review the returned data, and uncover any potential bugs that could have a future impact on our users. If you want to opt-in and become a beta user for this API, note that there is a possibility of experiencing breaking changes while it is still in the development phase. For more information on how you can opt-in, please contact your Customer Success Manager. You can learn more about becoming a beta user and joining the Sendcloud Beta Community in our [help center](https://support.sendcloud.com/hc/en-us/articles/360060730371). ## What can you do with this API? ### File upload With the API, you can store files necessary for creating a ticket or for continuing an investigation when additional documents are requested. ### Carrier support contact management With the API, you can manage carrier support contacts that are necessary for creating tickets for parcels shipped under your own contract. ### Tickets creation You can use the API to create new tickets. Depending on the type of support requested and the parcel (either created with your own carrier contract or using Sendcloud rates), you may be asked to provide additional details. In general, the amount of information required to open a ticket for a parcel shipped under your own carrier contract is lower than for a parcel created with Sendcloud rates. However, we recommend providing as much information and as many documents as possible so that carriers can deliver the best support and resolve the ticket as quickly as possible. ### Retrieve and complete requested actions With the API, you can retrieve a list of additional information or documents required to resolve a ticket and submit the requested data. ## Rate limits To build a robust integration, rate limit rules must be respected. Endpoints with rate limits provide information through the following headers: * `x-ratelimit-limit`: the total number of allowed requests (e.g., 30) * `x-ratelimit-remaining`: the number of requests still available in the current time window (e.g., 25) * `x-ratelimit-reset`: the timestamp when the rate limit will be reset (e.g., 1758893152) # Create a requested data response Source: https://sendcloud.dev/api/v3/support/provide-requested-data /.openapi/v3/support/openapi.yaml post /dsf/tickets/requested-data Depending on the requested `data_type`, additional documents/photos, text input, or sales data may be required. For the `sales_data` type, detailed sales data is expected, including item descriptions, quantities, prices, and tax rates. The data has to be passed as a valid JSON object under the `sales_data` key of the payload. Each item can optionally include a `sales_date` to specify the date of the sale, which will be used as the invoice date. If not provided, the parcel announcement date will be used. A file object is expected for the following `data_type`'s: `sales_invoice`, `purchase_invoice`, `claim_letter`. Files are expected to be passed in the `attachments` array. # Retrieve a support ticket Source: https://sendcloud.dev/api/v3/support/retrieve-a-support-ticket /.openapi/v3/support/openapi.yaml get /dsf/tickets/{ticket_id} Retrieve a single support ticket by its ID. Returns 404 if the ticket does not exist or does not belong to your organization. # Retrieve carrier support contacts Source: https://sendcloud.dev/api/v3/support/retrieve-carrier-support-contacts /.openapi/v3/support/openapi.yaml get /dsf/carrier-support-contacts A carrier support contact is required in order to create tickets for shipments sent under your own carrier contract so that we can forward the claim correctly. Ticket creation will fail if a carrier support contact is missing for a carrier you use with your own contract. # Retrieve requested data for open tickets Source: https://sendcloud.dev/api/v3/support/retrieve-requested-data-for-open-tickets /.openapi/v3/support/openapi.yaml get /dsf/tickets/requested-data Retrieve the list of additional data requests for open tickets handled by Support Automation. # Retrieve support tickets Source: https://sendcloud.dev/api/v3/support/retrieve-support-tickets /.openapi/v3/support/openapi.yaml get /dsf/tickets Retrieve a paginated list of support tickets for your organization, with optional filters for status, carrier, parcel, tracking number, and date range. # Update a carrier support contact Source: https://sendcloud.dev/api/v3/support/update-a-carrier-support-contact /.openapi/v3/support/openapi.yaml patch /dsf/carrier-support-contacts/{id} A carrier support contact is required in order to create tickets for shipments sent under your own carrier contract so that we can forward the claim correctly. Ticket creation will fail if a carrier support contact is missing for a carrier you use with your own contract. # Retrieve metadata associated with the authentication method Source: https://sendcloud.dev/api/v3/user/retrieve-metadata-associated-with-the-authentication-method /.openapi/v3/user/openapi.yaml get /user/auth/metadata Retrieve information about the metadata associated with the authentication method used in the request # Webhooks overview Source: https://sendcloud.dev/api/v3/webhooks/index Sendcloud is able to actively communicate updates in a parcel (such as updates in the delivery status) to your application using webhooks. Webhooks are scoped to the integration they are configured on. You will only receive webhook events for parcels created via this integration only and actions that belong to that specific integration. If you have multiple integrations, each one needs its own webhook configuration. You should specify an endpoint to which Sendcloud will make requests, whenever a webhook event occurs. You can set this using the `webhook_url` field in your integration settings in Sendcloud. To verify a request is coming from Sendcloud, Sendcloud signs each request that we send to your endpoint using a HMAC signature (Hash-based Message Authentication Code) with SHA256 algorithm and the `Secret Key` or the `Webhook Signature Key` as secret, depending on your integration type. For your store to validate that the webhook is coming from us, you should hash the message received from us using your secret and compare against the `Sendcloud-Signature` header received from us. ```php PHP example icon=php theme={null} '1eed4b3d41f4653ac64fd56f1bf1cbfd349e4482cbc11dff7134bd93e5da4b0a' ``` To receive the parcel data for every update that happens in a parcel, you need to: * Visit your Integration settings within the Sendcloud platform. * Enable the webhook feedback checkbox. * Set the webhook url to your application that will process the data received. \* You can also test if the webhook works by sending a test webhook to your application by clicking on “Test API Webhook” button. * Save the shop settings. Additional notes: * Please note that the data your application will receive is the same as the payload you would get when retrieving information about a specific parcel. * If for any reason the call to your webhook fails, Sendcloud will retry sending the update 10 times with an exponential delay. Starting with a 5 minute delay, and a maximum delay of 1 hour between retries. If after 10 tries, the call is still failing, Sendcloud will stop trying, and report the issue to your Failed Request logs. * Because your shop might be unreachable for some time, the webhook arrival order might be scattered (unordered) which is why each webhook includes a timestamp which can be used to identify which webhook is the later one. * For return parcels, you will receive webhook updates only if the outgoing shipment was created through the API Shop. # Integration connected Source: https://sendcloud.dev/api/v3/webhooks/integration-connected /.openapi/v3/webhooks/openapi.yaml webhook IntegrationConnected A request is sent to the defined webhook whenever the integration is created within our system. # Integration deleted Source: https://sendcloud.dev/api/v3/webhooks/integration-deleted /.openapi/v3/webhooks/openapi.yaml webhook IntegrationDeleted A request is sent to the defined webhook whenever the integration is deleted from our system. # Integration modified Source: https://sendcloud.dev/api/v3/webhooks/integration-modified /.openapi/v3/webhooks/openapi.yaml webhook IntegrationModified A request is sent to the defined webhook whenever the integration is updated. # Parcel status changed Source: https://sendcloud.dev/api/v3/webhooks/parcel-status-changed /.openapi/v3/webhooks/openapi.yaml webhook ParcelStatusChanged Happens whenever a parcel belonging to this integration shifts to a different status. Only parcels created through this specific integration will trigger this webhook. # Return created Source: https://sendcloud.dev/api/v3/webhooks/return-created /.openapi/v3/webhooks/openapi.yaml webhook ReturnCreated Happens whenever a return is created from a parcel matching the integration. # Address field limits Source: https://sendcloud.dev/docs/addresses/address-field-limits When creating parcels through our API, it is crucial to ensure that the address information complies with the specific requirements of the selected carrier. Each carrier may impose different limitations on address fields, such as maximum character lengths, mandatory fields, and formatting rules. Adhering to these requirements is essential to prevent errors in shipping and ensure smooth processing of your parcels. This page provides detailed tables outlining the address field limitations and requirements for each carrier supported by our platform. Please review the information carefully to ensure your data meets the necessary criteria for successful parcel creation and delivery. Some carriers might have specific requirements depending on the destination country. This page does not include these additional requirements. ## Address field limits by carrier ### Amazon (`amazon`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 1 | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 60 | | `address_2` | - | - | 60 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 64 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | 1 | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 60 | | `from_address_2` | - | - | 60 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 64 | ### Asendia (`asendia`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 30 | | `company_name` | - | - | 30 | | `address` | ✅ Yes | 2 | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 9 | | `telephone` | ✅ Yes | - | 15 | | `email` | ✅ Yes | - | 50 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 30 | | `from_company_name` | - | - | 30 | | `from_address_1` | ✅ Yes | 2 | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 9 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | ✅ Yes | - | 50 | ### Verzenden via bol (`bol`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 1 | 35 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 64 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 1 | 34 | | `postal_code` | - | - | 8 | | `telephone` | - | - | - | | `email` | - | - | 254 | | `country` | ✅ Yes | 1 | 3 | | `from_name` | ✅ Yes | 1 | 35 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 64 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 1 | 34 | | `from_postal_code` | - | - | 8 | | `from_country` | ✅ Yes | 1 | 3 | | `from_email` | - | - | 254 | ### Bpost (`bpost`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 30 | | `company_name` | - | - | 30 | | `address` | ✅ Yes | - | 40 | | `address_2` | - | - | 75 | | `address_divided.house_number` | ✅ Yes | 1 | 8 | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 30 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 40 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 8 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Bring (`bring`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 35 | | `telephone` | - | - | - | | `email` | - | - | 60 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 35 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 60 | ### BRT (`brt`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 35 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 9 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 9 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Budbee (`budbee`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 255 | | `company_name` | - | - | 255 | | `address` | ✅ Yes | - | 255 | | `address_2` | - | - | 255 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 255 | | `postal_code` | - | - | 255 | | `telephone` | ✅ Yes | - | 255 | | `email` | - | - | 255 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 255 | | `from_company_name` | - | - | 255 | | `from_address_1` | ✅ Yes | - | 255 | | `from_address_2` | - | - | 255 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 255 | | `from_postal_code` | - | - | 255 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 255 | ### Cainiao (`cainiao`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 64 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 128 | | `address_2` | - | - | 128 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 128 | | `postal_code` | - | - | 12 | | `telephone` | ✅ Yes | - | 32 | | `email` | ✅ Yes | - | 128 | | `country` | ✅ Yes | - | 64 | | `from_name` | ✅ Yes | - | 64 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 128 | | `from_address_2` | - | - | 128 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 128 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 64 | | `from_email` | ✅ Yes | - | 128 | ### Celeritas (`celeritas`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Chronopost (`chronopost`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 38 | | `address_2` | - | - | 38 | | `address_divided.house_number` | - | - | 8 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 9 | | `telephone` | - | - | - | | `email` | - | - | 80 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 38 | | `from_address_2` | - | - | 38 | | `from_house_number` | - | - | 8 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 9 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 80 | ### CIRRO E-Commerce/GOFO (`cirro`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 55 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 55 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Colis Privé (`colisprive`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 32 | | `company_name` | - | - | 32 | | `address` | ✅ Yes | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 25 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 14 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 32 | | `from_company_name` | - | - | 32 | | `from_address_1` | ✅ Yes | - | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 25 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### Colissimo (`colissimo`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 70 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 70 | | `from_address_2` | - | - | 70 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Colissimo EC2C (`colissimo_ec2c`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | 2 | 60 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 20 | | `email` | - | 5 | 80 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | 2 | 60 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | 5 | 80 | ### Correos (`correos`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 24 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 24 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 9 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Correos Express (`correos_express`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 40 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 15 | | `telephone` | ✅ Yes | - | 15 | | `email` | - | - | 75 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 40 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 15 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 75 | ### CTS GROUP (`cts_group`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### CTT Express (`ctt_express`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 60 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | ✅ Yes | - | 15 | | `email` | ✅ Yes | - | 70 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 60 | | `from_address_2` | - | - | 60 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 70 | ### Dachser (`dachser`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### DB Schenker (`dbschenker`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 500 | | `company_name` | - | - | 500 | | `address` | ✅ Yes | 2 | 1000 | | `address_2` | - | - | 1000 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 500 | | `postal_code` | - | - | 20 | | `telephone` | - | - | 250 | | `email` | - | - | 250 | | `country` | ✅ Yes | - | 10 | | `from_name` | ✅ Yes | - | 500 | | `from_company_name` | - | - | 500 | | `from_address_1` | ✅ Yes | 2 | 1000 | | `from_address_2` | - | - | 1000 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 500 | | `from_postal_code` | - | - | 20 | | `from_country` | ✅ Yes | - | 10 | | `from_email` | - | - | 250 | ### Delivengo (`delivengo`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 38 | | `company_name` | - | - | 38 | | `address` | ✅ Yes | - | 38 | | `address_2` | - | - | 38 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 25 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 18 | | `email` | ✅ Yes | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 38 | | `from_company_name` | - | - | 38 | | `from_address_1` | ✅ Yes | - | 38 | | `from_address_2` | - | - | 38 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 25 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### Der Kurier (`der_kurier`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | - | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | 10 | | `city` | ✅ Yes | - | 50 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | 10 | | `from_city` | ✅ Yes | - | 50 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### DHL eCommerce Benelux (`dhl`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | - | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 15 | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 35 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 55 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### DHL 2-Man-Handling (`dhl_2_man_handling`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 255 | | `company_name` | - | - | 255 | | `address` | ✅ Yes | - | 255 | | `address_2` | - | - | 255 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 255 | | `postal_code` | ✅ Yes | - | 255 | | `telephone` | - | - | 255 | | `email` | - | - | 255 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 255 | | `from_company_name` | - | - | 255 | | `from_address_1` | ✅ Yes | - | 255 | | `from_address_2` | - | - | 255 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 255 | | `from_postal_code` | ✅ Yes | - | 255 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 255 | ### DHL Germany (`dhl_de`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 40 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | 10 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 70 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | 1 | 35 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | 10 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 70 | ### DHL eCommerce / Cross-border (`dhl_ecommerce`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 35 | | `postal_code` | ✅ Yes | - | 17 | | `telephone` | - | - | 35 | | `email` | - | - | 70 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | ✅ Yes | - | 17 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### DHL Express (`dhl_express`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 45 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | ✅ Yes | - | 20 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 45 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### DHL Freight (`dhl_freight`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 70 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 40 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 1 | 40 | | `postal_code` | ✅ Yes | 1 | 12 | | `telephone` | - | - | 64 | | `email` | - | - | 64 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 70 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 40 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 1 | 40 | | `from_postal_code` | ✅ Yes | 1 | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 64 | ### DHL Parcel UK (`dhl_gb`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | ✅ Yes | - | 20 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | - | - | 40 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 20 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### DHL eCommerce UK (`dhl_parcel_gb`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 1 | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | 1 | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 1 | 35 | | `postal_code` | - | 3 | 15 | | `telephone` | ✅ Yes | - | 35 | | `email` | ✅ Yes | 1 | 60 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | 1 | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | 1 | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 1 | 35 | | `from_postal_code` | - | 3 | 15 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | ✅ Yes | 1 | 60 | ### DHL Parcel Iberia (`dhl_parcel_iberia`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 30 | | `address` | ✅ Yes | - | 80 | | `address_2` | - | - | 80 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | - | | `postal_code` | ✅ Yes | - | 9 | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 40 | | `from_address_2` | - | - | - | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | - | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### DHL Sweden (`dhl_se`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 1 | 35 | | `postal_code` | ✅ Yes | 1 | 9 | | `telephone` | - | - | 64 | | `email` | - | - | 64 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 1 | 35 | | `from_postal_code` | ✅ Yes | 1 | 9 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 64 | ### DHL Unified (`dhl_unified`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Deutsche Post (`dp`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 30 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 40 | | `address_2` | - | - | 40 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | 3 | 10 | | `telephone` | - | - | 25 | | `email` | - | - | 50 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | - | - | 40 | | `from_company_name` | - | - | 40 | | `from_address_1` | ✅ Yes | - | 40 | | `from_address_2` | - | - | 40 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 40 | | `from_postal_code` | ✅ Yes | - | 20 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 50 | ### DPD (`dpd`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 50 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | 8 | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 50 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 8 | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### DPD Austria (`dpd_at`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | - | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | - | | `from_email` | - | - | 100 | ### DPD France (`dpd_fr`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 105 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 3 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 105 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 3 | | `from_email` | - | - | 254 | ### DPD UK (`dpd_gb`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | - | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | - | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 50 | ### DPD Local (`dpd_local`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | - | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | - | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 50 | ### DPD Portugal (`dpd_pt`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 1 | 32 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 64 | | `address_2` | - | - | 64 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 1 | 26 | | `postal_code` | ✅ Yes | 1 | 8 | | `telephone` | ✅ Yes | 1 | 20 | | `email` | ✅ Yes | 1 | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | 1 | 32 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 64 | | `from_address_2` | - | - | 64 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 1 | 26 | | `from_postal_code` | ✅ Yes | 1 | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | 1 | 50 | ### DX Express (`dx`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 40 | | `address` | ✅ Yes | 2 | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 8 | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 40 | | `from_address_1` | ✅ Yes | 2 | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Dynalogic (`dynalogic`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 55 | | `address_2` | - | - | 75 | | `address_divided.house_number` | ✅ Yes | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | - | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 55 | | `from_address_2` | - | - | 75 | | `from_house_number` | ✅ Yes | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | - | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Europaket (`europaket`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 64 | | `company_name` | - | - | 64 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 64 | | `address_divided.house_number` | - | - | 16 | | `city` | ✅ Yes | - | 64 | | `postal_code` | ✅ Yes | - | 16 | | `telephone` | - | - | 32 | | `email` | - | - | 256 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 64 | | `from_company_name` | - | - | 64 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 64 | | `from_house_number` | - | - | 16 | | `from_city` | ✅ Yes | - | 64 | | `from_postal_code` | ✅ Yes | - | 16 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 256 | ### EVRi International (`evri_international`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 15 | | `telephone` | - | - | 20 | | `email` | ✅ Yes | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | - | - | 40 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 15 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 100 | ### Fairsenden (`fairsenden`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | 4 | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 120 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | ✅ Yes | - | 50 | | `from_address_1` | ✅ Yes | - | 60 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | 4 | 10 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 120 | ### FedEx (`fedex`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | - | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 50 | | `postal_code` | - | - | 10 | | `telephone` | ✅ Yes | - | 15 | | `email` | - | - | 254 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | - | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 50 | | `from_postal_code` | - | - | 10 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 254 | ### FedEx Crossborder (`fedexcrossborder`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 70 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 15 | | `telephone` | - | - | 20 | | `email` | ✅ Yes | - | 40 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 70 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 15 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 40 | ### Cycloon (`fietskoeriers`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 100 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | - | 100 | | `postal_code` | - | - | 20 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 100 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 100 | | `from_postal_code` | - | - | 20 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### Finmile (`finmile`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | - | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | - | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | - | | `telephone` | - | - | - | | `email` | - | - | - | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | - | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | - | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | - | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | - | ### Geodis (`geodis`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 70 | | `company_name` | - | - | 70 | | `address` | ✅ Yes | - | 70 | | `address_2` | - | - | 70 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | - | 70 | | `postal_code` | ✅ Yes | - | 20 | | `telephone` | ✅ Yes | - | 25 | | `email` | - | - | 155 | | `country` | ✅ Yes | - | - | | `from_name` | ✅ Yes | - | 70 | | `from_company_name` | - | - | 70 | | `from_address_1` | ✅ Yes | - | 70 | | `from_address_2` | - | - | 70 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 70 | | `from_postal_code` | ✅ Yes | - | 20 | | `from_country` | ✅ Yes | - | - | | `from_email` | - | - | 155 | ### Glovo (`glovo`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### GLS DE/AT/FR/BE (`gls_de`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 40 | | `address` | ✅ Yes | - | 40 | | `address_2` | - | - | 40 | | `address_divided.house_number` | - | - | 10 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 40 | | `from_address_1` | ✅ Yes | - | 40 | | `from_address_2` | - | - | 40 | | `from_house_number` | - | - | 10 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### GLS Spain (`gls_es`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 3 | 80 | | `company_name` | - | - | 80 | | `address` | ✅ Yes | 3 | 50 | | `address_2` | - | - | 29 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 3 | 80 | | `postal_code` | ✅ Yes | 4 | 30 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 254 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | 3 | 80 | | `from_company_name` | - | - | 80 | | `from_address_1` | ✅ Yes | 3 | 50 | | `from_address_2` | - | - | 29 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 3 | 80 | | `from_postal_code` | ✅ Yes | 4 | 30 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | ✅ Yes | - | 254 | ### GLS (`gls_eu`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 1 | 40 | | `company_name` | - | - | 40 | | `address` | ✅ Yes | 3 | 40 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 40 | | `city` | ✅ Yes | 1 | 40 | | `postal_code` | - | 1 | 10 | | `telephone` | - | - | 40 | | `email` | - | - | 80 | | `country` | ✅ Yes | 1 | 2 | | `from_name` | ✅ Yes | 1 | 40 | | `from_company_name` | - | - | 40 | | `from_address_1` | ✅ Yes | 3 | 40 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 40 | | `from_city` | ✅ Yes | 1 | 40 | | `from_postal_code` | - | 1 | 10 | | `from_country` | ✅ Yes | 1 | 2 | | `from_email` | - | - | 80 | ### GLS Italy (`gls_it`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 30 | | `company_name` | - | - | 30 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 100 | | `from_company_name` | - | - | 100 | | `from_address_1` | ✅ Yes | - | 100 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 100 | | `from_postal_code` | ✅ Yes | - | 20 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### GLS Netherlands (`gls_nl`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | 1 | 60 | | `company_name` | - | - | 30 | | `address` | ✅ Yes | 1 | 40 | | `address_2` | - | - | 30 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | 1 | 30 | | `postal_code` | ✅ Yes | 1 | 8 | | `telephone` | - | - | 25 | | `email` | - | - | 320 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | 1 | 60 | | `from_company_name` | - | - | 30 | | `from_address_1` | ✅ Yes | 1 | 40 | | `from_address_2` | - | - | 30 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | 1 | 30 | | `from_postal_code` | ✅ Yes | 1 | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 320 | ### Hermes Austria (`hermes_at`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | - | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | - | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | - | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### EVRi Dropoff (`hermes_c2c_gb`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 32 | | `address` | ✅ Yes | 1 | 32 | | `address_2` | - | - | 96 | | `address_divided.house_number` | ✅ Yes | - | 10 | | `city` | ✅ Yes | - | 32 | | `postal_code` | - | - | 10 | | `telephone` | - | - | 15 | | `email` | - | - | 80 | | `country` | - | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 32 | | `from_address_1` | ✅ Yes | 1 | 50 | | `from_address_2` | - | - | 96 | | `from_house_number` | ✅ Yes | - | 10 | | `from_city` | ✅ Yes | - | 32 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | - | - | 2 | | `from_email` | - | - | 80 | ### Hermes Germany (`hermes_de`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 5 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 20 | | `email` | - | - | 200 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 5 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 200 | ### EVRi (`hermes_gb`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 32 | | `address` | ✅ Yes | 1 | 32 | | `address_2` | - | - | 96 | | `address_divided.house_number` | ✅ Yes | - | 10 | | `city` | ✅ Yes | - | 32 | | `postal_code` | - | - | 10 | | `telephone` | - | - | 15 | | `email` | - | - | 80 | | `country` | - | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 32 | | `from_address_1` | ✅ Yes | 1 | 50 | | `from_address_2` | - | - | 96 | | `from_house_number` | ✅ Yes | - | 10 | | `from_city` | ✅ Yes | - | 32 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | - | - | 2 | | `from_email` | - | - | 80 | ### HIVED (`hived`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 100 | | `company_name` | - | - | 60 | | `address` | ✅ Yes | - | 100 | | `address_2` | - | - | 100 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 60 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 24 | | `email` | - | - | 60 | | `country` | - | - | - | | `from_name` | - | - | 40 | | `from_company_name` | - | - | 40 | | `from_address_1` | - | - | 40 | | `from_address_2` | - | - | 40 | | `from_house_number` | - | - | - | | `from_city` | - | - | 40 | | `from_postal_code` | - | - | 8 | | `from_country` | - | - | - | | `from_email` | - | - | - | ### Homerr (`homerr`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 255 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 255 | | `address_2` | - | - | 255 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 255 | | `postal_code` | ✅ Yes | - | 255 | | `telephone` | ✅ Yes | - | 255 | | `email` | ✅ Yes | - | 255 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 255 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 255 | | `from_address_2` | - | - | 255 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 255 | | `from_postal_code` | ✅ Yes | - | 255 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 255 | ### Hurby (`hurby`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | - | - | 200 | | `company_name` | - | - | 200 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | - | - | 50 | | `postal_code` | ✅ Yes | - | 7 | | `telephone` | - | - | 15 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | - | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | - | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | - | - | 2 | | `from_email` | - | - | 254 | ### InPost Spain (`inpost_es`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 32 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 32 | | `address_2` | - | - | 32 | | `address_divided.house_number` | ✅ Yes | - | 8 | | `city` | ✅ Yes | - | 26 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | ✅ Yes | - | 70 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 32 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 32 | | `from_address_2` | - | - | 32 | | `from_house_number` | ✅ Yes | - | 8 | | `from_city` | ✅ Yes | - | 26 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 70 | ### InPost GB (`inpost_gb`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 200 | | `address` | ✅ Yes | 1 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | - | 100 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 200 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 200 | | `from_address_1` | ✅ Yes | 1 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 100 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 200 | ### InPost Global (`inpost_global`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 254 | ### Inpost Italy (`inpost_it`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 30 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 40 | | `address_2` | - | - | 75 | | `address_divided.house_number` | ✅ Yes | 1 | 8 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 30 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 40 | | `from_address_2` | - | - | 75 | | `from_house_number` | ✅ Yes | 1 | 8 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 50 | ### Inpost Poland (`inpost_pl`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 55 | | `address_2` | - | - | 75 | | `address_divided.house_number` | ✅ Yes | 1 | 20 | | `city` | ✅ Yes | 1 | 30 | | `postal_code` | - | - | 12 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 55 | | `from_address_2` | - | - | 75 | | `from_house_number` | ✅ Yes | 1 | 20 | | `from_city` | ✅ Yes | 1 | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 254 | ### Jan Krediet (`jan_krediet`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | - | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | - | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | - | | `telephone` | - | - | - | | `email` | - | - | - | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | - | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | - | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | - | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | - | ### Jongstra Transport (`jongstra`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 55 | | `address_2` | - | - | 75 | | `address_divided.house_number` | ✅ Yes | - | 15 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 55 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### LandMark Global (`landmark`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | - | - | 100 | | `address_2` | - | - | 100 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 50 | | `postal_code` | - | - | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 100 | | `from_address_2` | - | - | 100 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 50 | | `from_postal_code` | - | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### La Poste (`laposte`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Lettre Suivie (`lettresuivie`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 38 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 38 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Maersk (`maersk`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### MHI (`mhi`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 200 | | `company_name` | - | - | 200 | | `address` | ✅ Yes | - | 200 | | `address_2` | - | - | 200 | | `address_divided.house_number` | - | - | 200 | | `city` | ✅ Yes | - | 200 | | `postal_code` | ✅ Yes | - | 200 | | `telephone` | - | - | 20 | | `email` | - | - | 200 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 200 | | `from_company_name` | - | - | 200 | | `from_address_1` | ✅ Yes | - | 200 | | `from_address_2` | - | - | 200 | | `from_house_number` | - | - | 200 | | `from_city` | ✅ Yes | - | 200 | | `from_postal_code` | ✅ Yes | - | 200 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 200 | ### Mondial Relay (`mondial_relay`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 32 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 32 | | `address_2` | - | - | 32 | | `address_divided.house_number` | ✅ Yes | - | 8 | | `city` | ✅ Yes | - | 26 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | ✅ Yes | - | 70 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 32 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 32 | | `from_address_2` | - | - | 32 | | `from_house_number` | ✅ Yes | - | 8 | | `from_city` | ✅ Yes | - | 26 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 70 | ### MRW (`mrw`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | ✅ Yes | - | 20 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Nacex (`nacex`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 40 | | `postal_code` | ✅ Yes | - | 15 | | `telephone` | ✅ Yes | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | - | - | 35 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 60 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | - | - | 40 | | `from_postal_code` | - | - | 15 | | `from_country` | - | - | 2 | | `from_email` | - | - | 254 | ### Ontime (`ontime`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 60 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 60 | | `postal_code` | ✅ Yes | - | 60 | | `telephone` | - | - | 60 | | `email` | - | - | 60 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 60 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 60 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | - | - | 60 | | `from_postal_code` | ✅ Yes | - | 60 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Paack (`paack`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 2 | 30 | | `postal_code` | - | 3 | 12 | | `telephone` | - | 1 | 20 | | `email` | - | 6 | 128 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 2 | 30 | | `from_postal_code` | - | 3 | 12 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 254 | ### Packs (`packs`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | - | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | ✅ Yes | - | 10 | | `city` | ✅ Yes | - | 50 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 50 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | ✅ Yes | - | 10 | | `from_city` | ✅ Yes | - | 50 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Parcelforce (`parcelforce`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 30 | | `company_name` | - | - | 40 | | `address` | ✅ Yes | - | 40 | | `address_2` | - | - | 40 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 16 | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 25 | | `from_address_1` | ✅ Yes | - | 40 | | `from_address_2` | - | - | 40 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 25 | | `from_postal_code` | ✅ Yes | - | 16 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### PLX Parcel Logistics (`plx`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Austrian Post (`postat`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 45 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 45 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### Poste Italiane Delivery (`poste_it_delivery`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | 2 | 40 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | 10 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 9 | | `telephone` | - | - | 15 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | 2 | 40 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | 10 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 9 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### Poste Italiane Crono (`poste_italiane`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 60 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 15 | | `email` | - | - | 254 | | `country` | - | - | 3 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 60 | | `from_address_2` | - | - | 60 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | - | - | 3 | | `from_email` | - | - | 254 | ### PostNL (`postnl`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 95 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 35 | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 17 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 95 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 35 | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 17 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### PostNL Fulfilment (`postnl_fulfilment`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 95 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 35 | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 17 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 95 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 35 | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 17 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### PostNL Extra\@Home (`postnl_large`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 95 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 35 | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 17 | | `telephone` | - | - | 20 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 95 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 35 | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 17 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### PostNord (`postnord`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Quicargo (`quicargo`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 254 | ### Raben (`raben`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Relais Colis (`relais_colis`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 1 | 80 | | `address_2` | - | - | 80 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | 1 | 40 | | `postal_code` | ✅ Yes | 1 | 5 | | `telephone` | ✅ Yes | - | 20 | | `email` | ✅ Yes | - | 81 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 1 | 80 | | `from_address_2` | - | - | 80 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | 1 | 40 | | `from_postal_code` | ✅ Yes | 1 | 5 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 81 | ### Instabox (`rjpv2`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 100 | | `company_name` | - | - | 100 | | `address` | ✅ Yes | - | 254 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 100 | | `postal_code` | ✅ Yes | - | 7 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | - | - | 2 | | `from_name` | - | - | 100 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | - | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | - | - | 2 | | `from_email` | - | - | 254 | ### Royal Mail (`royal_mail`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | ✅ Yes | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 20 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 254 | ### Royal Mail by Sendcloud (`royal_mailv2`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### SEUR (`seur`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 70 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 10 | | `telephone` | - | - | 20 | | `email` | ✅ Yes | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 70 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 50 | ### SkyNet Worldwide Express (`skymail`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 40 | | `address` | ✅ Yes | - | 40 | | `address_2` | - | - | 40 | | `address_divided.house_number` | - | - | 25 | | `city` | ✅ Yes | - | 40 | | `postal_code` | ✅ Yes | 4 | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 3 | | `from_name` | - | - | 25 | | `from_company_name` | - | - | 50 | | `from_address_1` | - | - | 25 | | `from_address_2` | - | - | 25 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | - | - | 25 | | `from_email` | - | - | 254 | ### Spring (`spring`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 45 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 15 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 45 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Storeshippers (`storeshippers`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 120 | | `company_name` | - | - | 60 | | `address` | ✅ Yes | - | 255 | | `address_2` | - | - | 255 | | `address_divided.house_number` | - | - | - | | `city` | - | - | 255 | | `postal_code` | - | - | 100 | | `telephone` | - | - | 60 | | `email` | ✅ Yes | - | 255 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 120 | | `from_company_name` | - | - | 60 | | `from_address_1` | ✅ Yes | - | 255 | | `from_address_2` | - | - | 255 | | `from_house_number` | - | - | - | | `from_city` | - | - | 255 | | `from_postal_code` | - | - | 100 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 255 | ### Swiss Post (`swisspost`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | 35 | | `address_divided.house_number` | ✅ Yes | 1 | 10 | | `city` | ✅ Yes | - | 35 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 20 | | `email` | - | - | 160 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 25 | | `from_company_name` | - | - | 25 | | `from_address_1` | ✅ Yes | - | 25 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | 10 | | `from_city` | ✅ Yes | - | 25 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 160 | ### Test Carrier (`test_carrier`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Thijse (`thijse`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Tipsa (`tipsa`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 60 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 60 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 10 | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 8 | | `telephone` | - | - | 15 | | `email` | - | - | 100 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 60 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 60 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 10 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 100 | ### TNT Italy (`tnt_it`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 75 | | `address_2` | - | - | 30 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 9 | | `telephone` | - | - | 16 | | `email` | ✅ Yes | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 75 | | `from_address_2` | - | - | 30 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 9 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 50 | ### Transforce (`transforce`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 75 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 55 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 20 | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 75 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 55 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 20 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Transmission (`transmission`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 60 | | `company_name` | - | - | 60 | | `address` | ✅ Yes | - | 71 | | `address_2` | - | - | 75 | | `address_divided.house_number` | ✅ Yes | - | 10 | | `city` | ✅ Yes | - | 60 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | ✅ Yes | - | 15 | | `email` | ✅ Yes | - | 180 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 60 | | `from_company_name` | - | - | 60 | | `from_address_1` | ✅ Yes | - | 71 | | `from_address_2` | - | - | 75 | | `from_house_number` | ✅ Yes | - | 10 | | `from_city` | ✅ Yes | - | 60 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 180 | ### Trunkrs (`trunkrs`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 255 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 255 | | `address_2` | - | - | 255 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 255 | | `postal_code` | - | - | 255 | | `telephone` | - | - | 255 | | `email` | ✅ Yes | - | 255 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 255 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 255 | | `from_address_2` | - | - | 255 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 255 | | `from_postal_code` | - | - | 255 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | ✅ Yes | - | 255 | ### UPS (`ups`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 35 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 70 | | `address_2` | - | - | 35 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 10 | | `telephone` | - | - | 19 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 35 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 70 | | `from_address_2` | - | - | 35 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 10 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | ### USPS (`usps`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### Viatim (`viatim`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 100 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | - | 64 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | 6 | | `city` | ✅ Yes | - | 30 | | `postal_code` | - | - | 12 | | `telephone` | - | - | 15 | | `email` | - | - | 255 | | `country` | ✅ Yes | 2 | 2 | | `from_name` | ✅ Yes | - | 100 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | - | 64 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | 6 | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | - | - | 12 | | `from_country` | ✅ Yes | 2 | 2 | | `from_email` | - | - | 255 | ### WeGrow (`wegrow`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 75 | | `address_2` | - | - | 75 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | - | 12 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 75 | | `from_address_2` | - | - | 75 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | - | 12 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### XPO ES (`xpo_es`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 50 | | `company_name` | - | - | 50 | | `address` | ✅ Yes | 2 | 50 | | `address_2` | - | - | 50 | | `address_divided.house_number` | - | - | - | | `city` | ✅ Yes | - | 30 | | `postal_code` | ✅ Yes | 1 | 8 | | `telephone` | - | - | 20 | | `email` | - | - | 254 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 50 | | `from_company_name` | - | - | 50 | | `from_address_1` | ✅ Yes | 2 | 50 | | `from_address_2` | - | - | 50 | | `from_house_number` | - | - | - | | `from_city` | ✅ Yes | - | 30 | | `from_postal_code` | ✅ Yes | 1 | 8 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 254 | ### InPost to Home (`yodel`) | API field name | Required | Minimum length | Maximum length | | ------------------------------ | -------- | -------------- | -------------- | | `name` | ✅ Yes | - | 40 | | `company_name` | - | - | 35 | | `address` | ✅ Yes | - | 35 | | `address_2` | - | - | - | | `address_divided.house_number` | - | - | 35 | | `city` | ✅ Yes | - | 35 | | `postal_code` | - | - | 20 | | `telephone` | - | - | 19 | | `email` | - | - | 50 | | `country` | ✅ Yes | - | 2 | | `from_name` | ✅ Yes | - | 40 | | `from_company_name` | - | - | 35 | | `from_address_1` | ✅ Yes | - | 35 | | `from_address_2` | - | - | - | | `from_house_number` | - | - | 35 | | `from_city` | ✅ Yes | - | 35 | | `from_postal_code` | - | - | 20 | | `from_country` | ✅ Yes | - | 2 | | `from_email` | - | - | 50 | # Address validation Source: https://sendcloud.dev/docs/addresses/address-validation Incorrect shipping addresses are one of the most common causes of failed deliveries, expensive returns, and frustrated end consumers. Address validation lets you catch and correct address issues before a shipment is ever created, so shipments reach their destination the first time. Sendcloud can apply two layers of validation: | Layer | What it does | Example | | ---------------------- | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------ | | **Formatting check** | Ensures the address meets carrier requirements (e.g. field length limits, required postal code format) | Address line 1 is too long for PostNL → Sendcloud automatically moves overflow to address line 2 | | **Content validation** | Verifies the address actually exists in the real world using an external address provider | `"city": "Amstredan"` → automatically corrected to `"city": "Amsterdam"` | The **formatting check** is always applied at no extra cost when you use the [Validate an address](/api/v3/address/validate) endpoint, or when creating a shipment with the [Shipments API v3](/api/v3/shipments). **Content validation** is available as an add-on, or is included automatically depending on your contract type. See [Pricing](#pricing) for details. Address validation is available on the **Shipments API v3** only. It is not available in API v2. *** ## How it works There are three integration patterns depending on your use case. Choose the one that best fits your workflow. ### Option 1: Validate an address before creating a shipment **Best for:** WMS and ERP systems that want to verify address data before announcing a shipment to a carrier. In this flow, you call the validate endpoint first, inspect the result, correct any issues on your side, and only then create a shipment. Send the address to the [Validate an address](/api/v3/address/validate) endpoint. ```http Example request method and URL theme={null} POST /api/v3/addresses/validate ``` ```json Example request body theme={null} { "address": { "address_line_1": "Stadhuisplein", "house_number": "10", "postal_code": "5611 EM", "city": "Eindhoven", "country_code": "NL" }, "carrier_code": "postnl", "validation_methods": ["here"] } ``` ```json Example response theme={null} { "input_address_is_valid": true, "results": [ { "address": { "address_line_1": "Stadhuisplein", "house_number": "10", "postal_code": "5611 EM", "city": "Eindhoven", "country_code": "NL" }, "recommended": true, "analysis": { "validation_result": { "is_valid": true, "reasons": [] }, "changed_attributes": [], "invalid_attributes": [] } } ] } ``` **How to read the response** | Field | What it means | | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `input_address_is_valid` | Whether the submitted address passed validation. If this value is `false`, check the `reasons` array for details on the validation failure (for example: `POSTAL_CODE_MISSING`, `ADDRESS_NOT_VALID`). If this value is `null`, an upstream connection issue occurred and the service could not reach the third-party validation providers. | | `recommended: true` | This is the best address match found. Use this for your shipment. There will only ever be one recommended result, or none. | | `recommended: false` | An alternative result that passed some checks but was not the best match. Can generally be ignored. | | `changed_attributes` | Fields that were corrected from your input (e.g. `city`, `postal_code`). If empty and `recommended: true`, the original address was already correct. | | `invalid_attributes` | Fields that failed a field-level validation check (e.g. `postal_code`, `country_code`, `address_line_1`) and caused an otherwise-passing address to be marked invalid. Empty when no specific field could be pinpointed as the cause. | | `validation_result.is_valid` | Whether the address passed validation. | | `validation_result.reasons` | List of reasons the address failed (e.g. `ADDRESS_NOT_VALID`, `POSTAL_CODE_MISSING`). Empty if the address is valid. | An address can return `is_valid: true` but `recommended: false`. This means the address meets certain validation rules, but no confident real-world match was found. In this case, review the address manually before proceeding. If a `recommended: true` result is returned, use that corrected address for your shipment. Create the shipment via the [Shipments API](/api/v3/shipments) using the corrected address. ### Option 2: Validate an address at checkout to suggest a correct address to your consumers **Best for:** Individual sellers and platforms that want to guide end consumers into entering valid addresses during checkout. In this flow, you collect partial address input from the consumer (for example, house number and postal code for Dutch addresses), call the validation endpoint, and surface the corrected or confirmed address back to the consumer before they confirm their order. This approach ensures that by the time an order is placed, the address has already been verified, reducing failed deliveries before a single shipment is created. Collect the relevant address fields from the consumer in your checkout (e.g. postal code + house number for NL). Call the [Validate an address](/api/v3/address/validate) endpoint with the input. ```http Request method and URL theme={null} POST /api/v3/addresses/validate ``` ```json Example request body with NL postal code and house number lookup theme={null} { "address": { "house_number": "10", "postal_code": "5611 EM", "country_code": "NL" }, "carrier_code": "postnl", "validation_methods": ["here"] } ``` The response will include a fully resolved address (street name, city, etc.) that you can present to the consumer for confirmation. Display the `recommended: true` address to the consumer as a suggestion. Let the consumer confirm or adjust before finalising the order. ### Option 3: Inline address validation during shipment creation **Best for:** Small sellers or merchants who want the simplest possible integration with minimal extra effort. In this flow, you don't call the validation endpoint separately. Instead, you pass `"validation_methods": ["here"]` directly in your shipment creation request. Sendcloud will validate and, where possible, correct the address as part of the announcement. Create a shipment via the [Shipments API](/api/v3/shipments) and include `"validation_methods": ["here"]` in the request body. ```http Request method and URL theme={null} POST /api/v3/shipments/create-and-announce-synchronously ``` ```json Example request body theme={null} { "to_address": { "name": "Jane Doe", "address_line_1": "Stadhuisplein", "house_number": "10", "postal_code": "5611 EM", "city": "Einhoven", "country_code": "NL", "email": "jane.doe@example.com" }, "ship_with": { "type": "shipping_option_code", "properties": { "shipping_option_code": "postnl:standard", "contract_id": 517 } }, "parcels": [ { "weight": { "value": "1.2", "unit": "kg" } } ], "validation_methods": ["here"] } ``` If the address can be corrected (e.g. a misspelled city), Sendcloud will automatically apply the fix. In this example, `"city": "Einhoven"` would be automatically corrected to `"city": "Eindhoven"`. If no valid match can be found, the request returns an error, so you know to fix the address before retrying. **Important:** Inline validation only keeps address components it can confirm with the address provider. Any extra information added to address fields, such as `"address_line_2": "Ring the blue doorbell"`, will be removed if it does not match provider records. Use `parcels.label_notes` for delivery instructions and notes instead. ## Supported content validation methods | Method | Description | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `here` | Real-world address content validation using the [HERE](https://www.here.com/) address provider. Verifies that the address exists and corrects recognisable typos or errors. | The default Sendcloud formatting check (carrier field limits, postal code format, etc.) is **always applied** regardless of which `validation_methods` you include. *** ## Pricing The **formatting check** is included for all merchants at no additional cost. **Content validation** (the `here` method) is free when announcing shipments on any non-enterprise subscription plan or through the shipment announcement flow with a transactional contract. For merchants on an enterprise plan, content validation is available as a paid add-on — applicable both when using the standalone validation endpoint and when announcing shipments with a direct contract. For full pricing details, refer to the [Sendcloud pricing page](https://www.sendcloud.com/pricing/). *** ## Related resources * [Validate an address — API reference](/api/v3/address/validate) * [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) * [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) * [Address field limits](/docs/addresses/address-field-limits) * [Create a shipment](/docs/shipments/create-a-shipment) # Sender addresses Source: https://sendcloud.dev/docs/addresses/sender-addresses A sender address is required information when creating a shipping label. It specifies a **ship from** address to indicate where a parcel came from, and where it should be returned to in the event that something goes wrong. Sender addresses are configured in the [Sendcloud platform](https://app.sendcloud.com/v2/settings/addresses/sender), and can then be used to specify a **ship from** location, or a ship to location for returns, when you interact with our APIs. Sender addresses correlate with the type of methods that you can retrieve when you make an API call to [Get shipping rates](/docs/shipping/shipping-rates/) or [Choose a shipping method](/docs/shipping/shipping-methods/). ## Default sender addresses Sendcloud allows you to store multiple sender addresses in your account details, but one address must always be marked as **default**. * Whenever you [create a parcel](/docs/archive/shipping/create-a-parcel) without specifying a sender address `id`, your **default** address will be automatically used to create your label * In turn, the **brand** associated with your default sender address is the one that will be assigned to any parcels you create. ## Ship from a different sender address location If you have multiple sender addresses, you can specify a different sender address `id` to ship a parcel from a different location. You can retrieve the `id` for each of your sender addresses by making a `GET` request to the [Retrieve a list of sender addresses](/api/v2/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint. ### Retrieve your configured sender addresses Make a `GET` request to the [Retrieve a list of sender addresses](/api/v2/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint to retrieve all sender addresses configured for your account: ```sh Example request using curl theme={null} curl --request GET \ --url https://panel.sendcloud.sc/api/v2/user/addresses/sender \ --header 'Accept: application/json' \ --header 'Authorization: Basic ' ``` A successful response will return a JSON object containing an array of all sender addresses configured for your account, similar to the following example: ```json Response body theme={null} { "sender_addresses": [ { "id": 2, "company_name": "French Company", "contact_name": "Marie Doe", "email": "info@sendcloud.fr", "telephone": "", "street": "Rue Villiers de l'Isle Adam", "house_number": "33", "postal_box": "", "postal_code": "35000", "city": "Rennes", "country": "FR", "vat_number": "NL123456789B01", "coc_number": "NL12345678", "eori_number": "NL123456789", "brand_id": 1, }, { "id": 1, "company_name": "Sendcloud", "contact_name": "John Doe", "email": "johndoe@sendcloud.com", "telephone": "+31626262626", "street": "Bogert", "house_number": "115", "postal_box": "", "postal_code": "5642 CV", "city": "Eindhoven", "country": "NL", "vat_number": "NL123456789B01", "coc_number": "NL12345678", "eori_number": "NL123456789", "brand_id": 2, } ] ``` In this example, two different addresses are stored to this account information, each with its own linked [brand](/docs/getting-started/brands). * To ship a parcel from our French store location, we can specify the `id` for this sender address in the `sender_address` field when you make a `POST` request to the [Create a parcel endpoint](/docs/archive/shipping/create-a-parcel). * To see shipping methods applicable for parcels shipping from France, you should specify the `sender_address` `id` of your secondary location when you make a `GET` request to the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint. ## Automate your 'ship from' location with shipping rules You can make use of [Shipping rules](/docs/shipping/shipping-rules/) to automatically create parcels from a specific sender address, based on pre-defined conditions. You can configure shipping rules to automatically ship parcels from a specific sender address based on criteria such as `from_country`, `to_country` and `integration`, plus many more. When properly configured, shipping rules interact with parcels created through the API to remove much of the manual decision making involved in choosing a sender address address per parcel. Read more about creating and applying shipping rules # Creating test labels (API v2) Source: https://sendcloud.dev/docs/archive/getting-started/creating-test-labels This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of this page for API v3](/docs/getting-started/creating-test-labels). You can test Sendcloud APIs without running the risk of being charged for any shipping labels you create in the process. There are two methods of creating test labels: 1. Create a test label using the Sendcloud shipping method **Unstamped letter**. You won't be charged for any parcels which are created using this method. 2. Create a label and cancel it within the deadline For testing purposes, we recommend you create parcels with the `request_label` property set to `false`. This will prevent labels from being created at the same time as the parcel and **avoid** potential charges. ## Method 1: create a test label using the Unstamped letter shipping method The shipping method **Unstamped letter** is a Sendcloud method which allows you to create test labels without being charged. It's not possible to use the **Unstamped letter** shipping method to create **return** parcels. To test return parcel creation, you should use a suitable return method and then [cancel the label before the cancellation deadline](/docs/shipping/cancel-a-label/). If you're creating a number of test parcels, you may find it helpful to set **Unstamped letter** as your [default shipping method](https://support.sendcloud.com/hc/en-us/articles/12213808740116-How-to-set-up-your-default-shipping-settings) in your Sendcloud account settings. You can specify the shipping method **Unstamped letter** in your API requests within the `shipment` object. Note that the `id` for this method is `8` at the time of writing. Note: Shipping method IDs are **volatile**, and should not be saved for more than an hour. The list of available methods and their associated IDs **change frequently**, as we continually add new methods and update existing ones in our system. ```json Example request body theme={null} { "shipment": { "id": 8, "name": "Unstamped letter" } // ... other parcel fields } ``` ## Method 2: create a label and cancel it within the deadline When you want to test outgoing or return parcel creation, and the “Unstamped letter” method isn't applicable, it's possible to create shipping labels and then cancel them within the cancellation deadline. Find out how to cancel a label before the cancellation deadline **Not all carriers support cancellation requests**. Carefully consult the list of carriers [in our help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-) before you request a label for a particular shipping method to be sure that cancellation is possible. # Multicollo returns Source: https://sendcloud.dev/docs/archive/returns/multicollo-returns This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of our returns documentation for API v3](/docs/returns/index). The Return portal API supports **multicollo returns**. This allows you to create a return shipment which contains multiple parcels, so long as the **outgoing shipment** was also [multicollo](/docs/shipping/multicollo). ## How to create a multicollo return The process for creating a multicollo return is the same as described in the [Return portal documentation](/docs/returns/return-portal#creating-the-return-parcel). The only difference is that you can state the number of collos to include in the return shipment. 1. Use the identifier of any of the parcels (tracking number or order number) included in the original shipment with the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. This will always return the main parcel in the shipment, so don't worry if the identifiers don't match. 2. In the `parcel` object in the response, you can find the number of parcels which were included in the original shipment under `collo_count`. You can choose to return, **at most**, a number of parcels **equal to** this number. 3. When sending your request to the [Create a return](/api/v2/return-portal/create-a-return) endpoint, add the number of parcels you want to include in the shipment under the `collo_count` field, in the `incoming_parcel` object. Each parcel inside the multicollo return is treated as an individual shipment, and will receive its own tracking number. ```http Example request method and URL wrap theme={null} POST https://panel.sendcloud.sc/api/v2/brand/{brand_domain}/return-portal/incoming ``` ```json Example request body snippet theme={null} { "outgoing_parcel": 123, // ID of the original outgoing parcel "incoming_parcel": { "collo_count": 3 // ... other incoming_parcel fields } // ... other fields } ``` # Return methods Source: https://sendcloud.dev/docs/archive/returns/return-methods This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of our returns documentation for API v3](/docs/returns/index). From the Sendcloud platform, you can enable the following return methods through your Return portal settings: * **Arrange a pickup** * **Return in store** * **At a drop-off point** (includes ERS - Easy returns solution) * **Labelless returns to a drop-off point** This tutorial explains the various ways you can specify a return method when you use the [Create a return](/api/v2/return-portal/create-a-return) endpoint in the Return portal API, and the differences between each method. ## Arrange a pickup The pickup returns method will schedule a pickup from your customer's address as soon as the return parcel is announced. Depending on the carrier, the pickup will then take place either on the next working day, or the following day. There are a limited number of carriers who support this feature. For more information about pickup returns, including a list of supported carriers and pickup schedules, please see our [help center](https://support.sendcloud.com/hc/en-us/articles/4406152719124-Pickup-Returns). To create a pickup return through the API, you need to include the `"delivery_option": "pickup"` field in the request. You also need to send a `selected_functionalities` object which includes the field `"first_mile": "pickup"`. ```json Example request body snippet theme={null} { "delivery_option": "pickup", "selected_functionalities": { "first_mile": "pickup" } // ...other fields } ``` ## Return in store If you have enabled this method in your portal settings, you can allow your customers to drop their parcel off at a physical store location. With this method, a return shipping label **isn't required.** To create an in-store return, specify the following field in your request: `"delivery_option": "in_store"`. ```json Example request body snippet theme={null} { "delivery_option": "in_store" // ...other fields } ``` ## At a drop-off point This method allows your customer to return their parcel by delivering it to the nearest service point (drop-off) location for the chosen carrier. To specify a drop-off location in your request, use the `service_point` object structured exactly as you received it from the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. You'll also need to include the following field: `"delivery_option": "drop_off_point"`. ```json Example request body snippet theme={null} { "delivery_option": "drop_off_point", "service_point": { // ...service point details from outgoing parcel endpoint } // ...other fields } ``` ### Easy returns solution (ERS) The ERS method allows customers who are based in more than 10km away from a applicable drop off-location to drop the parcel off at a branch for a national postal carrier instead. The national carrier will complete the first leg of the journey, and then hand the parcel over to the carrier you originally specified to complete the delivery. The ERS is particularly useful for facilitating **easy international returns** for your customers. If your customer is based in Germany, for example, they'll be able to drop their PostNL parcel off at a Deutsche Post service point. The names of both carriers will appear on the return label. You can read more about the ERS and view a list of carriers who support this return method on our [help center](https://support.sendcloud.com/hc/en-us/articles/4401922159636-How-does-the-Easy-Returns-Solution-feature-work-). The ERS is enabled by default when the return method “At a drop off point” is enabled in your Return portal settings. To enable ERS for a return, include the field `"delivery_option": "drop_off_point"` in your request. You also need to include the `selected_functionalities` object, with the field `"ers": true`. In the `selected_carrier_code` field, include the code of the carrier you want to use to create the return label , e.g. `postnl`. ```json Example request body snippet theme={null} { "delivery_option": "drop_off_point", "selected_carrier_code": "postnl", "selected_functionalities": { "ers": true } // ...other fields } ``` ## Labelless returns to a drop-off point This method works similarly to the drop-off point return method, but your customer doesn't need to physically print the return label and attach it to the box. Instead of a return label, a QR code will be generated. They can show this code on their phone when they take the parcel to a labelless drop-off point. To create a labelless return, specify the field: `"delivery_option": "drop_off_labelless"`. To specify a drop-off location in your request, you can the use the `labelless_service_point` object, structured exactly as you received it from the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. Not all carriers support labelless returns. See our [help center](https://support.sendcloud.com/hc/en-us/articles/360059835851-Paperless-returns) for more information about how this return method works, and through which carriers. ```json Example request body snippet theme={null} { "delivery_option": "drop_off_labelless", "labelless_service_point": { // ...labelless service point details from outgoing parcel endpoint } // ...other fields } ``` # Return portal Source: https://sendcloud.dev/docs/archive/returns/return-portal This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of our returns documentation for API v3](/docs/returns/index). Build your own return portal, find the closest service point to the customer's address, create return shipments, and download return labels. The Sendcloud Return portal is an easy-to-use solution to allow your customers to create their own returns based on an outgoing shipment, and select a convenient service point location to drop-off their parcel. ## Set up your Return portal 1. Follow the steps in our [Quickstart guide](/docs/getting-started) to set up your Sendcloud account 2. Create a [brand](/docs/getting-started/brands) 3. Create a return address in your [Address settings](https://app.sendcloud.com/v2/settings/addresses/returns) in the Sendcloud platform 4. Configure your preferred return reasons, methods and carriers in your [Return portal settings](https://support.sendcloud.com/hc/en-us/articles/360025142691-How-do-I-set-up-my-return-portal-) You can create a unique Return portal for each of the brands you've created in your Sendcloud account. ## Authentication The Return portal API uses **JWT authentication**. Since this is a public facing API which can also be accessed by customers, access tokens are generated upon a successful outgoing parcel lookup. 1. Retrieve the original shipment details via the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. 2. Two JWT authentication tokens will be provided in the response: one for creating a new return parcel (`access_token`), and one for looking up additional service point (drop-off) locations (`service_points_token`). 3. In order to create the return parcel, include an `Authorization` header with a `Bearer` schema in your request, and enter the `access_token` you obtained in the response from the Outgoing parcel lookup. ## Build your own version of the Return portal If you're a developer, you can use the Return portal API to retrieve your configured settings and build your own custom portal. Explore the Return portal API documentation and API playground ## Creating returns through the Return portal Once your Return portal is configured, you can access it via the URL you can find in the [Return portal settings page](https://app.sendcloud.com/v2/settings/return-portal) in the Sendcloud platform, or in the [Retrieve Return portal settings](/api/v2/return-portal/retrieve-return-portal-settings) endpoint. From here, you can create returns directly in the portal, or send the link to your customers so they can manage their own returns. ## Retrieve an outgoing shipment You can retrieve information about an outgoing shipment by making a GET request to the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint. You need to provide two query parameters in your request: the `postal_code` of your customer and the parcel `identifier`. This can be either the tracking number or the order number of the outgoing parcel. You also need to include the **brand domain name** for your Return portal as a path parameter, as shown in the example below. Your domain name can be configured in the settings of the brand which is connected to your return portal. ```http Example request method and URL wrap theme={null} GET https://panel.sendcloud.sc/api/v2/brand/{brandDomainName}/return-portal/outgoing?identifier={trackingNumber}&postal_code={customerPostalCode} ``` On a successful lookup, you will retrieve information about the original parcel, in addition to two JWT tokens: one to create a return parcel (`access_token`) and one to perform a service point lookup (`service_points_token`). The response will also include a list of `shipping_method_ids` which you can use to create the return parcel. This list is based on the carriers you have enabled in the settings of your Return portal. ### Service point information In the response you will see information about the closest drop-off point to your customer's location (based on their post code and applicable carriers) in the `service_point` object. You can use this information to specify a drop-off location when you create the return parcel. If any of your enabled carriers support [labelless returns](/docs/returns/return-methods), then the nearest `labelless_service_point` will also be retrieved. This can be used to specify the a drop-off location which supports labelless returns if you want to use this specific return type. See full examples of request and response payloads, and try out the endpoint in the API playground ## Creating the return parcel Using the `access_token` you retrieved from the [outgoing parcel lookup](#retrieve-an-outgoing-shipment) step, you can create a return parcel via the [Create a return](/api/v2/return-portal/create-a-return) endpoint. You can create your return parcel using any of the [return methods](/docs/returns/return-methods/) enabled in your portal settings. ## Downloading the return label Once a return parcel is successfully created, a **polling URL** is included in the response. Creating a label depends on the response time of the carrier, so you need to poll this endpoint to see the status of the label. The authentication token and parcel `id` is already included in the URL, so it's not necessary to perform another lookup or provide any additional parcel details. A `200` response indicates that the label is ready to be downloaded in PDF format via the URL. ## Service points search By default, performing an [outgoing parcel lookup](#retrieve-an-outgoing-shipment) will return the closest service point location to the customer, based on their postcode. If you're using the Return portal API to build your own returns solution, you may want to provide more drop-off locations for your customers to choose from. To facilitate this, you can retrieve a list of available service points within a specified search radius. This is done by making a `GET` request to the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint. You'll need to provide the `service_points_token` you received via the Outgoing parcel lookup step to authenticate, and specify the following additional parameters: * The country code of your customer * The latitude and longitude of the customer's address. (This is returned from the [Retrieve an outgoing parcel](/api/v2/return-portal/retrieve-an-outgoing-parcel) endpoint.) * A search radius in meters * (Optional) The carrier for which you want to receive drop-off locations ```http Example request method and URL wrap theme={null} GET https://servicepoints.sendcloud.sc/api/v2/service-points/?access_token={service_points_token}&country=NL&latitude=51.440316&longitude=5.473478&radius=500 ``` # Cancel a label Source: https://sendcloud.dev/docs/archive/shipping/cancel-a-label This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3, read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments). It's possible to create labels in Sendcloud and then cancel them before the carrier deadline. This is good to know for [testing purposes](/docs/getting-started/test-labels/), in particular when you want to test creating return parcels. In most cases, you will not be charged for labels which are **not shipped** and cancelled before 23:59 on the **day of creation**. ## Conditions for label cancellation It's not always possible to cancel a label which is already announced. As a result, cancellation is not guaranteed and may be asynchronous depending on the state of the parcel. Each carrier will have different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the label is cancelled within the deadline. You can find out more about cancellation deadlines and supporting carriers in our [help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-). ## How to cancel or delete a label Labels can be cancelled or deleted from the Sendcloud platform or via the API. To cancel a label, make a request to the [Cancel/Delete a parcel endpoint](/api/v2/parcels/cancel-a-parcel) and specify the parcel `id` as the path parameter for the `POST`request to `https://panel.sendcloud.sc/api/v2/parcels/{id}/cancel` If the parcel already had a shipping label, it will be cancelled but it will still be in the Sendcloud system under the original parcel `id`. In the Sendcloud platform, it will appear in the **Cancelled labels** tab. ```json Example response for a cancelled label theme={null} { "status": "cancelled", "message": "Parcel has been cancelled" } ``` If the parcel did not have a shipping label attached to it, and was not yet announced with the carrier, then the parcel object will be **deleted**. You will need to create the parcel again if you want to announce it at a later date. ```json Example response for a deleted label theme={null} { "status": "deleted", "message": "Parcel has been deleted" } ``` ## Information about cancelled labels * If you don't manage to cancel a label within the deadline, don't worry. You'll be charged for the label, but if you **cancel it within 42 days** and it remains unshipped, the cost will automatically be reimbursed on your next invoice. * When the cost for a label is deducted, it will be clearly stated on your invoice. For more information see the [help center](https://support.sendcloud.com/hc/en-us/articles/360025144511-How-undelivered-shipments-appear-on-your-invoice). # Create a parcel Source: https://sendcloud.dev/docs/archive/shipping/create-a-parcel This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3, read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments). Sendcloud's flexible shipping API covers every part of the shipping process, from label creation right up to the point of delivery. Ready to put your shipping processes on autopilot? Read on to learn how to create your first parcel with Sendcloud's **Shipping API**. There are two ways to create a parcel via the API: **Method 1: Create a parcel object** * This is the most flexible means of creating a parcel. The parcel object is created in the Sendcloud system, but the parcel is not immediately announced with the carrier. * This gives you time to continue making changes to the parcel data and decide on a shipping method right up until the moment you're ready to create the label. * Parcels can be processed either via the [Sendcloud platform](https://support.sendcloud.com/hc/en-us/articles/360025263691-Process-your-orders-), or you can perform all interactions via the API, depending on your specific use case. **Method 2: (Advanced option): Create the parcel and shipping label in a single API call** * This method is described in more detail at the end of this tutorial. To help get you started, this guide will cover the basics of **creating a parcel via the API**, step-by-step. Once the parcel is created, you can continue on to the next steps to learn how to choose a shipping method and print the label. ## Before you begin 1. Make sure you've completed basic account set up. See [Quickstart](/docs/getting-started) 2. You'll need to have obtained your API keys so you can authenticate with our API. See [Authentication](/docs/getting-started/authentication) 3. You'll need access to a tool that allows you to make API calls. Examples are [Postman](https://www.postman.com/sendcloud-api) and [Insomnia](https://insomnia.rest/download). ### The Create a parcel or parcels API endpoint Parcels are created by sending a HTTP `POST` request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. ```http Request method and URL theme={null} POST https://panel.sendcloud.sc/api/v2/parcels ``` #### Authorization header Every time you make an API call, you need to [authenticate](/docs/getting-started/authentication) your connection to Sendcloud by including your API keys through a HTTP header. ```http Authorization header theme={null} Authorization: Basic ``` ## Step 1: Prepare your request In the body of your HTTP request, you need to specify all the required information for the shipping label. Below you can find an example which will create a parcel object in your Sendcloud account. ```json Example request body theme={null} { "parcel": { "name": "John Doe", "company_name": "FlowerShop", "email": "john@doe.com", "telephone": "+31611223344", "address": "Fürstenrieder Str.", "house_number": "70", "address_2": "", "city": "Munich", "country": "DE", "postal_code": "80686", "country_state": null, "to_service_point": 10168633, "to_post_number": 262373726, "customs_invoice_nr": "", "customs_shipment_type": null, "parcel_items": [ { "description": "T-Shirt", "hs_code": "6109", "origin_country": "SE", "product_id": "898678671", "properties": { "color": "Blue", "size": "Medium" }, "quantity": 2, "sku": "TST-OD2019-B620", "value": "19.95", "weight": "0.9" }, { "description": "Laptop", "hs_code": "84713010", "origin_country": "DE", "product_id": "5756464758", "properties": { "color": "Black", "internal_storage": "2TB" }, "quantity": 1, "sku": "LT-PN2020-B23", "value": "876.97", "weight": "1.69" } ], "weight": "3.49", "length": "31.5", "width": "27.2", "height": "12.7", "total_order_value": "896.92", "total_order_value_currency": "EUR", "shipment": { "id": 1316, "name": "DHL Parcel Connect 2-5kg to ParcelShop" }, "shipping_method_checkout_name": "Battery WarehouseX DHL", "sender_address": 1, "quantity": 1, "total_insured_value": 0, "is_return": false, "request_label": false, "apply_shipping_rules": false, "request_label_async": false } } ``` The important thing to note here is that the `request_label` parameter is set to `false`. This allows you to create a parcel without announcing it to a carrier or creating a shipping label. The parcel will be created using the **default** shipping method you saved in your account, and can be updated later. Also note that specific carriers might impose [additional requirements on address-related fields](/docs/shipping/address-field-limits/). ### Other request fields There are many other additional fields that you can specify when creating a parcel. An example would be the `sender_address` parameter which lets you ship a parcel from a different sender location, or the parameters related to customs information for international shipping. You can find a list of the supported fields in our [API reference](/api/v2/parcels/create-a-parcel-or-parcels/). ## Step 2: Send your request Take the example above, and use it to make a `POST` request to `http://panel.sendcloud.sc/api/v2/parcels`. ```http Request method, URL, and Authorization header theme={null} POST https://panel.sendcloud.sc/api/v2/parcels Authorization: Basic ``` If everything went well, you'll receive a HTTP 200 [status code](https://en.wikipedia.org/wiki/List_of_HTTP_status_codes) and a `parcel` object in the response body. See an example of the response body in the [API reference](/api/v2/parcels/create-a-parcel-or-parcels). #### Some things to note about the response * The newly-created parcel will be assigned a parcel `id`, e.g. `"id": 189169249`. This is the unique parcel identifier which we will use whenever we want to update a parcel or create the label via the API. * The current status of the newly-created parcel will be `"No label"`. It will appear in the Sendcloud platform under the **Incoming order view** with the message **Ready to process** until we create a label for it. Screenshot of the Incoming order view, showing the newly-created parcel with the status "Ready to process" ## Step 3: Create the shipping label To create shipping labels via the API, you need to use the [Update a parcel endpoint](/api/v2/parcels/update-a-parcel) to update the value of `request_label` to `true`. Via this endpoint, you can also make changes to any of the properties that can be used for creating a parcel. ### Generating a label for an existing parcel In this example, we will update parcel `"id": 1` as follows: * Create the shipping label by providing the data `"request_label": true` * Change the `name` of the recipient to a new value * Change the shipping method by providing the corresponding `id`. In this example, we'll be using the method **"Unstamped letter"** to create a test label. You'll be invoiced for any shipping labels you create if you don't cancel or delete them within the [cancellation deadline](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment). You can create [test labels](/docs/getting-started/test-labels/) without receiving a charge by using the shipping method Unstamped letter (`"id": 8`) ```http Request method, URL, and Authorization header theme={null} PUT https://panel.sendcloud.sc/api/v2/parcels Authorization: Basic ``` ```json Example request body theme={null} { "parcel": { "id": 1, "request_label": true, "name": "Mr Test", "shipment": { "id": 8, "name": "Unstamped letter" } } } ``` Once you've prepared the response body, make a `PUT` request to the [Update a parcel endpoint](/api/v2/parcels/update-a-parcel). Make sure to include your authentication and content headers, as you did in Step 2. If everything goes well, you should receive a response similar to the one below: ```json Example response body theme={null} { "parcel": { "id": 1, "name": "Mr Test", "shipment": { "id": 8, "name": "Unstamped letter" }, "status": { "id": 1000, "message": "Ready to send" }, "label": { "normal_printer": [ "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0", "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=1", "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=2", "https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=3" ], "label_printer": "https://panel.sendcloud.sc/api/v2/labels/label_printer/1" }, "shipping_method": 8 // ... other parcel data } } ``` Notice that the response reflects the updates you have made to the customer `name`, and that the parcel `status` is now **"Ready to send"**. The shipping method has been updated to **"Unstamped letter"**. ## Step 4: Download the shipping label At the end of the previous step, you should have received a response which contains some URLs under the `label` field. These URLs are your links to download the shipping label. Labels can be downloaded in PDF format and are provided in A4 size for normal printers, and A6 size for label printers. Under `normal_printer`, the `start_from` value indicates the position of the label on an A4 size page: * `0` = Top left * `1` = Top right * `2` = Bottom left * `3` = Bottom right You'll need to provide your API credentials again to access the link to download your labels. You can do this by making a `GET` request to the URL of the label you want to access, and including the `Authorization` header. ```http Request method, URL, and Authorization header theme={null} GET https://panel.sendcloud.sc/api/v2/labels/normal_printer/1?start_from=0 Authorization: Basic ``` Labels can also be downloaded in bulk directly from the Sendcloud platform under the **Created labels** tab, or via the [Retrieve multiple PDF labels](/api/v2/labels/retrieve-multiple-pdf-labels) and [Bulk PDF label printing](/api/v2/labels/bulk-pdf-label-printing) endpoints. **Congrats!** You've just created your first parcel and downloaded the shipping label via the API. ## Next steps You can continue reading more tutorials or dive directly into exploring our API references. * [Choose a shipping method](/docs/shipping/shipping-methods) - learn how to retrieve the full list of shipping services available to you via Sendcloud * [Tracking parcels](/docs/archive/tracking/tracking-parcels) - to see how you can track the delivery journey of your newly created parcel as it travels to your customer * [Create a return](/docs/returns/return-portal) - read how you can create a return parcel shipment using the Sendcloud Returns API * [API v2 reference](/api/v2/) and [API v3 reference](/api/v3/) - browse our API references to explore more options for creating parcels and managing your shipping processes. ## Advanced options ### Create a parcel and immediately request a label in a single API call If you already know which shipping method you want to use to send your parcel, you can bypass Step 3 above by making a `POST` request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, including `"request_label": "true"`. When directly announcing parcels in this way, the `shipment` field is mandatory, and a shipping method `id` and `name` must be provided in the API request. If you're [shipping parcels internationally](/docs/shipping/international-shipping/), pay attention to the additional fields which become mandatory for customs documentations purposes. A full list of required parameters can be found in the [API reference](/api/v2/parcels/create-a-parcel-or-parcels). ### Create a return parcel You can use the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint to create return labels via the API. The process for creating a return label via this method is the same as for creating a parcel, but you must set the value of the `is_return` property to `true` and specify the customer's address address in the `from_*` fields. It's important to note that standard shipping methods don't apply to return parcels. You can find an overview of available return methods via the [List of all shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint and include the parameter `"is_return": true`. You can also create returns using the **Returns API** by following the [Create a return guide](/docs/returns/return-portal/). ### Ship parcels and retrieve methods for your sender addresses based in other countries You can set up multiple sender addresses in your Sendcloud account, and specify which sender address you want to ship from when you create a parcel. See our [sender addresses documentation](/docs/getting-started/sender-addresses) for more info. ### Automatically apply your preferred shipping methods via shipping rules Shipping rules are a Sendcloud feature which can be used in conjunction with the API to take the legwork out of manually choosing and selecting the best method for your created parcels. See our [shipping rules documentation](/docs/shipping/shipping-rules/) for more details. ### Print your brand logo on your shipping labels You can customize a brand in your Sendcloud account to make use of handy marketing tools, such as customizable tracking notifications and branded return portals for each of your integrations. See more about creating your brand in our [help center](https://support.sendcloud.com/hc/en-us/articles/360041212392-How-to-set-up-your-brand-). ### Receive real time parcel status updates via Webhooks There are two ways to receive real-time parcel event notifications: * **Classic webhooks** — configure webhook URLs directly in the [Sendcloud platform](https://app.sendcloud.com/v2/settings/integrations/manage) or via the [Webhooks API](/api/v3/webhooks/index). This is the established approach for receiving parcel status updates. * **Event Subscriptions API** — programmatically create [connections and subscriptions](/api/v3/event-subscriptions/index) to control where events are delivered and which events you listen for. Supports webhook endpoints and third-party integrations like Klaviyo. The Event Subscriptions API is currently in **BETA**. # Handling parcel errors Source: https://sendcloud.dev/docs/archive/shipping/handling-parcel-errors This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3, read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments). In the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint, when a request contains errors, the API responds with an error message and no parcels in the request are processed. This is the default behavior for this endpoint. ```json Example of a validation error message response theme={null} { "error": { "code": 400, "request": "api/v2/parcels", "message": "house_number: 'This field cannot be blank.'" } } ``` ## Getting more detailed error information To get more detailed information about errors that occur during parcel creation, pass the `errors` query parameter to your request. It can be one of `errors=verbose` or `errors=verbose-carrier`. ```http Request method and URL, with errors query parameter theme={null} POST https://panel.sendcloud.sc/api/v2/parcels?errors=verbose ``` The response structure will change when using the `errors` query parameter: ```json Example response structure with the errors query parameter theme={null} { "parcels": [], // List of successfully created parcels "failed_parcels": [] // List of parcels that failed } ``` The behavior of the endpoint also changes when the `errors` query parameter is used. All parcels in the `parcels` key will be processed, while the parcels in the `failed_parcels` key will not be processed. This differs from the default behavior, where if any parcel in the request contains an error, the entire request fails. ### `errors=verbose` Including the query parameter `errors=verbose` returns **errors that occurred during the validation of the request**. These errors only pertain to the provided data in the request (e.g. an invalid country was provided). ```json Example response using errors=verbose theme={null} { "parcels": [], "failed_parcels": [ { "parcel": { //... parcel data that was sent in the request }, "errors": { "name": ["This field is required."] } } ] } ``` ### `errors=verbose-carrier` Including the query parameter `errors=verbose-carrier` returns **errors that occurred on the carrier's side**. It is impossible to predict if these errors will happen ahead of time. It makes sense to use this query parameter if `request_label_async` is set to `false` and `request_label` is set to `true`. In such cases, errors can be recognized by the following structure: ```json Example response using errors=verbose-carrier theme={null} { "parcels": [], "failed_parcels": [ { "parcel": { //... parcel data that was sent in the request }, "errors": { "non_field_errors": ["Service error: "] } } ] } ``` #### HTTP response codes when using the `errors=verbose-carrier` query parameter When creating parcels, the behaviour of errors=verbose-carrier depends on the request data. The following scenarios apply: Sending one parcel: * If the parcel is sent successfully, the API will return an `HTTP 200` status code and the serialized parcel in the response body. * If the parcel fails to send, the API will return an `HTTP 400` status code and a carrier error message. Sending multiple parcels (including multi-collo): * If all parcels are sent successfully, the API will return an `HTTP 200` status code and the serialized parcels in the response. * If some parcels fail to send, the API will return an `HTTP 200` status code and a `failed_parcels` field in the response. The `failed_parcels` field is a list of dictionaries, where each dictionary contains the parcel data and the errors that occurred for that parcel. * If all parcels fail to send, the API will return an `HTTP 400` status code along with the errors listed in the same way as in the previous scenario. # Shipping methods Source: https://sendcloud.dev/docs/archive/shipping/shipping-methods This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3, read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments). Sendcloud partners with [160+ international carriers](https://www.sendcloud.com/how-it-works) to offer a wide variety of flexible **shipping methods**. Some methods are only available when you [connect a direct carrier contract](/docs/getting-started/carrier-contracts), while others can be [enabled in your Sendcloud account](/docs/getting-started/), so you can start shipping with them straight away. This article serves as a guide on how to make an API call to retrieve a list of available shipping methods. This will allow you to find the `id` for a method and use it to announce a parcel. This `id` is the unique identifier which you need to obtain before you can perform the following activities via the API: 1. [Create a shipping label](/docs/archive/shipping/create-a-parcel): before you can create a shipping label, you first need to specify a shipping method `id` in your request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) or [Update a parcel](/api/v2/parcels/update-a-parcel) endpoints. The parcel will then be announced with the relevant carrier, and the label can be downloaded. 2. [Retrieve shipping rates](/docs/shipping/shipping-rates/): you can check the rates for a specific shipping method by providing the method `id` in your request to the [Retrieve a shipping price](/api/v2/shipping-prices/retrieve-a-shipping-price) endpoint. 3. [Create a return](/docs/returns/return-portal/): you need to specify the `id` for an appropriate return shipping method in order to announce a return parcel. Note: Shipping method `id`s are volatile, and should not be cached for more than an hour. ## Retrieve shipping methods To retrieve a list of shipping methods which can be used to ship a parcel, you need to make a `GET` request to the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint. The shipping methods that will be retrieved appear based on the following factors: 1. The carriers you have enabled in [your Sendcloud account](/docs/getting-started/); 2. (Optional) The direct [carrier contracts](/docs/getting-started/carrier-contracts/) you have connected; and, 3. Your [sender address](/docs/getting-started/sender-addresses/): if you don't specify a `sender_address` id in the query parameters, then your default sender address will be used. This may affect which shipping methods you can see in the response, as some methods and carriers only operate in certain locations. * For example, if your default sender address is in the Netherlands, you will not see shipping methods that only operate from France. To see shipping methods available for shipping from France, you will need to specify a French `sender_address` service\_point\_id in the request. ```http Request method and URL theme={null} GET https://panel.sendcloud.sc/api/v2/shipping_methods?sender_address=123456 ``` ### Notes on the shipping methods response * The shipping method `id` is a top-level field in the response e.g. ```json Response body theme={null} [ { "id": 123, "name": "Example shipping method" // ... other fields } ] ``` * Prices for each method are displayed under the `countries` object. Please note that rates will differ depending on your current subscription plan. **Tip:** Once you're familiar with making API calls to retrieve shipping methods, you may want to filter for shipping methods based on their added-value services, known as [shipping functionalities](/api/v2/shipping-products/retrieve-a-list-of-shipping-functionalities). An example of this would be the ability to only retrieve shipping methods which require a "Signature on receipt". This is possible via the [Shipping products](/api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint. ## Advanced options ### Service point shipping methods If you want to ship a parcel to a service point, you need to use an applicable service point shipping method. You can filter the list of results to only display methods which can be used for service point delivery by including a `service_point_id` in the query parameters of your request. ```http Request method and URL theme={null} GET https://panel.sendcloud.sc/api/v2/shipping_methods?service_point_id=12345678 ``` You can obtain a `service_point_id` using the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint. ### Return shipping methods Return methods are treated differently from methods for outgoing parcels. If you want to only show shipping methods which apply to return parcels, include the argument `is_return=true` in the query parameters of your request. ```http Request method and URL theme={null} GET https://panel.sendcloud.sc/api/v2/shipping_methods?is_return=true ``` For a more refined way to retrieve return methods, you can refer to the [Returns API](/docs/returns/return-portal/) endpoints to filter for shipping products which match a given set of parcel characteristics, such as ship from country, ship to country, parcel weight and parcel dimensions. ## Troubleshooting: "Invalid shipment id" error If you try to use the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint and receive the error message “Invalid shipment id”, this could be because you're trying to use a shipping method which isn't applicable for the destination address. For example, if you need to ship a parcel internationally, but the specified shipping method only supports national (domestic) delivery, then you would need to lookup a new `id` for a supporting method and change the request. # Shipping rates Source: https://sendcloud.dev/docs/archive/shipping/shipping-rates This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3, read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments). The Sendcloud API seamlessly connects you to [a huge range of carriers worldwide](https://www.sendcloud.com/carriers/), giving you access to a diverse catalogue of shipping methods and service levels to fit the needs of any e-commerce business. We're continuously integrating new carriers and methods with our platform across the national and international delivery landscape. ## Receive discounts on your shipping labels You don't need to have a carrier contract to access shipping methods in Sendcloud. You can create shipping labels using Sendcloud rates, and receive a discount on your label price based on your subscription plan. The higher your plan, the more discount you'll receive. ## Connect your own direct contract If you have a direct contract with a carrier, you can [add it to your Sendcloud account](/docs/getting-started/carrier-contracts/) and create labels in Sendcloud using your contracted rates. ## Retrieve shipping rates through the API Through the Sendcloud API, you can access rates for a host of shipping methods, and directly compare pricing for domestic and international delivery options in a single API call. You'll only be able to see rates for carriers you've enabled in your account, so be sure to complete all the steps in [Getting started](/docs/getting-started/) before proceeding. ### Get rates for all shipping methods If you don't know which method you want to use, or if you want to compare pricing, you can retrieve a list of all available methods and rates by making a `GET` request to the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint. Learn more in our shipping methods guide ### Get rates for specific shipping methods Note: Carriers that use pricing based on shipping zones (e.g. Spanish carriers who charge different rates based on the postal code of the shipment) are not supported. You can access rates for a specific shipping method by making a `GET` request to the [Retrieve a shipping price](/api/v2/shipping-prices/retrieve-a-shipping-price) endpoint. You'll need to know some basic information before you can make your request: 1. The shipping method `id`, which will be used as the `shipping_method_id` query parameter. This is the internal reference Sendcloud uses to identify shipping methods. You can retrieve an `id` via the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) or Shipping products endpoints. 2. The `weight` of your parcel, and whether it's in kilograms or grams (`weight_unit`) 3. The country the parcel will be sent from (`from_country`) as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code, e.g. `NL` for the Netherlands 4. (Optional) The country the parcel will be sent to (`to_country`) as an [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code * If you don't provide a `to_country` parameter, the response will include prices for all the shipping destinations that are applicable to the method These pieces of information should be sent as query parameters to the endpoint, for example: ```http Request method and URL wrap theme={null} GET https://panel.sendcloud.sc/api/v2/shipping-price/?shipping_method_id=1234&weight=2weight_unit=kilogram&from_country=NL&to_country=DE ``` **Tip:** If you've already connected your own carrier contract, then rates for your connected carriers will be null, unless you have [uploaded your own contract pricing](https://support.sendcloud.com/hc/en-us/articles/5163547066004-How-to-upload-your-own-prices-from-your-direct-carrier-contract). Retrieve a shipping price endpoint # Shipping rules Source: https://sendcloud.dev/docs/archive/shipping/shipping-rules This page applies to v2 of the Sendcloud API and is no longer maintained. To learn more about switching to API v3, read our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3#parcels/shipments). You can create shipping rules in your Sendcloud account and use them in conjunction with our API to automate your parcel processing workflow. Shipping rules are pre-defined actions which will automatically apply to created parcels or imported orders when they match a given condition. An example of a shipping rule would be: * If **\[parcel weight]** is *less than* **\[10kg]**, *ship with* **\[PostNL Home address only 0-23kg]** There is a wide range of conditions and actions available which cover almost every aspect of parcel creation. For a quick guide on how to streamline your workflow with shipping rules, see [our help center](https://support.sendcloud.com/hc/en-us/articles/360025143571-Automate-your-workflow-using-Sendcloud-Shipping-Rules). ## Apply shipping rules when creating parcels When you create a parcel using the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint in the Parcels API, you can indicate whether you want to apply shipping rules with the `apply_shipping_rules` field. The benefit of this is that you can already indicate how you want to ship a parcel without having to manually input multiple different fields in your API request. For example, you can use shipping rules to determine the shipping method, sender address or insurance value you want to apply to parcels based on the to/from address, shipping country, which parcel items are included, and many other conditions. Depending on whether or not you choose to immediately request the label, shipping rule behaviour will change as described below: ### Method 1: Create a parcel and immediately request a shipping label In this scenario, you create a parcel, announce it with the carrier and create the shipping label, all in a single API call. This is done by including `"request_label": true` in the request body. This is described in more detail in our documentation on [creating parcels via the API](/docs/archive/shipping/create-a-parcel/). 1. In the request body, use the shipping method `id` for the "Unstamped letter" method. (At the time of writing, this is `8`, but note that shipping method ids can change.) * This is the same method as for [creating test labels](/docs/getting-started/creating-test-labels), but in this case the shipping method will be overridden if a shipping rule is found that matches the parcel's other properties. 2. Set the `apply_shipping_rules` field to `true`. 3. If the parcel properties match one or more shipping rules, then those rules will be applied and the label will be created alongside the parcel. ```http Request method and URL theme={null} POST https://panel.sendcloud.sc/api/v2/parcels ``` ```json Request body theme={null} { "parcel": { "shipment": { "id": 8 }, "apply_shipping_rules": true, "request_label": true // ...other parcel fields } } ``` ### Method 2: Create a parcel without a shipping label In this scenario, you've already created a parcel in Sendcloud, and your shipping rules have already been applied. For example, you created a parcel using the Create a parcel or parcels endpoint, with `"request_label": false` in the request body so the label is not immediately requested. You can continue making changes to the parcel up until the point where you request the shipping label. To request the label for a parcel that already has shipping rules applied, make a `PUT` request to the [Update a parcel](/api/v2/parcels/update-a-parcel) endpoint with `"request_label": true` in the request body. ```http Request method and URL theme={null} PUT https://panel.sendcloud.sc/api/v2/parcels ``` ```json Request body theme={null} { "parcel": { "id": 1, "request_label": true } } ``` #### Overriding shipping rules If you want to override any applied shipping rules, make a `PUT` request to the [Update a parcel](/api/v2/parcels/update-a-parcel) endpoint. In the example request body below, we will request the label for our parcel with `"request_label": true`, and override the applied shipping rule by updating the shipping method to “DHLForYou Drop-off”.' ```http Request method and URL theme={null} PUT https://panel.sendcloud.sc/api/v2/parcels ``` ```json Request body theme={null} { "parcel": { "id": 1, "request_label": true, "shipment": { "id": 117, "name": "DHLForYou Drop Off" } } } ``` # Tracking overview Source: https://sendcloud.dev/docs/archive/tracking/index This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of this page for API v3](/docs/parcel-tracking/index). Sendcloud automatically tracks the latest status update for every parcel created in your account. Through the Tracking API, you can retrieve the **entire tracking history** of a parcel, alongside timestamps which indicate the moment a delivery milestone was met at every point of the delivery journey. You can use the API to **build your own custom tracking solution** for your customers. You can extract the tracking data you retrieve via the API, and consolidate it into an easy-to-read format that displays parcel statuses and their associated timestamps. All you need in order to retrieve the tracking information for a parcel is the unique **tracking number**. Get started with our step-by-step guide on using the Tracking API to track parcels ## Build a branded tracking page If you choose not to utilise the Tracking API to build your own custom solution, we've got you covered. Sendcloud provides a straight-out-of-the-box tracking solution that you can customise directly from your Sendcloud platform. Our [customisable tracking page](https://support.sendcloud.com/hc/en-us/articles/360024837292-Personalize-your-Tracking-page) feature lets you design a Sendcloud-hosted tracking page that you can customise with your brand colours and logos. You can use it to advertise your promotional campaigns and promote your social media presence through our built-in Instagram widget. ## Branded tracking notifications Keep your customers informed every step of the way by [activating tracking emails in your Sendcloud account](https://support.sendcloud.com/hc/en-us/articles/360024841232-Send-branded-Tracking-emails-to-your-customers-). We provide customisable templates in 5 different languages, and you have full control over at which point in the delivery journey a notification will be automatically sent. ## Real-time event notifications Instead of polling the Tracking API, you can receive push notifications whenever parcel events occur. The [Event Subscriptions API](/api/v3/event-subscriptions/index) lets you programmatically configure where and which events are delivered — supporting webhook endpoints and third-party integrations like Klaviyo. The Event Subscriptions API is currently in **BETA**. # Tracking parcels Source: https://sendcloud.dev/docs/archive/tracking/tracking-parcels This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of this page for API v3](/docs/parcel-tracking/create-an-external-parcel-for-tracking). Sendcloud automatically tracks the latest status update for every parcel created in your account. To get started, you'll need to know the `tracking_number` of your parcel so you can look up its delivery status. A unique tracking number is attached to every parcel in the response from the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. To track a parcel, send a `GET` request to the [Retrieve tracking information of a parcel](/api/v2/tracking/retrieve-tracking-information-of-a-parcel) endpoint, including the `tracking_number` in the URL path. ```http theme={null} GET https://panel.sendcloud.sc/api/v2/tracking/{tracking_number} ``` The response will include information about the parcel, the carrier and the expected delivery date. If you've created your own branded tracking page in your Sendcloud account, the link to it is displayed in the `sendcloud_tracking_url` field. Tracking history is nested under the `statuses` object, and is listed in chronological order, starting from the moment the label was created up until the point of delivery. Tracking status messages are mapped from the carrier to the `parent_status` field. See the [endpoint specification](/api/v2/tracking/retrieve-tracking-information-of-a-parcel) for full details on the response structure and all available fields. # Tracking statuses Source: https://sendcloud.dev/docs/archive/tracking/tracking-statuses This page applies to v2 of the Sendcloud API and is no longer maintained. Read the [updated version of this page for API v3](/docs/parcel-tracking/retrieve-tracking-info). Tracking statuses cover all of the delivery "milestones" across the shipping journey. They also indicate when an action has been made (e.g. *Delivery method changed*) or an action is required by the recipient (e.g. *Ready for collection*) or by the sender (e.g. *Address invalid*). Certain delivery milestones also trigger the sending of [tracking notifications](https://support.sendcloud.com/hc/en-us/articles/360024840812-Tracking), which you can configure in the Sendcloud platform. ## Status definitions Sendcloud consolidates all the variations of status messages received by different carriers into a readable format. This corresponds with the `parent_status` field in the response body from the [Retrieve tracking information of a parcel](/api/v2/tracking/retrieve-tracking-information-of-a-parcel) endpoint. | Status | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Address invalid | The provided address details are not correct. | | Announced | The shipping label has been announced at the carrier. | | Announced: not collected | The label is announced, but not yet collected by the driver. | | Announcement failed | The label was not successfully announced at the carrier. | | At customs | The parcel is passing through customs checks at the border. | | At sorting centre | The parcel has arrived at the carrier sorting hub. | | Awaiting customer pickup | The parcel has been delivered to a service point and is awaiting collection by the end customer. | | Being announced | The shipping label is awaiting annoucnement at the carrier. | | Being sorted | The parcel is being sorted at the carrier sorting hub. | | Cancellation request | Cancellation has been requested for this parcel. | | Cancelled | The label was successfully cancelled at the carrier. | | Cancelled upstream | The label been cancelled upstream and is awaiting status Cancelled to be returned by the carrier. | | Delivered | The parcel has been delivered to the end customer. | | Delivery address changed | The delivery address has been modified. | | Delivery attempt failed | The end customer was not home to accept the delivery. | | Delivery date changed | The delivery date for this parcel was changed. | | Delivery delayed | The delivery will take place at a later time or date. | | Delivery method changed | The method of delivery has been modified. | | Driver en route | The driver is on the way to deliver the parcel. | | En route to sorting center | The driver is on the way to the sorting centre. | | Error collecting | The parcel could not be collected by the driver. | | Exception | There has been an exception with the parcel. | | No label | There is no label attached to the parcel. | | Not sorted | The parcel has not been sorted at the carrier sorting hub. | | Parcel en route | The parcel is on the way to be delivered. | | Ready to send | The label has been generated and announced, and the parcel can be picked up or taken to a service point to be delivered to the end customer. | | Refused by recipient | The end customer refused to accept the delivery. | | Returned to sender | The parcel is being returned to the sender. | | Return payment failed | Payment for the return label for this parcel has not been processed. | | Shipment collected by customer | The end customer has collected the parcel from a service point. | | Shipment picked up by driver | The driver has collected the parcel from the service point or requested pickup location. | | Sorted | The parcel has been sorted for delivery at the carrier sorting hub. | | Submitting cancellation request | Cancellation has been requested and is being processed. | | Unable to deliver | The parcel could not be delivered to the intended address or service point. | | Waiting for the return payment | The carrier must receive payment for the return label before it is returned to sender. | # Dynamic Checkout overview Source: https://sendcloud.dev/docs/dynamic-checkout/index The [Dynamic Checkout API](/api/v3/dynamic-checkout) lets you retrieve available delivery options for a specific checkout session, based on real-time context such as the shipping address, cart contents, and the merchant configuration in Sendcloud. It is designed to power dynamic, address-aware checkout experiences, where delivery options (home delivery, service points, same-day, etc.) are shown and updated before payment. Using this API enables you to retrieve eligible delivery options for a given checkout context, display them in a custom checkout UI, and allow the customer to select their preferred delivery option before completing the order. This API does not create shipments or labels — it only informs what delivery options are available at the time of the request. Note: This guide covers our latest version, Dynamic Checkout API v3. For full endpoint and schema documentation, see the [API reference](/api/v3/dynamic-checkout). ## When to use the Dynamic Checkout API Use the Dynamic Checkout API to dynamically determine which delivery options are available during checkout, based on real-time context. It’s particularly useful when you want to: * Show delivery options in real time as the customer updates their address * Adapt delivery choices based on live checkout data * Power a custom or headless checkout flow Typical implementation scenarios include: * Custom storefronts or headless commerce setups * Platforms where native Sendcloud checkout extensions are not available * Checkout flows that must resolve delivery options before payment The Dynamic Checkout API: * Does not create shipments * Does not generate labels * Does not list or search service points ## How it fits into the Sendcloud workflow The Dynamic Checkout API represents the delivery option resolution phase which operates before order creation and shipment fulfillment. It resolves which delivery options are available to the customer at checkout, based on real-time context. Typical flow includes: 1. Customer enters a destination address in checkout 2. Your system calls the [Retrieve a list of delivery options endpoint](/api/v3/dynamic-checkout/retrieve-a-list-of-delivery-options) 3. The API returns eligible delivery options for that context 4. The customer selects one option 5. Your system stores the selected option with the order 6. During fulfillment, you create a shipment using the Shipments or Ship-an-Order API. ## Key Concepts | Concept | Definition | | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Delivery option** | The delivery option is the core response object from the API. Each delivery option represents a valid carrier service that a customer could choose at checkout. The API returns one delivery option per carrier configured for a delivery method. | | `checkout_identifier` | Each delivery option includes a checkout\_identifier field that can be used downstream (for example, to map to a shipping option code in the Shipments API, enabling shipment creation with the selected option). | | **Mapping to configured delivery methods** | If a delivery method uses multiple carriers (e.g., the Service Point delivery method configured with more than one carrier), the API will return multiple delivery options with distinct carriers but referencing the same delivery method ID. | # Retrieve delivery options Source: https://sendcloud.dev/docs/dynamic-checkout/retrieve-delivery-options Use the [Retrieve a list of delivery options](/api/v3/dynamic-checkout/retrieve-a-list-of-delivery-options) endpoint during checkout to retrieve the delivery options available for a specific cart or order context. The endpoint evaluates a published Dynamic Checkout configuration against shipment details and returns the delivery options that are eligible at that moment in the checkout flow. Each returned delivery option can include a `checkout_identifier` that maps directly to a `shipping_option_code`, allowing you to create a shipment later during fulfillment using the Shipments API. The Dynamic Checkout endpoint is read-only. It does not create shipments, generate labels, or store delivery selections — it only resolves which options are available. ## Before you begin To use this endpoint, you must: 1. Make sure you’ve completed basic account set up. See [Quickstart guide](/docs/getting-started). 2. Authenticate using HTTP Basic Authentication (API public and secret keys). See [Authentication](/docs/getting-started/authentication). 3. Create and publish a Dynamic Checkout configuration in the Sendcloud platform. The `configuration_id` in requests must refer to a published configuration linked to your API integration. ## Calling the endpoint To retrieve delivery options, send a `GET` request to the [Retrieve a list of delivery options endpoint](/api/v3/dynamic-checkout/retrieve-a-list-of-delivery-options), including the required checkout context as query parameters. ```http theme={null} GET https://panel.sendcloud.sc/api/v3/checkout/configurations/{configuration_id}/delivery-options?weight_value=2500&total_order_value=45.90&from_country_code=NL&to_country_code=NL ``` ### Required query parameters The endpoint determines delivery eligibility based on: * `configuration_id`: UUID of the published Dynamic Checkout configuration * `weight_value`: Total cart/order weight (in grams) * `total_order_value`:Total cart/order value (in the configuration currency) * `from_country_code`: ISO 3166-1 alpha-2 sender country * `to_country_code`: ISO 3166-1 alpha-2 recipient country These values determine which delivery methods, pricing rules, and carrier services apply. ### Optional query parameters Use these when using [Checkout Rules](https://support.sendcloud.com/hc/en-us/articles/18580048370705-Checkout-rules): * `to_postal_code` * `parcel_length`, `parcel_width`, `parcel_height` * `checkout_metadata` (custom value used in rule evaluation) * `checkout_identifier_type` (default: shipping\_option\_code) Note: To create a shipment from a selected delivery option, request delivery options with: `checkout_identifier_type` \= `shipping_option_code`. This ensures the returned `checkout_identifier` contains the shipping option code required for shipment creation. ## Response If the request is successful, you’ll receive: * **HTTP 200** status code * The evaluated `configuration_id` * A list of `delivery_options` Each delivery option represents a valid shipping choice for the given Dynamic Checkout configuration and includes: * A unique `id` * A `checkout_identifier` (used for shipment creation) * Delivery method and carrier information * Pricing details * Estimated delivery timing The API returns one delivery option per configured carrier. If multiple carriers are configured under the same delivery method, multiple delivery options are returned. These may share the same underlying delivery method ID, allowing you to group them in your checkout UI if desired. Note: Field names are aligned to API payload — see the [Dynamic Checkout API v3 reference](/api/v3/dynamic-checkout/retrieve-a-list-of-delivery-options) for the full schema. ## Error Handling If required parameters are missing or invalid, the API will return an error response. Always validate: * That the `configuration_id` is published and linked to your integration * That weight and order value meet expected formats and ranges * That country codes follow ISO 3166-1 alpha-2 standards Note: See the [Dynamic Checkout API v3 reference](/api/v3/dynamic-checkout/retrieve-a-list-of-delivery-options) for full error response details. # API client requirements Source: https://sendcloud.dev/docs/getting-started/api-client-requirements Sendcloud takes your and your customers' security seriously. Therefore, before interacting with our API, please check if your client supports the protocols and security features we require. ## HTTPS (TLS) A secure connection is enforced. Please always connect to the Sendcloud API using HTTPS. We only support TLSv1.2 and higher, as lower versions are no longer considered secure. This means that SSLv3 and SSLv2 are also not supported. ### Certificate Our certificate is signed by Amazon Root CA. Most operating systems and clients have built-in support for automatically verifying these certificates. In case yours doesn't, you can add the [AWS CA](https://docs.aws.amazon.com/privateca/latest/userguide/PCACertInstall.html) to your list of trusted Certificate Authorities (CA). Note that our API's server certificate is rotated regularly and it is therefore not recommended to pin our certificate instead. ### Supported TLS Ciphers A cipher suite is a set of algorithms that help secure a TLS connection. The Sendcloud API supports the following ciphers: * `TLS_AES_128_GCM_SHA256` * `TLS_AES_256_GCM_SHA384` * `TLS_CHACHA20_POLY1305_SHA256` * `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256` * `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384` * `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256` ## HTTP version The Sendcloud API supports both `HTTP/1.1` and `HTTP/2`. `HTTP/3` is not (yet) supported. `HTTP/1.0` is not supported. ## `GET` requests that include a body The Sendcloud API does not support `GET` requests that include a body. If a `GET` request includes a body, the server will respond with HTTP status code `403 (Forbidden)`. ## IP version Currently our API is only available using IPv4. # API user flows Source: https://sendcloud.dev/docs/getting-started/api-user-flows Here we outline common user flows when using the Sendcloud APIs. For an explanation of the terms used, visit the [Glossary](/docs/getting-started/glossary/). ## API v3 user flows ### Standard shipment creation flow (Shipments API v3) ```mermaid placement="top-right" theme={null} %%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%% flowchart TD A([Start]) --> B("Call the Shipping Option API v3 to get a desired Shipping Option Code

POST /api/v3/shipping-options") B --> C("Create parcel payload with desired shipping_option_code") C --> D{"Do you want your labels to be created synchronously?"} D -- No --> E("Create and announce a shipment asynchronously

POST /api/v3/shipments") D -- Yes --> F("Create and announce a shipment synchronously

POST /api/v3/shipments/announce") E --> G("Call Parcel Document API v3 with the id of Parcel

GET /api/v3/parcels/{id}/documents/label") F --> H{"Did you announce a multicollo shipment?"} H -- Yes --> G H -- No --> I("Retrieve label from response") G --> I I --> J([Stick label on parcel and hand it to carrier]) click B "/api/v3/shipping-options/return-a-list-of-available-shipping-options" _blank click E "/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously" _blank click F "/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously" _blank click G "/api/v3/parcel-documents/retrieve-a-parcel-document" _blank ``` 1. **Choose a shipping option**: Retrieve available shipping options using [`POST /api/v3/shipping-options`](/api/v3/shipping-options/return-a-list-of-available-shipping-options) to get carrier services with their `shipping_option_code` values. 2. **Create the parcel payload**: Assemble your shipment payload with the desired `shipping_option_code`, along with sender address, recipient details, parcel dimensions, and weight. 3. **Choose synchronous or asynchronous announcement**: Decide whether labels should be created immediately (synchronous) or in the background (asynchronous). * **Asynchronous path**: Use [`POST /api/v3/shipments`](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) which returns a `parcel_id` for later label retrieval via the [Parcel Document API](/api/v3/parcel-documents/retrieve-a-parcel-document). * **Synchronous path**: Use [`POST /api/v3/shipments/announce`](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) which returns the label immediately in the response. 4. **Handle multicollo shipments**: If you announced a multicollo shipment (multiple parcels announced together to stay linked throughout delivery), you must retrieve individual labels using the `GET /api/v3/parcels/{id}/documents/label` endpoint for each parcel in the shipment. 5. **Apply the label**: Extract the label from the API response. Print the label, affix it to the parcel, and hand it to the carrier via pickup or drop-off. Need more information on this flow? Visit [Shipments API Overview](/docs/shipments) to learn more. ### Shipping orders from E-commerce platforms ```mermaid placement="top-right" theme={null} %%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%% flowchart TD A([Start]) --> B("Call Order API v3 to get an Order that has already been imported into Sendcloud

GET /api/v3/orders") B --> C("Create the payload") C --> D{"Do you want to ship multiple orders in one API call?"} D -- yes --> E("Call Ship-an-Order API v3

POST /api/v3/orders/create-labels-async") D -- no --> F("Call Ship-an-Order API v3

POST /api/v3/orders/create-label-sync") E --> G("Retrieve id of created Parcels from the response") G --> H("Call Parcel Documents API v3 with the retrieved parcel_id

GET /api/v3/parcels/{id}/documents/label") H --> I("Retrieve a binary file from the response") F --> J("Retrieve a Base64 encoded file from the response") I --> K([Stick the label on parcel and hand it to carrier]) J --> K click B "/api/v3/orders/retrieve-a-list-of-orders" _blank click E "/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously" _blank click F "/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously" _blank click H "/api/v3/parcel-documents/retrieve-a-parcel-document" _blank ``` 1. **Fetch an imported order**: Retrieve an order that was synced from your e-commerce platform using [`GET /api/v3/orders`](/api/v3/orders/retrieve-a-list-of-orders). 2. **Create the payload**: Assemble your payload with the order information and shipping preferences. 3. **Choose batch or single shipment**: Decide whether to ship multiple orders in one API call (batch processing) or ship one order at a time. 4. **Ship the order(s)**: * **Multiple orders (async)**: Use [`POST /api/v3/orders/create-labels-async`](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) which returns `parcel_id` values for each created parcel. * **Single order (sync)**: Use [`POST /api/v3/orders/create-label-sync`](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) which returns a Base64 encoded label immediately. 5. **Retrieve labels for batch shipments**: For async/batch processing, call [`GET /api/v3/parcels/{id}/documents/label`](/api/v3/parcel-documents/retrieve-a-parcel-document") with each `parcel_id` to retrieve binary label files. 6. **Apply the label**: Extract the label (Base64 or binary), print it, affix it to the parcel, and hand it to the carrier. Need more information on this flow? Visit [Orders API Overview](/docs/orders) to learn more. ### Announcing a multicollo parcel ```mermaid placement="top-right" theme={null} %%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%% flowchart TD A([Start]) --> B("Call the Shipping Option API v3 to get a desired Shipping Option Code

POST /api/v3/shipping-options") B --> C("Create shipment payload with the desired shipping_option_code") C --> D("Call Shipments API v3 with multiple parcel objects

POST /api/v3/shipments/announce") D --> E("Call Parcel Document API v3 with the parcel ID as many times as needed to get all labels
GET /api/v3/parcels/{id}/documents/{type}") E --> F("Retrieve label from the response") F --> G([Stick the label on the parcel and hand it to carrier]) click B "/api/v3/shipping-options/return-a-list-of-available-shipping-options" _blank click D "/api/v3/shipments/create-and-announce-a-shipment-synchronously" _blank click E "/api/v3/parcel-documents/retrieve-a-parcel-document" _blank ``` 1. **Choose a shipping option**: Retrieve available shipping options using [`POST /api/v3/shipping-options`](/api/v3/shipping-options/return-a-list-of-available-shipping-options) to get carrier services with their `shipping_option_code` values. 2. **Create the multicollo shipment payload**: Assemble your payload with the desired `shipping_option_code` and include multiple parcel objects in a single shipment. This creates a multicollo shipment where all parcels stay linked for the customer's tracking purposes throughout delivery. 3. **Announce the multicollo shipment**: Use [`POST /api/v3/shipments/announce`](/api/v3/shipments/create-and-announce-a-shipment-synchronously) with your array of parcel objects. This returns an array of `parcel_id` values, one for each parcel in the multicollo shipment. 4. **Retrieve labels for each parcel**: Call [`GET /api/v3/parcels/{id}/documents/{type}`](/api/v3/parcel-documents/retrieve-a-parcel-document) once for each `parcel_id` to retrieve individual label files. Each parcel in the multicollo shipment requires its own label. 5. **Apply labels to parcels**: Extract each label from the responses, print them, affix each label to its corresponding parcel. In some cases certain parcels in the shipment may have to be shipped at a later date (e.g., limited stock) so coordinate with the carrier accordingly. Need more information on this flow? Visit the [Multicollo guide](/docs/shipments/multicollo) in the Shipments API section to learn more. ### Shipping a parcel as a white-label product in the marketplace Use this flow to ship a parcel under your own branding. To get started: ```mermaid placement="top-right" theme={null} %%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%% flowchart TD A([Start]) --> B("Call the Shipping Option API v3 to get the desired shipping option

POST /api/v3/shipping-options") B --> C("Call the Brands API v2 to get a desired brand ID
GET /api/v2/brands") C --> D("Create parcel payload with the shipping_option_code and brand_id") D --> E("Create shipment

POST /api/v3/shipments/announce") E --> F("Retrieve label from the response") F --> G("Affix label and hand to carrier") G --> H("Status of the parcel updates along its journey") H --> I([Sendcloud sends branded notification via your selected channels e.g., email, WhatsApp, tracking page, or SMS]) click B "/api/v3/shipping-options/return-a-list-of-available-shipping-options" _blank click C "/api/v2/brands/retrieve-a-list-of-brands" _blank click E "/api/v3/shipments/create-and-announce-a-shipment-synchronously" _blank ``` 1. **Choose a shipping option**: Retrieve available shipping options using [`POST /api/v3/shipping-options`](/api/v3/shipping-options/return-a-list-of-available-shipping-options) to get carrier services with their `shipping_option_code` values. 2. **Choose your brand**: Retrieve your configured brands using [`GET /api/v2/brands`](/api/v2/brands/retrieve-a-list-of-brands) and select the `brand_id` to apply to this shipment. Brands customize customer-facing features like tracking pages and notifications. 3. **Create the parcel payload**: Combine your chosen `shipping_option_code` and `brand_id` in the parcel payload along with sender address, recipient details, and parcel dimensions. 4. **Announce the shipment**: Use [`POST /api/v3/shipments/announce`](/api/v3/shipments/create-and-announce-a-shipment-synchronously) to create and announce the shipment with the carrier, which returns the label. 5. **Apply the label**: Print the label from the response, affix it to the parcel, and hand it to the carrier via pickup or drop-off. 6. **Tracking with branded notifications**: Once the carrier scans the parcel and updates its status, Sendcloud automatically sends tracking notifications via your chosen channels (email, WhatsApp, tracking page, or SMS) under your selected brand. No further API calls needed. ### Setting up event subscriptions To start receiving real-time parcel event notifications via the [Event Subscriptions API](/api/v3/event-subscriptions/index) (BETA): ```mermaid placement="top-right" theme={null} %%{init: {'flowchart': {'defaultRenderer': 'elk', 'nodeSpacing': 25, 'rankSpacing': 30, 'padding': 4}}}%% flowchart TD A([Start]) --> B("Create a connection

POST /api/v3/event-subscriptions/connections") B --> C("Create a subscription

POST /api/v3/event-subscriptions/subscriptions") C --> D("Test event delivery

POST /api/v3/event-subscriptions/broadcast/test/{subscription_id}") D --> E([Start receiving live events]) click B "/api/v3/event-subscriptions/list-connections" _blank click C "/api/v3/event-subscriptions/create-a-subscription" _blank click D "/api/v3/event-subscriptions/test-event-delivery" _blank ``` 1. **Create a connection**: Define where events should be delivered (e.g. a webhook URL or Klaviyo integration) using the [Create a connection](/api/v3/event-subscriptions/create-a-connection) endpoint. 2. **Create a subscription**: Specify which events to listen for and link them to your connection using the [Create a subscription](/api/v3/event-subscriptions/create-a-subscription) endpoint. 3. **Test your setup**: Verify that events are delivered correctly by using the [Test event delivery](/api/v3/event-subscriptions/test-event-delivery) (`/broadcast/test/{subscription_id}`) endpoint. # API version guide Source: https://sendcloud.dev/docs/getting-started/api-version-guide There are two versions of the Sendcloud API: **API v2** and **API v3**. **API v3** is our latest version and is receiving active updates, with new features and improvements over API v2. **API v2** is our legacy API and is entering maintenance mode. It is still available for existing users but will not receive new features. For new users, we recommend starting with API v3 to make use of the latest features and improvements. If you need help with moving to API v3, check out our [migration guide](/docs/getting-started/migration-guidelines-for-api-v3). ## What does maintenance mode mean for API v2? API v2 is starting to enter **maintenance mode** as of April 2026, which means: * Endpoints that enter maintenance mode are closed to new users. New users should use API v3 instead. * There is an exception for Sendcloud Partners, who may still use API v2 for new accounts. If you are a Sendcloud Partner, ensure you pass the `Sendcloud-Partner-Id` header to your requests. * **Existing integrations remain fully functional.** If you are using API v2 and your Sendcloud account was created before April 2026, you can continue to use it without interruption. It is still possible to rotate your API keys and create new API integrations for users who created their Sendcloud account before April 2026. ### Endpoints in maintenance mode Currently, only the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint in the [Parcels API v2](/api/v2/parcels) is in maintenance mode and therefore closed to new users. Other v2 APIs are still available for new users, but we recommend using API v3 for all new integrations to benefit from the latest features and improvements. # Authentication Source: https://sendcloud.dev/docs/getting-started/authentication ## Before you begin Before you can start making requests towards Sendcloud APIs, [register a Sendcloud account](/docs/getting-started), and [obtain your Public and Secret API keys](/docs/getting-started/how-to-create-your-api-keys) in order to authenticate your requests. When adding an API integration in the Sendcloud platform, take a look at the following settings: * **Service Points**: allows the API integration to be used in `servicepoint.sendcloud.sc` API. * **Use OAuth2 authentication**: enforces the integration to use OAuth2 authentication instead of basic, otherwise it fails. OAuth2 authentication is currently available as a beta feature for a limited number of clients. ## Basic Authentication Sendcloud uses [Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication) for authenticating requests for APIs, where your username is your **Public Key** and your password is your **Private Key** as provided for your integration. Do not share your Private API keys in publicly accessible areas such as GitHub, client-side code, etc. ### Authenticating your requests Once you have obtained your Public and Private keys, start authenticating your requests. To do this, include your keys in your requests. ```sh Example request using curl theme={null} curl --location 'https://panel.sendcloud.sc/api/v2/parcels' \ --header 'Accept: application/json' \ --header 'Authorization: Basic ' ``` The `Authorization` header value is constructed by combining the API keys (base64-encoded) separated by a colon (`:`). While this example uses `curl`, you can use any programming language or HTTP client that supports setting HTTP headers to make authenticated requests to the Sendcloud API. ## OAuth2 authentication (beta) OAuth2 authentication is currently available as a beta feature for a limited number of clients. Following this beta phase, we are planning a gradual rollout of the OAuth2 authentication feature to all users. Our aim is to ensure a smooth transition and to continue providing an optimal user experience throughout the process. [OAuth2](https://en.wikipedia.org/wiki/OAuth) provides a token-based authentication mechanism. Obtain an access token by authenticating with the OAuth2 server, then include the obtained token in the `Authorization` headers of your API requests. To generate an API integration for OAuth2, tick the **Use OAuth2 authentication** checkbox when [creating it in the Sendcloud platform](https://app.sendcloud.com/v2/settings/integrations/manage). ```sh Example request using curl theme={null} # Generate an OAuth2 access token curl -X POST --location "https://account.sendcloud.com/oauth2/token" \ --header "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&scope=api" \ --basic --user your_sendcloud_public_key:your_sendcloud_private_key ``` The response for the above request will be similar to the following: ```json Response body theme={null} { "access_token": "ory_at_dK...", "expires_in": 3599, "scope": "api", "token_type": "bearer" } ``` This request returns an `access_token`, which you can use in subsequent API requests: ```sh Example request using curl theme={null} # Make a request to the Sendcloud API using OAuth2 authentication curl --location "https://panel.sendcloud.sc/api/v2/user" \ --header "Authorization: Bearer ${access_token}" ``` # Creating test labels Source: https://sendcloud.dev/docs/getting-started/creating-test-labels You can test Sendcloud APIs without running the risk of being charged for any shipping labels you create in the process. There are two methods of creating test labels: 1. Create a test label using the Sendcloud shipping option **Unstamped letter**. You won't be charged for any shipments which are created using this method. 2. Create a label and cancel it within the deadline ## Method 1: create a test label using the Unstamped letter shipping option The shipping option **Unstamped letter** is a Sendcloud option which allows you to create test labels via the [Shipments API](/api/v3/shipments) without being charged. It's not possible to use the **Unstamped letter** shipping option or the Shipments API to create **returns**. To test returns creation, you should use a suitable return shipping option with the [Returns API](/api/v3/returns) and then [cancel the label before the cancellation deadline](/docs/shipping/cancel-a-label/). If you're creating a number of test parcels, you may find it helpful to set **Unstamped letter** as your [default shipping option](https://support.sendcloud.com/hc/en-us/articles/12213808740116-How-to-set-up-your-default-shipping-settings) in your Sendcloud account settings. You can specify the shipping option **Unstamped letter** in your [Shipments API](/api/v3/shipments) requests within the `ship_with` object. Note that the `shipping_option_code` for this method is `sendcloud:letter` at the time of writing. ```json Example request body theme={null} { "ship_with": { "type": "shipping_option_code", "properties": { "shipping_option_code": "sendcloud:letter" } } // ... other shipment fields } ``` ## Method 2: create a label and cancel it within the deadline When you want to test outgoing or return shipment creation, and the “Unstamped letter” shipping option isn't applicable, it's possible to create shipping labels and then cancel them within the cancellation deadline. Find out how to cancel a label before the cancellation deadline **Not all carriers support cancellation requests**. Carefully consult the list of carriers [in our help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment-) before you request a label for a particular shipping option to be sure that cancellation is possible. # Glossary Source: https://sendcloud.dev/docs/getting-started/glossary Below is a list of definitions that are referred to throughout our API documentation in relation to integrations, data models and carrier services. | Term | Definition | | --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Announcement** | The process of registering a shipment with a carrier. A successful announcement results in a tracking number and a shipping label being returned. | | **Brand** | A configurable entity used to customize customer-facing features such as tracking pages, tracking notifications, and return portals. Brands are linked to sender addresses and are automatically applied to parcels created from those addresses. | | **Carrier contract** | A direct agreement between a sender and a carrier that defines negotiated shipping rates and services. Connected carrier contracts allow Sendcloud to generate shipping and return labels using the sender’s own pricing. | | **Collo** | The count of parcels in a shipment. | | **Drop-off** | The act of handing a parcel over to a service point to be collected and delivered by a carrier. | | **Integration** | An online platform, such as an e-commerce Platform, WMS, Marketplace, ERP or custom-built interface that is connected to Sendcloud. | | **Label** | A physical document generated after a shipment is announced to a carrier, which must be affixed to each parcel before handover. It contains the routing, identification, and tracking information required by the carrier network. | | **Multicollo** | A shipment containing multiple parcels which are announced at the same time so that they stay together throughout the delivery journey. Linked parcels are represented on the shipping label. | | **Orders** | Represents the commercial details of a purchase, including what was sold, customer information, and delivery addresses. Orders are typically created in upstream systems and synced to Sendcloud, where they can be updated until prepared for fulfillment. | | **Pack & Go** | Sendcloud feature designed to facilitate an easier picking and packing process by allowing orders to be processed via a barcode scanner and/or picking lists and packing slips. | | **Parcel** | A parcel is a single physical package within a shipment that is handed over to a carrier. It contains the information required to generate a shipping label and enable tracking, such as weight, dimensions, contents, insurance values, and carrier-specific instructions. A parcel typically has a shipping label linked to it. | | **Pickup** | The act of a carrier collecting parcels (usually in bulk) from a specified location, such as a warehouse or brick-and-mortar store. | | **Return method** | The method by which a customer returns a parcel, such as pickup, in-store return, drop-off at a service point, or labelless return. Return methods determine how the return is initiated, labeled, and handed over to the carrier. | | **Return rules** | Automation rules that can be created in the Sendcloud platform to automatically apply actions to return parcels created through the Return portal or Return portal API based on pre-set conditions. | | **Sendcloud platform** | The [Sendcloud platform](https://app.sendcloud.com) is where you can configure settings, process orders and access core features through our user interface. | | **Sender address** | A configured ship-from address that defines where a parcel is sent from and where it should be returned if delivery fails. Sender addresses are required for label creation and influence available shipping methods and rates. | | **Service point** | A physical location affiliated with one or more specific carriers, where parcels can be dropped off or collected. Return parcels are typically dropped off at a service point by a customer to be shipped back to the sender. Also called: Parcel shop, Drop-off point | | **Shipments** | Represents the fulfillment of an order, defining how items are shipped, including the carrier, service level, and delivery preferences. A shipment may contain one or more parcels and is used for carrier communication, label generation, and tracking. | | **Shipping functionality** | An additional service attached to a shipping method which specifies additional handling required by a parcel, the type of parcel that’s accepted for delivery or a specific delivery deadline. An example of a shipping functionality would be *Signature required* or *Delivery within 24h*. | | **Shipping method** (**Shipping option** in API v3) | A specific carrier service used to deliver a parcel, defining how and at what rate it is shipped. Shipping methods are a subset of a shipping product and determine factors such as delivery speed, weight limits, and service type. In API v3, this concept is referred to as a **shipping option**. | | **Shipping option** | See **Shipping method**. This term is used in API v3 to refer to a carrier shipping service. | | **Shipping product** | An overarching collection of shipping methods which are grouped together based on shared characteristics. Represents the service offerings of a carrier. An example of a shipping product would be PostNL Standard. | | **Shipping rates** | The prices charged by a carrier to ship a parcel, based on factors such as sender address, destination, weight, dimensions, service level, and carrier contract. | | **Shipping rules** | Automation rules that can be created in the Sendcloud platform to automatically apply actions to orders and shipments based on pre-set conditions. | | **Tracking** | The process of receiving status updates to indicate the progress of a parcel from the point of label creation to the point of delivery. | | **Tracking notifications** | Customisable tracking emails which you can configure in Sendcloud to send automatic updates to your customer every time their parcel reaches a delivery milestone. | # How the Sendcloud APIs work Source: https://sendcloud.dev/docs/getting-started/how-the-sendcloud-apis-work Sendcloud APIs are **RESTful** and communicate over HTTPS using standard HTTP methods: * `GET` to retrieve data * `POST` to create resources * `PATCH` or `PUT` to update resources * Action endpoints (for example, cancel or announce) Requests and responses use JSON unless stated otherwise. You can integrate using: * your own backend or HTTP client * [cURL](https://curl.se/) * API tools such as [Postman](https://www.postman.com/) or [Bruno](https://www.usebruno.com/) Sendcloud does not require SDKs — you're free to use whatever language or framework you prefer. # How to create your API keys Source: https://sendcloud.dev/docs/getting-started/how-to-create-your-api-keys 1. Log in to your Sendcloud account and go to [Integrations](https://app.sendcloud.com/v2/settings/integrations/manage) 2. Find **Sendcloud API** in the list of integrations and click **Connect** 3. Enter a name for the API integration and click **Save** 4. An API Public and Secret Key will be automatically generated 5. Your **username** when authenticating with the API is your **Public Key**, and your **password** is your **Secret Key** # Quickstart Source: https://sendcloud.dev/docs/getting-started/index Before you can begin interacting with our APIs, you first need to [create a Sendcloud account](https://account.sendcloud.com/signup/) and complete the basic account setup. 1. Follow the steps in [Getting started with Sendcloud](https://support.sendcloud.com/hc/en-us/articles/360024833452-Getting-started-with-Sendcloud-) to set up your account, add an invoice address, and add a [sender address](/docs/getting-started/sender-addresses/). 2. [Enable some carriers](https://support.sendcloud.com/hc/en-us/articles/360025133311-Choose-your-carriers-) in your Sendcloud account 3. [Connect a direct carrier contract](/docs/getting-started/carrier-contracts/) (optional) 4. [Create your API keys](/docs/getting-started/how-to-create-your-api-keys/) to start making API requests. ## Integrating with Sendcloud APIs You can integrate with our APIs in various ways, depending on your specific needs. Sendcloud provides plug-and-play integrations with 100+ of the most [popular e-commerce systems](https://www.sendcloud.com/integrations/). If your online store is already supported by our pre-built plugins then you can easily connect it to Sendcloud and begin taking advantage of our hassle-free shipping solutions by following the appropriate [integration guideline](https://support.sendcloud.com/hc/en-us/categories/360001557291-Integrations). If you're looking to automate your current workflow, then our APIs provide you access to our core shipping products and features that are normally available through our UI interface ([Sendcloud platform](https://app.sendcloud.com/)). Start building with our APIs ## Postman The fastest way to begin testing and experimenting with our APIs is to grab one of our [Postman collections](https://www.postman.com/sendcloud-api). If you're new to Postman, you can read the [relevant guides](https://learning.postman.com/docs/getting-started/introduction/) on how to set it up and start developing with Sendcloud APIs in a matter of minutes! Quickly onboard with our Postman collections ## API tutorials 1. Learn how to make an API call to [create your first shipment](/docs/shipping/create-a-parcel) 2. [Retrieve and compare rates](/docs/shipping/shipping-rates) across an extensive list of shipping options and choose the one that best suits you 3. Now that you've created your parcel it's time to [download your label](/docs/shipping/create-a-parcel). 4. Create a [return parcel](/docs/returns/return-portal) from anywhere in the world through the [Returns API](/api/v3/returns/) 5. [Track the status of your parcel](/docs/parcel-tracking) via our Parcel tracking API ## Need a little help? If you have additional questions or want to reach out to our support please visit this Help Center article to learn more. # Key concepts Source: https://sendcloud.dev/docs/getting-started/key-concepts ## Orders In Sendcloud, an order represents the commercial side of a purchase — it captures what was sold, to whom, and where it needs to be delivered. An order's structure typically includes: * Unique order ID and timestamps * Customer details and contact information * Billing and shipping addresses * Line items (products, quantities, and prices) * Payment details and totals * Source metadata (e.g. webshop, marketplace, ERP, or custom backend) From an API perspective, the order contains all data required to prepare a [shipment](#shipments). Orders are usually created in your upstream systems and synced to Sendcloud through the Orders API. While in the preparation phase, orders remain editable — allowing you to correct addresses, adjust contents, or update statuses before fulfillment begins. ## Shipments A shipment represents the operational step where an [order](#orders) is prepared for fulfillment — defining how the items will be shipped. When creating a shipment, you determine: * The carrier and service level to use * How many physical parcels are included * Which shipping rules or defaults apply * Branding, contracts, and delivery preferences Shipments are created via the [Shipments API](/api/v3/shipments) or directly from an order with the [Ship an Order API](/api/v3/ship-an-order). This is also where Sendcloud's automation engine (Shipping Rules and Defaults) can be applied to streamline configuration. Within a single shipment, multiple parcels may exist. A parcel represents each physical package handed to the carrier and typically includes: * Weight and dimensions * Contents and insurance values * Label notes or carrier-specific instructions This separation allows Sendcloud to model both single-package and multi-package (multi-collo) shipments accurately. Each parcel can be configured independently, giving you full control over how items are packaged and shipped. Once a shipment is created, it becomes trackable and forms the basis for all communication with carriers. ## Labels After a shipment has been successfully announced to the carrier, shipping labels are generated for its parcels. A label is the physical document that must be affixed to each parcel before it's handed over to the carrier. It contains essential routing and tracking data used by the carrier network. Example label ## Event subscriptions Event subscriptions allow you to receive real-time notifications when parcel events occur, such as status changes or delivery milestones. The model has two parts: * **Connections** define where events are delivered — for example, a webhook URL or a Klaviyo integration. * **Subscriptions** define which events to listen for and link them to a connection. You can manage event subscriptions programmatically via the [Event Subscriptions API](/api/v3/event-subscriptions/index). The Event Subscriptions API is currently in **BETA**. ## How the concepts fit together * Orders capture the commercial intent — what was sold, to whom, and where it should go. * Shipments define the fulfillment plan — how the goods are shipped, which carrier is used, and how many packages are involved. * Labels are the carrier-authorized documents required to dispatch the physical packages. * Event subscriptions let you react to parcel events in real time by pushing notifications to your systems. You can use these layers together or independently, depending on your integration design: * Direct shipment creation: If your system already handles orders, you can create shipments directly in Sendcloud. Labels can then be generated to complete the process. * Order-driven flow: Sync commercial order data first, then convert orders into shipments when you're ready to fulfill. * Event-driven automation: Subscribe to parcel events to trigger downstream workflows — such as updating order statuses, notifying customers, or syncing with third-party platforms. This flexible model keeps commercial, operational, and logistical details neatly separated — while allowing you to automate the complete shipping lifecycle through the API, with full visibility and manual control in the Sendcloud platform. # MCP server Source: https://sendcloud.dev/docs/getting-started/mcp-server Connect AI agents and assistants to the Sendcloud Public API v3 through the Model Context Protocol. The Sendcloud **MCP server** exposes the [Public API v3](/api/v3) to AI assistants and agents through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/). Every API operation (for example creating shipments, listing orders, tracking parcels, and more) is available as a **tool** your MCP client can call, so an agent can act on your Sendcloud account in natural language without you writing any HTTP code. It is an *aggregated* server: a single endpoint that bundles every Public API v3 domain as a separate **toolset**. You connect once and get access to all of them, or narrow the connection to just the toolsets you need. This page describes how to **use** the MCP server as an agent or MCP client. For the underlying endpoints and schemas, see the [API v3 reference](/api/v3). ## Endpoint | | | | ------------------ | ------------------------------- | | **MCP URL** | `https://mcp.sendcloud.com/mcp` | | **Transport** | Streamable HTTP | | **Authentication** | OAuth 2.0 (bearer token) | The server speaks the standard MCP protocol over HTTP, so any MCP-compatible client (for example Claude, Claude Code, Cursor, or your own agent built on an MCP SDK) can connect to it. **Before you connect – please read.** **Results are reference information only.** This connector lets your AI assistant read data already available to you via the Sendcloud API (e.g. shipment status, tracking, rates, order details). That data reflects a snapshot at the time your AI assistant made the request and can change afterwards – for example, carrier surcharges, tracking status, and delivery estimates update over time. Do not treat a response from your AI assistant as a confirmed or binding figure; for anything time-sensitive or in dispute (e.g. a surcharge query), check your Sendcloud account directly or contact Sendcloud support. **Sendcloud does not control your AI assistant's output.** We cannot control, and are not responsible for, how your chosen AI assistant interprets, summarises, or responds to this data, including any follow-up questions or attempts to get it to “confirm” a figure. **You choose the AI tool.** You are solely responsible for selecting the AI assistant you connect to this feature. Sendcloud does not select, endorse, or control that AI provider, and has no visibility into or control over how it subsequently stores, uses, or discloses the data it receives – that is governed by your own agreement with that provider, not by Sendcloud. By connecting, you confirm you have read and accept the above. ## Connecting Point your client at the MCP URL. For example, with the Claude Code CLI: ```bash theme={null} claude mcp add --transport http sendcloud https://mcp.sendcloud.com/mcp ``` Other clients (Cursor, Claude Desktop, custom agents) accept the same URL in their MCP server configuration. A typical JSON config looks like: ```json theme={null} { "mcpServers": { "sendcloud": { "type": "http", "url": "https://mcp.sendcloud.com/mcp" } } } ``` The first time your client connects, it discovers the authorization server automatically (via [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728) protected-resource metadata) and walks you through an OAuth 2.0 sign-in at `account.sendcloud.com`. After you approve access, the client stores the resulting token and attaches it to every tool call. Your credentials live in the MCP client, never in the server. See [Authentication](/docs/getting-started/authentication) for how Sendcloud OAuth 2.0 works. Once connected, the client lists the available tools. Ask the agent to perform a task (for example *"list my most recent orders"* or *"track parcel 123456789"*) and it selects and calls the matching tool, forwarding the request to the Public API v3 and returning the response. ## Selecting toolsets By default the server exposes **all** toolsets. To limit a connection to a subset (for example keeping the agent's tool list focused and relevant) add a `?toolsets=` query parameter with a comma-separated list of toolset names: ```bash theme={null} # Only the orders and shipments tools claude mcp add --transport http sendcloud "https://mcp.sendcloud.com/mcp?toolsets=orders,shipments" ``` The filter applies to both tool discovery and tool calls: a tool outside the selected toolsets is hidden from the list *and* rejected if called directly. ## Available toolsets Each toolset maps to one Public API v3 domain. | Toolset | What it covers | | --------------------- | -------------------------------------------------------------------- | | `analytics` | Carrier and shipping-option transit times | | `brands` | Brands configured on your account | | `carriers-dp` | Carrier delivery-point order finalization | | `compat` | Compatibility shipping-options endpoint | | `contracts` | Carrier contracts and their schemas | | `duties-and-taxes` | Duties and taxes calculations | | `dynamic-checkout` | Checkout delivery options | | `event-subscriptions` | Webhook subscriptions and connections | | `integrations` | Integrations, logs, and order-status mappings | | `orders` | Create, list, retrieve, update, and delete orders | | `organization` | Organization metadata | | `parcel-documents` | Retrieve parcel documents | | `parcel-statuses` | Parcel status definitions | | `parcel-tracking` | Register and retrieve tracking | | `pickups` | Schedule and retrieve pickups | | `reporting` | Parcel reports | | `returns` | Create, validate, and manage returns | | `sender-addresses` | Sender addresses | | `service-points` | Service-point lookup and availability | | `ship-an-order` | Create labels for orders (sync and async) | | `shipments` | Create, announce, cancel, and retrieve shipments; validate addresses | | `shipping-options` | Fetch shipping options and quotes | | `store-locations` | Store-location management | | `support` | Support tickets, carrier contacts, and documents | | `user` | User authentication metadata | ## How tools map to the API Each tool corresponds to one HTTP operation. The tool name is derived from the operation's `operationId`, and is **namespaced by toolset** to avoid collisions — for example `orders_sc_public_v3_orders_get_list_orders` (list orders) or `shipments_sc_public_v3_scp_get_shipment_by_id` (retrieve a shipment). The operation's path, query, and header parameters — plus the request-body fields — become the tool's arguments. Required API parameters stay required on the tool. Tools are annotated with hints about their effect, derived from the HTTP method: read-only (`GET`), idempotent, or destructive (`DELETE`, `POST`). MCP clients use these to auto-confirm safe lookups while prompting you before a tool that creates, cancels, or deletes data. Tools that create or cancel shipments act on your live account. As with the API directly, you may be invoiced for shipments you create if they aren't cancelled within the cancellation deadline. ## Next steps How Sendcloud OAuth 2.0 works The endpoints behind every MCP tool # Migration guidelines for API v3 Source: https://sendcloud.dev/docs/getting-started/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](/api/v2/parcels/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](/api/v2/integrations/create-a-list-of-shipments) endpoint\* in the Integrations API | Use the [Create/update orders in batch](/api/v3/orders/create-update-orders-in-batch) endpoint in the Orders API | | Get a list of incoming orders | Use the [Retrieve a list of shipments](/api/v2/integrations/retrieve-a-list-of-shipments) endpoint in the Integrations API | Use the [Retrieve a list of orders](/api/v3/orders/retrieve-a-list-of-orders) endpoint in the Orders API | | Get a specific order | Use the [Retrieve a list of shipments](/api/v2/integrations/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](/api/v3/orders/retrieve-an-order) endpoint in the Orders API | | Update an order | Update an **unannounced** parcel using the [Update a parcel](/api/v2/parcels/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](/api/v2/integrations/create-a-list-of-shipments) endpoint\* in the Integrations API | Use the [Update an order](/api/v3/orders/update-an-order) endpoint in the Orders API | | Delete or cancel an order | Use the [Delete a shipment](/api/v2/integrations/delete-a-shipment) endpoint in the Integrations API | Use the [Delete an order](/api/v3/orders/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](/api/v2/parcels/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](/api/v3/ship-an-order/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](/api/v3/ship-an-order/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](/api/v2/integrations/retrieve-a-list-of-integrations) endpoint in the Integrations API (v2) | Use the [Retrieve a list of integrations](/api/v3/integrations/retrieve-a-list-of-integrations) endpoint in the Integrations API (v3) | | Get the settings for one specific integration | Use the [Retrieve an integration](/api/v2/integrations/retrieve-an-integration) endpoint in the Integrations API (v2) | Use the [Retrieve an integration](/api/v3/integrations/retrieve-an-integration) endpoint in the Integrations API (v3) | | Update integration settings (full) → replace all settings | Use the [Update an integration](/api/v2/integrations/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](/api/v2/integrations/partially-update-an-integration) endpoint in the Integrations API (v2) | Use the [Update certain parts of an integration](/api/v3/integrations/update-certain-parts-of-an-integration) endpoint in the Integrations API (v3) | | Delete an integration | Use the [Delete an integration](/api/v2/integrations/delete-an-integration) endpoint in the Integrations API (v2) | Use the [Delete an integration](/api/v3/integrations/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](/api/v2/integrations/retrieve-all-integration-exception-logs)
  • [Retrieve exception logs for a specific integration](/api/v2/integrations/retrieve-exception-logs-for-a-specific-integration)
  • [Create integration exceptions logs](/api/v2/integrations/create-integration-exception-logs)
| 🚫 Not supported | | Get shop order statuses (for the Prestashop v2 integration only) | 🚫 Not supported | Use the [Retrieve shop order statuses for an integration](/api/v3/integrations/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](/api/v3/integrations/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](/api/v3/integrations/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](/api/v3/integrations/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](#address-fields) * [Customs fields](#customs-fields) * [Sender address fields](#sender-address-fields) * [Shipment/Parcel fields](#shipment/parcel-fields) * [Shipping methods vs. Shipping products vs. Shipping prices vs. Shipping options 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](/api/v2/parcels/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](/api/v3/shipments/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](/api/v2/parcels/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](/api/v3/shipments/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](/api/v2/parcels/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](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-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](/api/v2/parcels/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](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously) endpoint in the Shipments API | | Create multiple parcels at once | Use the [Create a parcel or parcels](/api/v2/parcels/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](/api/v2/parcels/create-a-parcel-or-parcels) endpoint in the Parcels API, setting `quantity` to a number greater than 1 | Use any [Shipments API](/api/v3/shipments) `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](/api/v2/labels/retrieve-pdf-labels-for-a-label-printer)
  • [Retrieve a specific PDF label for a label printer](api/v2/labels/retrieve-a-specific-pdf-label-for-a-label-printer)
  • [Retrieve parcel documents](/api/v2/parcel-documents/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](/api/v3/parcel-documents/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](/api/v3/shipments/create-and-announce-a-shipment-synchronously) or [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously) (for **single-collo** shipments only)
| | Retrieve your label after announcement - ZPL/PNG label | [Retrieve parcel documents](/api/v2/parcel-documents/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](/api/v3/parcel-documents/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](/api/v3/shipments/create-and-announce-a-shipment-synchronously) or [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-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](/api/v2/parcels/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](/api/v2/parcels/retrieve-a-parcel) or [Retrieve parcels](/api/v2/parcels/retrieve-parcels) endpoints in the Parcels API, and check the errors object
| Use one of these options:
  • [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) or [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-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](/api/v3/shipments/retrieve-a-shipment) or [Retrieve shipments](/api/v3/shipments/retrieve-shipments) endpoints in the Shipments API, and check the errors object
| | List your parcels | Use the [Retrieve parcels](/api/v2/parcels/retrieve-parcels) endpoint in the Parcels API | Use the [Retrieve shipments](/api/v3/shipments/retrieve-shipments) endpoint in the Shipments API | | Get a specific parcel | Use the [Retrieve a parcel](/api/v2/parcels/retrieve-a-parcel) endpoint in the Parcels API | Use the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint in the Shipments API | | Update your parcel | Use the [Update a parcel](/api/v2/parcels/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](/api/v2/parcels/cancel-a-parcel) endpoint in the Parcels API | Use the [Cancel a shipment](/api/v3/shipments/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](/api/v2/parcels/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](/api/v2/shipping-methods) or the [Shipping products API](/api/v2/shipping-products). | Use any [Shipments API](/api/v3/shipments) `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](/api/v3/shipping-options/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](/api/v3/compat/retrieve-a-list-of-shipping-options) 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](/api/v2/shipping-products/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](/api/v2/shipping-prices/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](/api/v3/shipping-options/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](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/brands/retrieve-a-list-of-brands) endpoint. | | Add insurance to your single-collo shipment | Use the [Create a parcel or parcels](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously) or [asynchronous](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously) 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](/api/v2/integrations/create-a-list-of-shipments) endpoint in the Integrations API (only available for certified Sendcloud partners) | Use the [Create a parcel or parcels](/api/v2/parcels/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](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) or [Request a label for one or more orders asynchronously](/api/v3/ship-an-order/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](/api/v3/parcel-documents/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](/api/v3/shipments/create-and-announce-a-shipment-synchronously) or [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-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](/api/v3/shipments) `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](/api/v3/shipments) `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](/api/v3/shipments) `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](/api/v3/shipments) `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](/api/v2/parcels/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](/api/v3/returns/create-a-return) endpoint in the Returns API | | Create a return (synchronously) | Use the [Create a parcel or parcels](/api/v2/parcels/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](/api/v3/returns/create-a-return-synchronously) endpoint in the Returns API | | Retrieve a list of returns | Use the [Retrieve parcels](/api/v2/parcels/retrieve-parcels) endpoint in the Parcels API | Use the [Retrieve a list of returns](/api/v3/returns/retrieve-a-list-of-returns) endpoint in the Returns API | | Retrieve a return | Use the [Retrieve a parcel](/api/v2/parcels/retrieve-a-parcel) endpoint in the Parcels API | Use the [Retrieve a return](/api/v3/returns/retrieve-a-return) endpoint in the Returns API | | Request cancellation of a return | Use the [Cancel a parcel](/api/v2/parcels/cancel-a-parcel) endpoint in the Parcels API | Use the [Request cancellation of a return](/api/v3/returns/request-cancellation-of-a-return) endpoint in the Returns API | | Validate a return | 🚫 Not supported | Use the [Validate a return](/api/v3/returns/validate-a-return) endpoint in the Returns API | | Retrieve a return portal URL | Use the [Retrieve a return portal URL](/api/v2/parcels/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](/api/v2/contracts/retrieve-a-list-of-contracts) endpoint | Use the v3 [Retrieve a list of contracts](/api/v3/contracts/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](/api/v2/contracts/retrieve-a-contract) endpoint | Use the v3 [Retrieve a contract](/api/v3/contracts/retrieve-a-contract) endpoint | | Create a contract for carrier | 🚫 Not supported | Use the [Create a contract for a carrier](/api/v3/contracts/create-a-contract-for-a-carrier) endpoint.

To help with creating contracts, use the [Retrieve a list of contract schemas](/api/v3/contracts/retrieve-a-list-of-contract-schemas) endpoint. | | Update a contract | 🚫 Not supported | Use the [Update a contract](/api/v3/contracts/update-a-contract) endpoint.

To help with updating contracts, use the [Retrieve a list of contract schemas](/api/v3/contracts/retrieve-a-list-of-contract-schemas) endpoint. | | Delete a contract | 🚫 Not supported | Use the [Delete a contract](/api/v3/contracts/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](#pickups-fields) for more details. | Action | Pickups API v2 | Pickups API v3 | | ------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | List all pickups | Use the v2 [Retrieve a list of pickups](/api/v2/pickups/retrieve-a-list-of-pickups) endpoint | Use the v3 [Retrieve a list of pickups](/api/v3/pickups/retrieve-a-list-of-pickups) endpoint | | Get a specific pickup | Use the v2 [Retrieve a pickup](/api/v2/pickups/retrieve-a-pickup) endpoint | Use the v3 [Retrieve a pickup](/api/v3/pickups/retrieve-a-pickup) endpoint | | Create a pickup for Correos Express | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DHL | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DHL Parcel Iberia | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DPD | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for FedEx | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for Poste Italiane | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for UPS | Use the v2 [Create a pickup](/api/v2/pickups/create-a-pickup) endpoint | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for BRT | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DPD AT | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DHL DE | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DHL Express | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for DHL Parcel GB | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for GLS Italy | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint | | Create a pickup for Hermes Germany | 🚫 Not supported | Use the v3 [Create a pickup](/api/v3/pickups/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](/api/v2/tracking/retrieve-tracking-information-of-a-parcel) endpoint | Use the [Retrieve tracking information for a parcel](/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel) endpoint | | Create an external parcel for tracking | 🚫 Not supported | Use the [Create an external parcel for tracking](/api/v3/parcel-tracking/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](https://jsonapi.org/format/#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](/api/v2/dynamic-checkout/retrieve-a-list-of-delivery-options) endpoint | Use the v3 [Retrieve a list of delivery options](/api/v3/dynamic-checkout/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](/api/v2/analytics/retrieve-carrier-transit-times) endpoint | Use the v3 [Retrieve carrier transit times](/api/v3/analytics/retrieve-carrier-transit-times) endpoint | | Retrieve shipping option transit times | Use the v2 [Retrieve shipping method transit times](/api/v2/analytics/retrieve-shipping-method-transit-times) endpoint | Use the v3 [Retrieve shipping option transit times](/api/v3/analytics/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](https://jsonapi.org/format/#error-objects). There have also been some field changes between the Reporting API v2 and Reporting API v3. Please refer to the [reporting fields section](#reporting-fields) for more details. | Action | Reporting API v2 | Reporting API v3 | | ------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | | Create a parcels report | Use the v2 [Create a parcels report](/api/v2/reporting/create-a-parcels-report) endpoint | Use the v3 [Create a parcels report](/api/v3/reporting/create-a-parcels-report) endpoint | | Retrieve a parcels report | Use the v2 [Retrieve a parcels report](/api/v2/reporting/retrieve-a-parcels-report) endpoint | Use the v3 [Retrieve a parcels report](/api/v3/reporting/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](/api/v3/event-subscriptions/index) (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: * [Brands API](/api/v2/brands/retrieve-a-list-of-brands) * [Invoices API](/api/v2/invoices) * [Parcel statuses API](/api/v2/parcel-statuses) * [Return portal API](/api/v2/return-portal) * [Service points API](/api/v2/service-points) * [Users API](/api/v2/users/retrieve-your-user-data) ## 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](#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](#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](#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` | # Postman Source: https://sendcloud.dev/docs/getting-started/postman Postman collections offer a convenient way to explore and experiment with Sendcloud APIs. Once you have created an account with [Postman](https://www.postman.com), you can use our Postman collections, which you can find on our [public Postman workspace](https://www.postman.com/sendcloud-api). ### Forking The best way to experiment with the collection is to [create a fork](https://learning.postman.com/docs/collaborating-in-postman/version-control/). A fork allows you to set up your private environments and create a tailored experience for your specific needs. A fork is a new instance of an element that you can change without changing the parent element. In Postman, you can fork collections, environments, and flows. Forking enables you to contribute to a component without having editor access to that element. Once you have forked a collection, you need to [define your environment](https://learning.postman.com/docs/sending-requests/managing-environments/) to experiment with it. We provide an environment template that you can also [fork](https://learning.postman.com/docs/sending-requests/managing-environments/#forking-environments) and use to get started. If you work as part of a team, you can use environments to group related sets of values together and manage access to shared data. If you need to set the value for your [API keys](/docs/getting-started/authentication), use the environment templates. They already have sets of variables and values to start using the APIs. [Run in Postman](https://app.getpostman.com/run-collection/10978080-a806884c-a437-4c48-8095-eb152949b800) # Rate limits Source: https://sendcloud.dev/docs/getting-started/rate-limits Rate limiting is a technique employed by APIs to manage the volume and frequency of incoming requests, ensuring a stable and high-quality experience for all users. It helps prevent resource starvation, maintain cost control, and provide a layer of security against potential attacks. To ensure fair usage, prevent system overloading, and protect API resources, our API has **rate limits** that limit the number of requests that can be made within a specific time frame and request safety. These rate limits differ depending on whether the request is considered [safe or unsafe](https://developer.mozilla.org/en-US/docs/Glossary/Safe/HTTP). It is essential to follow these guidelines to avoid exceeding the API rate limits and receiving HTTP 429 responses. Failure to comply may disrupt your API usage and lower service quality. ## Default rate limits | | Default rate limits | Burst allowance\* | | ---------------------------------------------------- | -------------------------- | ------------------------ | | **Safe** methods: `GET` | `1000` requests per minute | n/a | | **Unsafe** methods: `POST`, `PATCH`, `PUT`, `DELETE` | `100` requests per minute | `15` requests per second | \*A **burst allowance** sets the maximum number of concurrent requests the API can handle. It allows for a temporary increase in the request rate to accommodate short periods of high traffic without exceeding the overall rate limits. ## Tips * To avoid getting blocked or throttled, it is important to adhere to the rate limits that are set. These limits specify the maximum number of requests allowed within a certain period. Please make sure that your application stays within these limits. * It's important to handle rate-limit responses properly. If you receive an `HTTP 429 (Too Many Requests)` response, the rate limit has been surpassed. * Regularly monitor and analyze your application's rate limit usage to identify potential bottlenecks or excessive usage patterns. This will help you proactively adjust your application's behavior and optimize resource consumption. # Centralized integration guidelines Source: https://sendcloud.dev/docs/marketplaces/centralized-integration-guidelines If you're looking for an integration that allows you to maintain full control over shipping label creation, this is the workflow we recommend. Via a centralized integration type, you will run a single Sendcloud account which can only be accessed by your marketplace employees. Your account will serve as the central hub for processing all of your merchants' orders into labels. Merchants won't need to create their own Sendcloud accounts, and you can tailor the customer experience by deciding on the rates and shipping methods you want to offer them. ## Key benefits * You have full oversight of all shipping activities * Sendcloud operates in the background, so merchants won't have to leave your platform to create their labels * Ideal setup for C2C marketplaces, or for marketplaces which host sellers who ship low volumes of orders per month, on an ad-hoc basis * You can enable customizable tracking emails to increase brand exposure * You decide how and when to charge merchants for their shipping labels * Quickly onboard new sellers and provide an easy means for them to print labels * You can offer multiple shipping options, including delivery to service points ## How does it work? 1. Through a centralized setup, you will provide the option to purchase a shipping label through your marketplace at the point of sale 2. Optional: You can provide multiple shipping options for your merchant to choose from, based on the size and form of the packaging or parcel weight 3. The marketplace will request a label via an API call using its own Sendcloud account credentials 4. The label is returned to the marketplace, to be presented to the merchant 5. The merchant downloads the shipping label, prints it and attaches it to the box Centralized integration workflow ## Centralized integration setup To begin, [sign up for a Sendcloud account](https://account.sendcloud.com/signup). This is your main account, which you or your marketplace employees will use to make API calls to retrieve shipping labels for your users. Merchants are not required to have their own Sendcloud accounts, and no input is required from them to create the integration. Then, create an API integration in your Sendcloud account: 1. Log in to your Sendcloud account 2. Navigate to [Settings > Integrations](https://app.sendcloud.com/v2/settings/integrations/manage) 3. Find the **Sendcloud API** integration in the list and click **Connect** 4. Enter a name for the integration, such as the name of your platform, and click **Save** 5. The form will auto-complete with your API credentials. Your API Public and Private key will be used to [authenticate your API requests](/docs/getting-started/authentication/) to Sendcloud. You must include these in the `Authorization` header for all your requests to our APIs. 6. To enable a webhook feedback loop, enter the webhook URL in the designated field and check the box “Webhook feedback required”. 7. (Optional) Enable **service point delivery**, as well as the carriers you want to use for this delivery option. Your API credentials are private and **must not be shared** with anyone. ## How to create shipping labels With a centralized integration type, you need to provide your merchants with a way to request a shipping label for a completed order. This is done by making an API call to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. You'll need to include information about your merchant's sender address and the end-customer's address information in your API call. If you want to create a parcel to ship to a service point, you'll also need to retrieve a list of service points and include a corresponding `service_point_id` in your request. Learn how to offer service point delivery to your merchants and their customers. In order to retrieve a shipping label at the same time as you create the parcel in the Sendcloud system, you need to pass the argument `"request_label": true`. When this field is set as `true`, a URL containing the shipping label will be returned along with the parcel information in the response. For full details on the data you can include in your request, refer to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint documentation. The response will contain a URL which links to the shipping label. You'll need to provide your API keys to access the label, as with all API requests. Shipping labels can be downloaded in various sizes and formats, including PDF format and sizes suitable for a standard or label printer. This is explained in more detail in the [Labels API](/api/v2/labels/) documentation. You can now present the label to your merchant to download, print and attach to their box. **Tip:** The response also includes a tracking number for the parcel, which can be shared with both the merchant and the buyer. If Tracking emails have been enabled in your Sendcloud account, the buyer will receive tracking emails to inform them about the status of their delivery. Find out more about [Tracking parcels via the API](/docs/tracking/tracking-parcels). ## Additional functionalities Sendcloud APIs allow you access to the internals of our platform, including our host of shipping-oriented features. You can decide which of our features you want to build into your integration. Depending on your unique business model and the extent to which you want to support your merchants; shipping activities, you could consider implementing some of the following features: ### Tracking A centralized integration model provides a unique marketing opportunity by way of branded tracking notifications. Build out your brand in the Sendcloud platform and enable tracking notifications to have customers receive timely delivery updates, customized with your branding. You can also customize a Tracking Page which customers will land on when they click the tracking URL in the notification. Tracking pages let you promote your social media presence via our Instagram widget, and you can insert your latest campaign through promotional banners. Learn how to integrate tracking into your marketplace. **Tip:** You can make use of webhooks to proactively push tracking information through to your customers. See our [webhook documentation](/api/v2/webhooks). ### Return portal Provide an easy way for merchants to generate return labels via a customizable Return portal. View our documentation to see how you can build your own version of the Return portal to incorporate return label creation into your workflow. Learn how to build your own version of the return portal. ### Service point delivery We make it easy for you to enable service point delivery methods and allow your merchants to ship parcels to a location that's convenient to the end-buyer. Read the [Servicepoints for marketplaces](/docs/marketplaces/servicepoints-for-marketplaces/) page to understand the steps involved, and see an example of how you can build a service point location picker into your checkout. ## How do I charge my merchants for shipping labels? Sendcloud will charge your account for labels you create on behalf of your sellers. This gives you the flexibility to define your own customer journey, and decide how and when you will charge your users for their labels. Some options to consider for your billing model include: ### Connect your direct carrier contracts Connecting your direct carrier contracts helps you to keep your shipping rates as low as possible, so you can transfer the benefits to your users while shipping on your pre-negotiated rates. Learn how to connect your direct carrier contracts to Sendcloud. ### Offer multiple shipping options to your merchants A choice of shipping methods gives both your merchants, and their end-customer, the flexibility to choose a delivery method and service level that suits them best. You can retrieve rates directly via the Sendcloud API for all our supported shipping methods, so you can price shop regularly to make sure you're getting the best possible rates. Learn how to get an up-to-date list of shipping methods via the API. Learn how to retrieve shipping prices from the API. ### Simplify shipping decisions with flat-rate or free shipping If you want to make the lives of your merchants as easy as possible, you can simply offer a flat fee for parcels that fall within specific weight brackets. This is the easiest billing method that also saves you in development costs. Some popular online marketplaces let their merchants select a parcel form, (e.g., letterbox parcel, small box, large box, etc.), and then present a flat fee for the parcel, based on their selection and delivery method (standard or service points delivery). Offering free or discounted labels to your merchants based on how much they ship per month is another great way to improve your customer retention rates. ### Turn shipping into a profit generator When you ship through Sendcloud, you'll receive discounts on shipping label prices based on the amount of parcels you ship. You could decide to gain extra margin on your rates by offering them to merchants with a percentage or flat fee markup. Alternatively, consider offering discounted shipping to customers who have a higher subscription plan as an incentive. ### Transfer shipping costs directly And finally, you could simply choose to present shipping costs directly to your merchants based on the price you pay in Sendcloud or via your carrier contract. If you opt for this solution, you can retrieve up-to-date shipping prices for specific shipping methods, and build it into your marketplace UI. Learn how to retrieve shipping prices from the API. # Decentralized integration guidelines Source: https://sendcloud.dev/docs/marketplaces/decentralized-integration-guidelines A decentralized integration setup is recommended for **B2B and B2C-model marketplaces**, where sellers typically ship large volumes of parcels on a regular basis. Via this setup, each individual merchant will have their own Sendcloud account. This **allows sellers to have full control over their own shipping processes** and the ability to connect carrier contracts to their account. The merchant can process their imported orders into labels using the Sendcloud platform. For the marketplace, this setup means that you don't have to consider building shipping processes and label purchasing into your platform. Merchants who ship on Sendcloud rates, and have questions about shipments, rates or invoicing, will be handled by Sendcloud. This makes a decentralized integration flow an ideal solution if you're looking to reduce your customer support and development costs. ## Key benefits * Scalable solution that allows users to fully optimize their shipping processes, so your merchants won't outgrow your marketplace as their order volume increases * Allows merchants with a direct carrier contract to ship on their pre-negotiated rates * Merchants can market their brand through customizable tracking notifications, and the Return portal * Sendcloud will support merchants with questions related to shipping, integrations and invoices * Low-cost, low effort integration * You don't have to worry about billing or building shipping label purchasing into your UI, because Sendcloud will invoice merchants directly for any labels they create ## How does it work? 1. A decentralized setup means that every merchant on your platform will need to have their own Sendcloud account. 2. When an order is placed in the marketplace, it will be imported into Sendcloud via the merchant's API credentials. 3. The merchant will log into their account and process the order into a shipping label via the Sendcloud UI. Once the order is processed in Sendcloud, the merchant downloads and prints the label, and attaches it to the box. Decentralized integration workflow ## Decentralized integration setup Each merchant will need to [sign up for their own Sendcloud account](https://account.sendcloud.com/signup). Once an account has been made, they can create an API integration in the Sendcloud platform to create their unique API keys. Once they create their API keys, they can enter these into the relevant fields in your marketplace UI to create the connection. To make this process easier, this can be done by redirecting the merchant to a webpage which will prompt them to allow access for the integration, allowing you to make API calls on their behalf. Merchants need to complete the following steps to obtain their API keys: 1. Log in to their Sendcloud account 2. Navigate to [Settings > Integrations](https://app.sendcloud.com/v2/settings/integrations/manage) 3. Find the **Sendcloud API** integration in the list and click **Connect** 4. Enter a name for the integration, such as the name of the marketplace, and click **Save** 5. The form will auto-complete with their API credentials. Your API Public and Private key will be used to [authenticate your API requests](/docs/getting-started/authentication/) to Sendcloud. You must include these in the `Authorization` header for all your requests to our APIs. 6. To enable a webhook feedback loop, enter the webhook URL in the designated field and check the box “Webhook feedback required”. You can also set up event notifications programmatically using the [Event Subscriptions API](/api/v3/event-subscriptions/index) (BETA), which supports webhook endpoints and third-party integrations like Klaviyo. 7. (Optional) Enable **service point delivery**, as well as the carriers you want to use for this delivery option. API credentials are private and **must not be shared** with anyone. ## How to create shipping labels To create shipping labels via a decentralized integration model, you need to make a request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. When you make the request, you should authenticate **by passing the API keys of the merchant**. This will ensure that orders you create via the integration will appear in the individual merchant's Sendcloud platform. For full details on the data you can include in your request, refer to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint documentation. Note that the response **does not contain either tracking information or a URL to access the shipping label**. This is because the order must still be processed directly via the Sendcloud platform before it will be announced with the carrier. Read our help center guides on how to [process orders](https://support.sendcloud.com/hc/en-us/articles/360025263691-Process-your-orders-) and [print labels](https://support.sendcloud.com/hc/en-us/articles/360025142471-Print-labels-in-one-click) through the Sendcloud platform. ### Important: the `request_label` field Via a decentralized flow, orders should be imported into the merchant's Sendcloud platform **without creating a shipping label**. This is to allow merchants the flexibility to make adjustments to orders, such as changing the shipping method, before processing them into labels. You will need to pass the following argument, in addition to the required fields: `"request_label": false`. The order will now correctly appear in the merchant's incoming order overview in Sendcloud. ### Shipping to a service point If you want to create a parcel to ship to a service point, you'll need to retrieve a list of service points and include a corresponding `service_point_id` in your request. Learn how to offer service point delivery to your merchants and their customers. ## Additional functionalities ### Connect carrier contracts Sellers with high order volumes will often have their own contracts with their preferred carriers to ensure they get the best possible rates on their shipping labels. An integration with Sendcloud means you don't have to worry about your biggest customers outgrowing your marketplace—they can connect their contracts directly to their Sendcloud account, and they'll be invoiced directly by their carrier for any labels they create. Learn how to use your own carrier contract in our help center. ### Tracking Merchants can upload their brand assets in Sendcloud and use them to personalize tracking notifications and a custom tracking page to replace the website of the shipping carrier. Tracking notifications are an unmissable banding opportunity for sellers looking to grow brand awareness and encourage return sales. Learn about Sendcloud's automated tracking features in our help center. ### Return portal Sellers can take advantage of a customizable, Sendcloud-hosted return portal, which allows both the merchant, and their customers, to validate returns and download return shipping labels. The return portal also allows merchants to charge for returns, so savvy online retailers won't be out of pocket when customers request returns. Find out how to set up your own return portal in our help center. ### Multi-carrier shipping options Sendcloud connects our users to 160+ domestic and international carriers, resulting in a huge and diverse portfolio of shipping methods which sellers can, in turn, offer to their customers. By integration with Sendcloud via this setup, you won't have to consider which rates and methods to offer to your sellers, as they'll have the flexibility to define their own customer journeys. Read more about Sendcloud's carrier offering. ### International shipping options and customs documents Sendcloud will automatically generate customs documents alongside the label when your merchants ship an order to a destination outside the EU. The merchant needs to provide some additional information in their account settings, and include additional parcel item information. Read guidance on handling international shipping in our help center. ### Automated order processing with shipping rules Shipping rules help users to customize their workflow and save time, money and energy by automating every-day decisions about how to process orders. Learn how to set up and use shipping rules in our help center. # Hybrid integration guidelines Source: https://sendcloud.dev/docs/marketplaces/hybrid-integration-guidelines A hybrid integration model utilizes a **combination of a centralized and decentralized approach**, resulting in two separate flows. While this setup involves a little more development time to build, it's the most flexible way to allow merchants to process orders and create labels. If you have a varied customer base of C2C and B2C sellers, or your merchants range in parcel volume anywhere from 10 to 5000+ parcels per month, this setup covers all bases. You can provide an easy way for new merchants and C2C sellers to join your platform by letting them create shipping labels directly from your marketplace via a centralized workflow. You will use a single Sendcloud account to create labels and process orders on the behalf of your new and smaller scale merchants. At the same time, you can provide a scalable solution for your larger customers by allowing them to integrate your platform with their own, individual Sendcloud accounts (decentralized setup). ## Key benefits * Future-proof and scalable solution for merchants increasing in parcel volume * The two integrations can be managed separately, so if you already have a centralized or decentralized set-up you can implement a hybrid solution at a later stage if required * You'll be able to capitalize on branding opportunities via tracking notifications via the centralized workflow * Offers the most flexibility for sellers * Easily onboard new or inexperienced sellers ## How does it work? As this integration involves two separate setups, you can follow the guidelines for a centralized and decentralized setup to build the two integrations independently. See: [Centralized integration guidelines](/docs/marketplaces/centralized-integration-guidelines/) and [Decentralized integration guidelines](/docs/marketplaces/decentralized-integration-guidelines/). Merchants will be able to follow either the decentralized flow and use their own Sendcloud account (indicated by the **red** path in the diagram below), or a centralized flow (**blue** path). Hybrid integration workflow Merchants will use either of the options below, depending on their preference: 1. Their own Sendcloud account to purchase labels 2. The marketplace's central Sendcloud account ### Option 1: Merchant uses their own Sendcloud account A decentralized setup means that every merchant on your platform will need to have their own Sendcloud account. 1. When an order is placed in the marketplace, it will be imported into the Sendcloud account of the individual merchant via their unique API credentials. 2. The merchant will log into their account and process the order into a shipping label via the Sendcloud UI. 3. Once the order is processed in Sendcloud, the merchant downloads and prints the label, and attaches it to the box. 4. They will be invoiced directly by Sendcloud for shipping labels they create. ### Option 2: Merchant uses the marketplace's central Sendcloud account At the point of sale, merchants will be able to purchase a label for a completed order directly from your platform. Optionally, you can provide multiple shipping options for your merchant to choose from, based on the size and form of the packaging or parcel weight. 1. The marketplace will request a label via an API call using its own Sendcloud account credentials 2. The label is returned to the marketplace, to be presented to the merchant 3. The merchant downloads the shipping label, prints it and attached it to the box 4. Sendcloud will charge you, the marketplace, for all labels you create via the central Sendcloud account 5. You can decide how and when to bill your merchants. Some examples are included in the documentation for the Centralized setup under [How do I charge my merchants for shipping labels?](/docs/marketplaces/centralized-integration-guidelines#how-do-i-charge-my-merchants-for-shipping-labels%3F) ## Hybrid integration setup The setup for a hybrid model will require you to build and offer two separate flows to the merchant: ### Decentralized setup Each merchant will need to [sign up](https://www.sendcloud.com/) for their own Sendcloud account. * Once an account has been made, they can create an API integration in the Sendcloud platform to create their unique API keys. * Once they create their API keys, they can enter these into the relevant fields in your marketplace UI to create the connection. * To make this process easier, this can be done by redirecting the merchant to a webpage which will prompt them to allow access for the integration, allowing you to make API calls on their behalf. Read the in-depth guide on setting up a decentralized integration with Sendcloud ### Centralized setup To enable merchants to purchase labels directly from your platform, you will need to create a single Sendcloud account, which will be accessed only by marketplace employees. This account will be used to process all orders and create labels for merchants who purchase labels directly from the marketplace. To begin, [sign up](https://www.sendcloud.com/) for a Sendcloud account. This is your main account, which you use to make API calls to retrieve shipping labels. As you will allow your users to request labels directly from the marketplace, they are not required to create their own accounts. Read the in-depth guide on setting up a centralized integration with Sendcloud ## How to create shipping labels Two different technical setups are required for the hybrid integration model. You can find more details, plus an explanation of how shipping labels are created via each flow, in the respective documentation: [Centralized integration guidelines](/docs/marketplaces/centralized-integration-guidelines/) & [Decentralized integration guidelines](/docs/marketplaces/decentralized-integration-guidelines/). # Marketplaces overview Source: https://sendcloud.dev/docs/marketplaces/index Looking for a robust, **all-in-one shipping solution** that seamlessly integrates with your online marketplace? Sendcloud APIs enable your merchants to create and print labels by connecting them to 160+ shipping carriers, and a host of reliable and flexible shipping methods for both domestic and international delivery. Our Shipping and Service Point APIs provide all the components you need to connect your sellers, and their customers, with service point delivery methods, customizable tracking notifications and multi-carrier services. You can easily integrate your marketplace with Sendcloud and have real-time order updates and status changes automatically synced between both platforms. Not only does Sendcloud help your merchants to process orders into shipments, but our core features are designed to boost conversion rates and drive return sales. Integrating with our APIs allows you to focus on your core business model without losing time and money from needing to build shipping into your platform infrastructure. ## Marketplace guidelines We've identified three different integration models to suit the needs of every marketplace. In these guidelines, we provide example workflows and discuss the key benefits of each integration model, so you can make a reliable decision about which setup works best for you. Tip: Alongside our APIs, Sendcloud provides plug-and-play apps for the most popular online marketplaces, such as Amazon, Bol.com, Ebay, Etsy and Mirakl. These apps allow individual sellers to quickly integrate their Sendcloud account with their marketplace account in a matter of minutes. ## Integration types There are a few different ways you can choose to integrate Sendcloud with your marketplace, depending on your business and invoicing model, and the needs of your particular customer base. We've identified three different setups and account options: 1. [Centralized integration](/docs/marketplaces/centralized-integration-guidelines) (Single Sendcloud account) 2. [Decentralized integration](/docs/marketplaces/decentralized-integration-guidelines) (Standalone Sendcloud accounts) 3. [Hybrid integration](/docs/marketplaces/hybrid-integration-guidelines) | | Centralized integration | Decentralized integration | Hybrid integration | | ---------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **Sendcloud account holder** | The marketplace has a central Sendcloud account. | Individual merchants have their own Sendcloud accounts. | Central Sendcloud account for new users. For merchants with higher parcel volumes, they can create their own Sendcloud accounts to customize their workflow. | | **Label creation** | Merchants purchase labels through the Marketplace. | Labels are created by the merchant via their own Sendcloud account. | Two possible flows; purchase labels via the Marketplace, or process orders via the individual merchant's Sendcloud account. | | **Business mode** | Most suitable for C2C and C2B marketplaces. | Most suitable for B2C and B2B marketplaces. | Most suitable for B2C and B2B marketplaces. | | **Parcel volume** | Most suitable for merchants who ship low volumes of orders on an ad-hoc basis. | Most suitable for merchants shipping high volumes of parcels per month. | Provides two separate, scalable workflows so merchants won't outgrow your platform. | | **Direct carrier contract** | The marketplace can ship on their direct carrier contract rates. | Individual merchants can ship on their direct carrier contracts. | Combination, depending on chosen workflow. | | **Customer care** | Marketplace supports merchants. | Sendcloud supports merchants directly. | Marketplace, or Sendcloud, depending on setup. | | **Invoicing** | Marketplace is invoiced for labels by Sendcloud. Marketplace can transfer costs to their users. | Merchants are invoiced for labels directly by Sendcloud. | Combination of a centralized and decentralized billing model, depending on workflow. | | **Development effort** | Average | Average | Higher | | **Documentation** | [Centralized integration guidelines](/docs/marketplaces/centralized-integration-guidelines) | [Decentralized integration guidelines](/docs/marketplaces/decentralized-integration-guidelines) | [Hybrid integration guidelines](/docs/marketplaces/hybrid-integration-guidelines) | Need help? [Speak to an expert](https://www.sendcloud.com/contact/) to help you get started. # Service points for marketplaces Source: https://sendcloud.dev/docs/marketplaces/servicepoints-for-marketplaces Service point delivery allows online buyers to have their parcel delivered to a local service point location, as opposed to their home or business address. First ensure that you've [enabled service point delivery in your Sendcloud account](/docs/service-points/creating-a-parcel-with-service-point-delivery#step-1%3A-enable-service-point-delivery-in-your-sendcloud-account). If you're following a [decentralized integration setup](/docs/marketplaces/decentralized-integration-guidelines), each merchant who wants to offer service point delivery will have to perform these steps in their Sendcloud account. Secondly, you need to provide a way for the end-customer to select their preferred service point location during the checkout process. Sendcloud offers a Service points API. To support service point delivery, you'll need to retrieve a list of available service points within a specified search radius via the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint. You can display this list to the end-customer during your checkout process, so that they can select their preferred delivery location. We also support integrating a service point picker widget into your checkout. Service point picker widget Read more about how to include service points in your data flow, including the service point picker widget. Once the customer has selected a service point, you'll need to include it in your request to the Create a parcel endpoint. Read more about how to create a parcel for delivery to a service point. ## Service point delivery methods If you want to offer service point delivery to your sellers and their customers, it's important that you also provide them with applicable shipping methods to choose from. You will need to present your seller with the option to purchase either a standard delivery method or a service point delivery method at the point of sale. Learn how to retrieve a list of shipping methods, including service point delivery methods. **Tip:** Depending on how you choose to tailor your customer journey, you can present multiple different methods from various carriers to offer more flexibility to your sellers. # Creating and managing orders Source: https://sendcloud.dev/docs/orders/creating-and-managing-orders You can use the [Orders API](/api/v3/orders) to create, retrieve, update, and delete orders in Sendcloud. ## Orders API behaviour and limits Understanding how the Orders API behaves will help you design reliable synchronization logic. ### Upsert behaviour * Orders are matched by `order_id` + `order_details.integration.id` * If a matching order exists, it is updated * If no match exists, a new order is created * You may optionally include Sendcloud’s internal `id` to explicitly target an existing order When sending `id`, it must be a string — even though responses return it as a number ### Batch processing * Up to **100 orders per request** * Orders from multiple integrations may be included in the same batch * Requests are all-or-nothing: if one order fails validation, the entire batch is rejected ### Constraints * `order_id` is immutable once an order exists * You can only create or update orders for integrations belonging to your account * Concurrent updates on the same order may result in a conflict — retry after a short delay ## Creating orders To [create or update orders](/api/v3/orders/create-update-orders-in-batch), make a `POST` request to: ```http Example request method and URL theme={null} POST https://panel.sendcloud.sc/api/v3/orders ``` This endpoint accepts an array of orders and applies upsert logic to each entry: if the order already exists, it is updated, if it does not exist, a new order is created. If the request is successful, the API returns HTTP 200 and a response body containing the created or updated orders, including their Sendcloud id. Orders created via the API typically include: * `order_id` * `order_number` * `order_details.integration.id` * Customer contact details * Shipping address or service point information * Order line items with quantities and pricing * Order totals and currency * Optional customs details (for international shipments) Note: See the [API Reference](/api/v3/orders/create-update-orders-in-batch) for the full schema. Creating an order: * Does not create a shipment * Does not generate labels * Does not contact the carrier ## Retrieving orders To [retrieve a list of orders](/api/v3/orders/retrieve-a-list-of-orders), make a `GET` request to ```http Example request method and URL theme={null} GET https://panel.sendcloud.sc/api/v3/orders ``` The orders returned depend on: * The filters you provide (integration, order number, status, creation/update dates) * Sorting parameters * Page size settings The endpoint is paginated. Use the `next` and `prev` links in the response headers to navigate through results. To [retrieve an order](/api/v3/orders/retrieve-an-order), make a GET request including the specific `id` to: ```http Example request method and URL theme={null} GET https://panel.sendcloud.sc/api/v3/orders/{id} ``` This returns the order that matches the provided Sendcloud internal `id`. ## Updating orders You can keep Sendcloud synchronized with your source system by updating orders as data changes. This can be done either by reusing the upsert endpoint or by performing partial updates. ### Upserting with `POST` (recommended) To [update an existing order](/api/v3/orders/create-update-orders-in-batch), make a `POST` request to: ```http Example request method and URL theme={null} POST https://panel.sendcloud.sc/api/v3/orders ``` Include: * The same `order_id` * The same `order_details.integration.id` * Any fields that have changed (for example address corrections or status updates) If a matching order exists, it will be updated. The internal Sendcloud `id` remains unchanged. ### Partial updates To [update an order](/api/v3/orders/update-an-order) for specific fields only, make a `PATCH` request to: ```http Example request method and URL theme={null} PATCH https://panel.sendcloud.sc/api/v3/orders/{id} ``` Dedicated endpoints allow updating only specific fields of an order. See the [API Reference](/api/v3/orders/update-an-order) for details on partial updates and supported fields. ## Deleting orders Orders that are cancelled upstream can be removed from Sendcloud. To [delete an order](/api/v3/orders/delete-an-order), make a `DELETE` request to ```http Example request method and URL theme={null} DELETE https://panel.sendcloud.sc/api/v3/orders/{id} ``` Deleting an order: * Removes it from the Incoming Orders View * Does not affect shipments or labels that already exist ## Error handling & troubleshooting If a request fails validation, the API will return an error response. For batch requests: * If one order fails validation, the entire request is rejected * No orders are created or updated Common causes of errors include: * Missing required fields * Invalid `order_details.integration.id` * Incorrect country codes or timestamps * Attempting to modify immutable fields such as order\_id * Concurrent updates on the same order If an order doesn’t appear or looks incorrect in the Sendcloud platform: * Confirm you received a success response * Confirm the response includes a Sendcloud `id` * Verify `order_details.integration.id` * Use `GET /api/v3/orders/?integration={id}` to confirm existence * Validate timestamps and country codes ## Shipping an order (“Ship an Order” endpoints) Orders do not generate labels or announce shipments by themselves. To ship an existing order, use the [Ship an Order API](/api/v3/ship-an-order). These endpoints generate shipping labels based on an order that already exists in Sendcloud. Learn how to create shipping labels for your orders using the Ship an Order API. # Orders overview Source: https://sendcloud.dev/docs/orders/index The [Orders API v3](/api/v3/orders) lets you create and manage [Orders](/docs/getting-started/key-concepts#orders) in Sendcloud. Orders appear in the Incoming Orders view, where they can be reviewed, updated, and shipped later via API. Use this API when you want to sync order data (addresses, items, delivery details such as service points) into Sendcloud before creating labels. ## What you'll Learn This guide explains how to: * Create, update, and retrieve orders via the API * Keep order data in sync with your upstream systems * Use orders as the starting point for automated shipping and label generation Note: This guide covers our latest version, Orders API v3. For full endpoint and schema documentation, see the [API reference](/api/v3/orders). ## When to use the Orders API Use the Orders API when you want to sync and manage orders in Sendcloud before fulfillment. Typical use cases: * Importing orders from a webshop, marketplace, or ERP * Preparing orders for fulfillment while shipping happens later * Allowing operational review or corrections before shipping * Using Sendcloud as a central place to manage incoming orders If you already have shipping-ready data and want to create labels immediately, the [Shipments API](/api/v3/shipments) is usually a better fit. ## How it fits into the Sendcloud workflow Orders sit between checkout and fulfillment. They represent the commercial side of a purchase — what was sold, to whom, and where it needs to be delivered. A typical flow looks like this: 1. An order is created in the source system (shop, marketplace, ERP) 2. The order is created in Sendcloud via the Orders API 3. The order can be reviewed or updated in Sendcloud 4. The order is shipped by: * Creating labels directly in the Sendcloud panel, or * Using the [Ship an Order API](/docs/orders/ship-an-order) to programmatically generate shipments and labels Once shipped, the order transitions into the operational fulfillment phase. Important distinctions: * Orders can include delivery details such as service point (locker) information * Orders do not announce shipments to carriers by themselves * Orders do not generate labels automatically * An order can exist without ever being shipped Orders define what needs to be shipped. Shipments define how it is shipped. # Ship an order Source: https://sendcloud.dev/docs/orders/ship-an-order Use the [Ship an Order API](/api/v3/ship-an-order) to generate a shipping label for an order that already exists in Sendcloud. This is the fastest way to go from an Incoming Order to a label without building a full Shipments API flow. Ship an Order supports two flows: * **Synchronous**: Ship **one** order and receive the label file in the response. Best suited for one-off shipments or low volume. * **Asynchronous**: Ship **one or multiple** orders in a single request. Recommended for batch processing. The response returns parcel references and any per-order errors. Labels are retrieved separately. Ship an Order supports: * Shipping to addresses and service points * Applying Shipping Rules and Shipping Defaults * Adding brand information to labels and tracking emails ## Before you begin Before calling the [Ship an Order API](/api/v3/ship-an-order): Orders can be created via the [Orders API](/api/v3/orders) or through a plug-and-play integration (Shopify, eBay, WooCommerce, etc). You can use the [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint to confirm the order is available. Orders are saved asynchronously. If you create an order and immediately request a label, it may not yet be available. If you receive an “order not found” error, retrieve the order first and retry. Shipping Defaults can automatically fill in missing shipment data (for example weight, insurance, or preferred shipping method). Read about setting up shipping defaults in our help center Shipping Rules allow you to automatically determine how an order should be shipped based on conditions.\ To apply them during label creation, set `apply_shipping_rules: true` in your request. Learn more about shipping rules in our help center When shipping orders from plug-and-play integrations (e.g. Shopify, eBay, WooCommerce), tracking updates are automatically synced back to the source platform. ## Request a label for a single order synchronously Use the synchronous endpoint when you need the label returned immediately in the response. | Key details | | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Endpoint** | [Request a label for a single order synchronously](/api/v3/ship-an-order/request-a-label-for-a-single-order-synchronously) | | **Max orders per request** | **1** | | **HTTP status code** | **201** | | **Response** | Parcel reference + Base64-encoded label file | ## Request labels for one or more orders asynchronously Use the asynchronous endpoint for batch shipping. This endpoint fails gracefully — one order failing does not block others. | Key details | | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | | **Endpoint** | [Request a label for one or more orders asynchronously](/api/v3/ship-an-order/request-a-label-for-one-or-more-orders-asynchronously) | | **Max orders per request** | **1–20** | | **HTTP status code** | **202** | | **Response** | Parcel references for successful orders + `errors` array for failed ones | All orders in an asynchronous request must belong to the same `integration_id`. ## Request examples ### Asynchronous request ```json Example request body for the asynchronous endpoint theme={null} { "integration_id": 12345, "sender_address_id": 17, "orders": [ { "order_id": "ORDER-ID-1" }, { "order_number": "ORDER-NUMBER-2" } ] } ``` ### Synchronous request ```json Example request body for the synchronous endpoint theme={null} { "integration_id": 12345, "order": { "order_id": "ORDER-ID-1" } } ``` ## Common fields you may include Depending on your flow, your request may include: ### Required fields * `integration_id` (**required**) * `order` (**required**, synchronous only) * `orders` (**required**, asynchronous only; 1–20 orders) * `order_id` or `order_number` (**at least one required** per order): If both are provided, they must reference the same order under the specified `integration_id`. ### Optional fields * `ship_with`: explicitly set `shipping_option_code` and optional `contract_id` * `sender_address_id`: override default sender address * `brand_id`: apply branding to labels and tracking emails The Brands API is currently only available in API v2. This reference will be updated when a v3 version becomes available. If you are curious to learn more about setting up and managing brands see this [Help Center article](https://support.sendcloud.com/hc/en-us/articles/360041212392-How-to-set-up-your-brand). * `apply_shipping_rules` (per order): apply Shipping Rules before label creation * `label_details` (synchronous only): control label format (mime type, DPI) See the [API reference](/api/v3/ship-an-order) for the complete request schema and all supported fields. ### Shipping method resolution priority When creating the label, Sendcloud determines the shipping method in the following order: 1. Shipping Rules (if `apply_shipping_rules` = true) 2. `ship_with.shipping_option_code` 3. Existing `shipping_method` on the order 4. Shipping Defaults 5. Fallback to [Unstamped Letter](https://support.sendcloud.com/hc/en-us/articles/210931986-What-is-the-shipping-method-Unstamped-letter) (if no carriers are enabled) ### Contract selection * If `contract_id` is provided, that contract is used. * If omitted, Sendcloud uses your direct carrier contract (if available). * Otherwise, Sendcloud rates are applied. ### Finding related IDs and codes You may need to retrieve supporting values before calling this endpoint: * Use the [Retrieve a list of integrations](/api/v3/integrations/retrieve-a-list-of-integrations) endpoint to get a list of all your integrations. * To find which `shipping_option_code` values are available for a given shipment context, use the **Shipping Options API** (see [Shipping options & quotes](/docs/shipments/shipping-options-and-quotes) endpoint). * If you’ve hardcoded shipping method IDs in your system, you can use the **Compat API** to map them to the equivalent `shipping_option_code`. * Use the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint to get a list of your contracts. * Use the [Retrieve a list of sender addresses](/api/v3/sender-addresses/retrieve-a-list-of-sender-addresses) endpoint to get a list of your sender addresses. ## Retrieving labels ### If you used the asynchronous endpoint The async endpoint returns parcel references. Use the Parcel Documents API and to retrieve the label file, make a `GET` request to the [retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint. You can control the output format using: * `dpi` (query parameter) * Accept header (MIME type) ```http Request method, URL and headers theme={null} GET https://panel.sendcloud.sc/api/v3/parcels/1234567/documents/label?dpi=150 Accept: image/png ``` Supported formats depend on the carrier and configuration (e.g. PDF, PNG, ZPL). ### If you used the synchronous endpoint The label file is included directly in the JSON response (Base64-encoded). No additional API call is required. ```http Request method, URL and body theme={null} POST https://panel.sendcloud.sc/api/v3/orders/create-label-sync { "integration_id": 12345, "label": { "mime_type": "application/pdf", "dpi": 72 }, "order": { "order_id": "ORDER-ID-1" } } ``` The response includes: * `parcel_id` * `label.file` (Base64-encoded) * `label.mime_type` * `label.dpi` ## Error handling **Order not found**: If the order was recently created, it may not yet be available. Retrieve the order first using [Retrieve an order](/api/v3/orders/retrieve-an-order) endpoint and retry. **Partial failures (asynchronous endpoint)**: The asynchronous endpoint may return both successful parcel references and per-order errors in the same response. Inspect the `errors` array to determine which orders failed and why. **Carrier or announcement errors**: For synchronous requests, errors are returned directly in the response. For asynchronous requests, inspect the response and relevant parcel in the Sendcloud platform if needed. ## Limitations of Ship an Order Compared to the Shipments API, Ship an Order is more limited and does not (yet) support: * Synchronous multicollo shipping * Order splitting * Setting parcel-specific details such as: * Weight or dimensions per parcel * Items per parcel * Insurance per parcel * Label notes or delivery dates per parcel For advanced shipping scenarios, use the [Shipments API](/api/v3/shipments). # Creating an external parcel for tracking Source: https://sendcloud.dev/docs/parcel-tracking/create-an-external-tracking-parcel Use the [Create an external parcel for tracking](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) endpoint to register an external parcel in Sendcloud for parcel tracking, using a valid tracking number and parcel details. This does not create a shipment or label in Sendcloud. It registers the parcel so you can retrieve its tracking events and status via the Parcel Tracking API. The **Create an external parcel for tracking** endpoint is currently in beta. While the core functionality is stable, some details or behavior may change as the feature evolves. We recommend reviewing release notes periodically for updates. ## Before you begin To use this endpoint, you must: 1. Make sure you’ve completed basic account setup. See the [Quickstart guide](/docs/getting-started). 2. Authenticate using API credentials (Basic auth) or OAuth2 client credentials. See [Authentication](/docs/getting-started/authentication). 3. Have a valid tracking number and carrier code for the parcel you want to track. ## Calling the endpoint To [create an external parcel for tracking](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) endpoint, send a `POST` request to: ```http Example request method and URL theme={null} POST https://panel.sendcloud.sc/api/v3/parcels/tracking ``` ### Required parameters To register a parcel for tracking, the following fields are required: | Status | Description | | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `announced_at` | The date and time the parcel was handed over to the carrier (ISO 8601 format). This establishes the starting point of the tracking lifecycle. | | `from_address` | The sender’s address object. At minimum, this includes: `address_line_1`, `postal_code`, `country_code`. This is used for validation and carrier tracking context. | | `to_address` | The recipient’s address object. At minimum, this includes: `address_line_1`, `postal_code`, `country_code`. | | `ship_with` | Provides information about which contract and shipping method were used to ship the parcel. | | `tracking_number` | Contains: `carrier_code` (Sendcloud carrier identifier), `tracking_number` (carrier-provided tracking number). This is the primary identifier used to retrieve tracking updates. | | `source_id` | A unique identifier from your own system. Use this to link the external parcel back to your internal order or shipment record. | No prior Sendcloud shipment or parcel ID is required — the API will register the parcel independently. To see the parcel in [Analytics](https://support.sendcloud.com/hc/en-us/sections/28788521497745-Analytics), include the `shipping_option_code` in the `ship_with` property. Parcels created without a shipping option code will not appear in analytics. You can retrieve valid shipping option codes via the [Shipping Options API](/docs/shipments/shipping-options-and-quotes). ### Optional parameters You may optionally include additional contextual information: * `details`: Additional parcel metadata such as: `brand_id`, `expected_delivery_date`, Service point flags * `parcel_items`: List of items included in the parcel. Useful for reporting and internal tracking. * `measurements`: Parcel dimensions and weight. Helpful for logistics analytics and reporting. * `insurance`: Insurance policy information if applicable. * `return_price`: Return price context if relevant. See the [API reference](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) for the full structure on both required and optional fields. ## Response If the request is successful, it’ll include: * **HTTP 200** status code * A Parcel Tracking object containing: * `created_at`: When the tracking object was created in Sendcloud * `announced_at`: When the parcel was handed to the carrier * `updated_at`: Last time tracking data was updated * `tracking_numbers` — Carrier tracking identifiers * `from_address` and `to_address` * `ship_with` * `details` (if available) * `parcel_items` (if provided) This object can later be queried using the [Retrieve tracking information for a parcel](/docs/parcel-tracking/retrieve-tracking-info) endpoint. ## Error Handling If required fields are missing or invalid, the API returns an error response. Common causes include: * Missing required nested fields in `from_address` / `to_address` * Invalid `tracking_number` format or missing carrier code * Missing `ship_with.properties.shipping_option_code` * Invalid or missing authentication credentials See the [API reference](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) for full error response details. # Parcel tracking overview Source: https://sendcloud.dev/docs/parcel-tracking/index The [Parcel Tracking API](/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel) allows you to register and monitor parcels in Sendcloud, even if they were not shipped via Sendcloud. By registering external parcels, you can retrieve their tracking timeline and integrate Sendcloud’s monitoring, analytics, and post-purchase visibility into your own systems. This API provides two core capabilities: * Register a parcel for tracking * Retrieve a complete timeline of tracking events Note: This guide covers our latest version, Parcel Tracking API v3. For full endpoint and schema documentation, see the [API reference](/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel). ## When to use the Parcel Tracking API Use the Parcel Tracking API when you want to: * Display tracking information to customers. * Monitor externally shipped parcels and/or internal shipments in back-office dashboards. * Automate post-purchase support workflows. * Analyze shipping performance, delivery timelines, and trends. Typical implementation scenarios include: * Tracking parcels fulfilled outside Sendcloud. * Consolidating tracking visibility across multiple logistics providers. * Building custom tracking portals or support tools. Note: High-frequency polling is discouraged. Webhook support for tracking external parcels is not yet available. ## How it fits into the Sendcloud workflow The Parcel Tracking API operates after shipment creation. Typical flow: * A parcel is shipped outside Sendcloud. * You register the parcel via the Parcel Tracking API. * Sendcloud begins monitoring tracking events. * You retrieve the tracking timeline via the API. * Tracking data is integrated into customer-facing portals, internal dashboards, or post-purchase workflows. Note: Tracking webhooks do not currently fire for parcels created via this API. Webhook support will be added in a future release. ## Key concepts | Concept | Definition | | ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Parcel Tracking object** | Represents a single parcel being tracked in Sendcloud. It is independent of Sendcloud shipments, meaning no shipment or label needs to exist in Sendcloud and no carrier announcement is triggered. This allows externally shipped parcels to be registered and monitored without using the Shipments API. | | **Tracking Events** | The Retrieve tracking information endpoint returns a timeline of parcel events. The timeline contains both historical and near-real-time updates. You can determine the parcel’s current status by inspecting the most recent event. The event types that can be shown include: | | **Internal (Sendcloud) events** | Updates generated by Sendcloud for parcels announced via Sendcloud. | | **Carrier tracking events** | Status updates received directly from the carrier reflecting the parcel’s physical journey. | # Retrieve tracking information Source: https://sendcloud.dev/docs/parcel-tracking/retrieve-tracking-info Use the [Retrieve tracking information for a parcel](/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel) endpoint to retrieve a parcel’s current status and full tracking timeline using its `tracking_number`. This endpoint works for: * Parcels created via Sendcloud shipments * External parcels registered for tracking via the [Create an external parcel for tracking](/api/v3/parcel-tracking/create-an-external-parcel-for-tracking) endpoint ## Calling the endpoint To [retrieve tracking information](/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel), send a `GET` request including the tracking number in the path: ```http Example request method and URL theme={null} GET https://panel.sendcloud.sc/api/v3/parcels/tracking/{tracking_number} ``` ## Response If successful, the API returns: * **HTTP 200** status code * A Parcel Tracking object containing: * Parcel lifecycle timestamps: * `created_at` — When the parcel tracking object was created in Sendcloud * `announced_at` — When the parcel was handed to the carrier * `updated_at` — Last time tracking information was updated * `details`: Additional context such as `expected_delivery_date`, `integration_id`, service point indicators, return flags * `tracking_numbers`: Carrier tracking identifiers associated with the parcel. * `events`: A chronological list of tracking events representing delivery milestones. * `parent_status`: carrier status messages standardized into a consistent Sendcloud status. This allows you to reliably interpret the parcel’s delivery state across different carriers. Each event has a single source. However, the full timeline may contain both carrier events and internal Sendcloud events (see [Parcel Tracking Key Concepts](/docs/parcel-tracking/index#key-concepts)). The parcel’s current status can be derived from the most recent event in the timeline. If the `tracking number` is invalid or unknown, the API returns an error response instead of a parcel object. See the [API reference](/api/v3/parcel-tracking/retrieve-tracking-information-for-a-parcel) for the full response schema. ## Status definitions Sendcloud consolidates all the variations of status messages received by different carriers into a readable format. This corresponds with the `parent_status` field in the response. | Status | Description | | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | Address invalid | The provided address details are not correct. | | Announced | The shipping label has been announced at the carrier. | | Announced: not collected | The label is announced, but not yet collected by the driver. | | Announcement failed | The label was not successfully announced at the carrier. | | At customs | The parcel is passing through customs checks at the border. | | At sorting centre | The parcel has arrived at the carrier sorting hub. | | Awaiting customer pickup | The parcel has been delivered to a service point and is awaiting collection by the end customer. | | Being announced | The shipping label is awaiting annoucnement at the carrier. | | Being sorted | The parcel is being sorted at the carrier sorting hub. | | Cancellation request | Cancellation has been requested for this parcel. | | Cancelled | The label was successfully cancelled at the carrier. | | Cancelled upstream | The label been cancelled upstream and is awaiting status Cancelled to be returned by the carrier. | | Delivered | The parcel has been delivered to the end customer. | | Delivery address changed | The delivery address has been modified. | | Delivery attempt failed | The end customer was not home to accept the delivery. | | Delivery date changed | The delivery date for this parcel was changed. | | Delivery delayed | The delivery will take place at a later time or date. | | Delivery method changed | The method of delivery has been modified. | | Driver en route | The driver is on the way to deliver the parcel. | | En route to sorting center | The driver is on the way to the sorting centre. | | Error collecting | The parcel could not be collected by the driver. | | Exception | There has been an exception with the parcel. | | No label | There is no label attached to the parcel. | | Not sorted | The parcel has not been sorted at the carrier sorting hub. | | Parcel en route | The parcel is on the way to be delivered. | | Ready to send | The label has been generated and announced, and the parcel can be picked up or taken to a service point to be delivered to the end customer. | | Refused by recipient | The end customer refused to accept the delivery. | | Returned to sender | The parcel is being returned to the sender. | | Return payment failed | Payment for the return label for this parcel has not been processed. | | Shipment collected by customer | The end customer has collected the parcel from a service point. | | Shipment picked up by driver | The driver has collected the parcel from the service point or requested pickup location. | | Sorted | The parcel has been sorted for delivery at the carrier sorting hub. | | Submitting cancellation request | Cancellation has been requested and is being processed. | | Unable to deliver | The parcel could not be delivered to the intended address or service point. | | Waiting for the return payment | The carrier must receive payment for the return label before it is returned to sender. | ## Real-time event notifications Instead of polling this endpoint for status changes, you can receive push notifications whenever parcel events occur. The [Event Subscriptions API](/api/v3/event-subscriptions/index) lets you configure webhooks or third-party integrations to be notified automatically. The Event Subscriptions API is currently in **BETA**. # Returns overview Source: https://sendcloud.dev/docs/returns/index The Sendcloud Returns API lets you create standalone return labels programmatically. No need to have shipped the original parcel through Sendcloud — this API works with any return scenario. ## What you can do * [Create return labels](/api/v3/returns/create-a-return) * [Validate returns](/api/v3/returns/validate-a-return) before creating labels * [Retrieve return](/api/v3/returns/retrieve-a-return) tracking information and status updates * [Cancel return labels](/api/v3/returns/request-cancellation-of-a-return) * [Filter returns](/api/v3/returns/retrieve-a-list-of-returns) by creation date, status, or other criteria ## Returns API Easily and efficiently create returns, even if the outgoing parcel was not shipped by Sendcloud. The Returns API endpoints support international returns and customs documentation, and gives you the ability to quickly look up which shipping method is most appropriate for your return. Explore the Returns API documentation and API playground ## Key differences from our Return portal API \[deprecated] The old Return portal API required you to: 1. Look up the original outgoing parcel 2. Generate JWT tokens from the lookup 3. Use those tokens to create a return The v3 Returns API is simpler: * No outgoing parcel lookup required * Works with standard API authentication * Creates standalone returns from any source ## Synchronous vs Asynchronous We offer both a [synchronous](/api/v3/returns/create-a-return-synchronously) and [asynchronous version](/api/v3/returns/create-a-return) of the same endpoint. Which one you should use generally depends on your data quality and performance needs. Provided your data quality is up to par using the [asynchronous endpoint](/api/v3/returns/create-a-return) is what we would recommend. It is a more performant endpoint. # Multicollo returns Source: https://sendcloud.dev/docs/returns/multicollo-returns [The v3 Returns API](/api/v3/returns/create-a-return) supports multicollo returns. This allows you to create a return shipment which consists of multiple parcels. One thing to keep in mind is that the way this endpoint supports multicollo is through replicating the same parcel details to create multiple parcels. This means that for shipments where customs documentation is involved the return should be consolidated to a single packaging unit to avoid unnecessary customs delays/issues. The parameter *collo\_count* will be used to set the amount of parcels that the incoming shipment will contain. Within the response we will return the parcel ID for each individual parcel created through this endpoint. For shipments requiring customs documentation, consolidate the return to a single packaging unit. The multicollo endpoint replicates parcel details, which can cause customs delays when documentation is split across multiple parcels. # Return methods Source: https://sendcloud.dev/docs/returns/return-methods ## Shipping options There are two ways to select the carrier method: `shipping_option_code` - preferred approach. get the codes from the [shipping options endpoint](/api/v3/shipping-options/return-a-list-of-available-shipping-options) by setting the returns functionality to `true`. Pass it in the `ship_with` object with type set to `"shipping_option_code"`. If you have multiple contracts for the same carrier you need to specify which contract id to use. `shipping_product_code` - legacy method from v2. Requires the shipping product code plus a functionalities object to filter which variant of that product you want. Only use this if you're migrating existing v2 code. ## International returns Crossing borders may mean customs. You need `parcel_items` with `hs_code` and `origin_country` for each item when shipping through customs. Customs won't clear it without proper classification. The `customs_invoice_nr` field must reference the original outbound invoice number. If you generate a new invoice number for the return, customs treats it as a fresh import and the customer gets hit with duties again so try to always match the outbound invoice exactly. The `customs_information` object needs the same invoice number plus `export_reason` set to `"returned_goods"` and the `return_data` section with outbound tracking number, shipment date, carrier name, and return postal code. This proves it's actually a return of previously imported goods. # Creating a parcel with service point delivery Source: https://sendcloud.dev/docs/service-points/creating-a-parcel-with-service-point-delivery **Service points**, also known as drop-off locations, are physical locations affiliated with one or more specific carriers. Parcels can be dropped off at these locations, and a driver will collect them and take them to be sorted at the carrier sorting hub. Parcels can also be delivered to service points as an alternative to door-to-door delivery. A service point can be a local post office, a brick-and-mortar store, or a fuel station. Service point delivery is an increasingly popular choice amongst e-commerce consumers, as it allows them to pick up their parcels at a time and location that's convenient to them. The customer can see when their parcel is ready for collection via the tracking number. You can activate tracking notifications via your Sendcloud account (see [Tracking parcels](/docs/archive/tracking/tracking-parcels/)) to automatically notify your customers when their parcel has been delivered and is awaiting collection from a service point. This tutorial will cover the basics of creating a parcel using a service point delivery method. ## Step 1: Enable service point delivery in your Sendcloud account Before you can begin using the API, you need to make that service points are enabled in your Sendcloud integration settings. Tip: If service points are not enabled for your integration, you'll see the following error message: “Service point support is not activated for this integration”. 1. In the Sendcloud platform, go to your [integration settings](https://app.sendcloud.com/v2/settings/integrations/manage) 2. Find your API integration in the list and click **Configure** 3. In the settings page for your API integration, **enable service points** 4. **Enable your desired carriers** for service point delivery and **save your changes** Screenshot showing how to enable service points in your Sendcloud integration settings ## Step 2: Retrieve a service point You need to find the id for the service point you want to deliver to before you can specify it in your request to the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. You can do so by making a `GET` request to the [Retrieve a list of service points](/api/v2/service-points/retrieve-a-list-of-service-points) endpoint and specifying a country and a search radius based on a postcode or a GPS location. ```http Request method and URL wrap theme={null} GET https://servicepoints.sendcloud.sc/api/v2/service-points?country=NL&address=5611%20EM&radius=1000 ``` The response to the request above will list all available service points within a 1 km radius of the postal code. Note that: * A service point `id` is assigned to each of the service points which are returned, e.g. `"id": 12345678`. This is the identifier we will use when creating the parcel, so that it is delivered to this specific service point. * The `carrier` field corresponds to the carrier which is associated with this particular service point * The response includes the opening times for all of the service points which were returned ## Step 3: Find a service point delivery method To ship a parcel to a service point, you need to select an appropriate shipping method. Now that we have a service point id, we can make a request to the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint to retrieve a list of methods that support delivery to the service point. ```http Request method and URL wrap theme={null} GET https://panel.sendcloud.sc/api/v2/shipping_methods?service_point_id=12345678 ``` The response will contain a list of shipping methods which support delivery to the specified service point. Each shipping method has an `id` field, which we will use when creating the parcel. ```json Response body snippet theme={null} { "shipping_methods": [ { "id": 123, "name": "Carrier X - Service Point Delivery" // ... other shipping method fields } // ... other shipping methods ] } ``` ## Step 4: Create the parcel Now we have both the service point `id` and an appropriate shipping method `id`, we can create the parcel using the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. To create a parcel which ships directly to a specific service point, make sure your request payload includes the following: 1. The service point id in the `to_service_point` field 2. The shipping method id for your service point delivery method in the `shipment` object ```http Request method and URL wrap theme={null} POST https://panel.sendcloud.sc/api/v2/parcels ``` ```json Request body snippet for a single parcel theme={null} { "parcel": { "shipment": { "id": 123 }, "to_service_point": 12345678 // ... other parcel fields } } ``` # How to include service points in your data flow Source: https://sendcloud.dev/docs/service-points/how-to-include-service-points-in-your-data-flow In this guide, you will find an explanation of how to incorporate Sendcloud service points in the data flow between your CMS (webshop), ERP/WMS systems, and Sendcloud. Please note that this guide includes most standard scenarios that you might encounter. ## Requesting a label based on service point selection Read our step-by-step guide on how to create a parcel that is delivered to a service point. ## How to determine which flow of data to use for the integration Refer to the following decision tree: Decision tree for service point integration ## Most common integrations | Integration | Service point id | To post number | | -------------------- | ------------------------------- | ------------------------------------ | | **Lightspeed** (new) | `order.shipmentData.location` | Not saved | | **Lightspeed** (old) | Not saved | Not saved | | **Magento v2** | `sendcloud_service_point_id` | `sendcloud_service_point_postnumber` | | **Prestashop** | Not saved | Not saved | | **Shopify** | Not saved | Not saved | | **Shopware 6** | `order.sendcloud_service_point` | Not saved | | **Woocommerce** | Not saved | Not saved | ## Custom-built plugins using Sendcloud service points In cases where we do not offer a plug-and-play integration with your CMS platform, or the integration does not save the service point ID to the webshop, there are two possible options: 1. Embed the [Sendcloud service points widget JavaScript code](https://support.sendcloud.com/hc/en-us/articles/360024967612-Service-points-for-API-Integrations) in your checkout Service point picker widget 2. Create your own service point picker plugin using our [Service Points API](/api/v2/service-points/retrieve-a-list-of-service-points). For both options, based on the end customer's selection, save the `service_point_id`, `to_post_number`, and `carrier` (as they are returned in the service point object) to the order in your webshop. This information can then be sent to the ERP/WMS when the order is synced. It's a good idea to save the carrier since this field can be used for setting more flexible shipping rules in Sendcloud; refer to the Standard flow section below. ### Standard flow As depicted in the diagram, the `service_point_id` (and potentially the `to_post_number`) are saved in the webshop and, most commonly, to the order. This information can then be sent to the ERP/WMS, where it is saved, and later can be sent to Sendcloud at the time of parcel creation. It's important to note that the `shipment` `id` has to be defined when creating a parcel to ship to a service point. This can be done via three methods: 1. Using [Sendcloud shipping rules](/docs/shipping/shipping-rules/). For example, when you have the following shipping rule: **if** the checkout delivery method is PostNL service point, **then** ship with "PostNL service point 0-23 kg", you would use the `shipment` `id` of `8` and set `"apply_shipping_rules": true` when creating a parcel with `"request_label": true`. The checkout delivery method name is defined in the webshop, and should also be sent to the ERP/WMS, and then to Sendcloud. 2. Use the [Retrieve a list of shipping methods](/api/v2/shipping-methods/retrieve-a-list-of-shipping-methods) endpoint to find shipping methods that ship to the service point. In the query parameters, use the `service_point_id`. 3. If the carrier is known in the ERP/WMS, the [Retrieve a list of shipping products](api/v2/shipping-products/retrieve-a-list-of-shipping-products) endpoint can be used to find an appropriate shipping method. Make sure to pass the `last_mile=service_point` query parameter. ```http Example request method and URL wrap theme={null} GET https://panel.sendcloud.sc/api/v2/shipping-products?from_country=NL&to_country=NL&carrier=postnl&weight=5&weight_unit=kilogram&last_mile=service_point ``` ## Fulfilling webshop orders via API flow Read a full explanation of this flow on [Fulfill orders](/docs/shipping/fulfill-orders). Note that when the integration fetches the shipment created by the webshop integration, the `to_service_point`, `to_post_number` and the `shipping_method` are also retrieved. # Brands Source: https://sendcloud.dev/docs/shipments/brands You can create your own brands in the Sendcloud platform to customise some of our key features and ensure you stay at the forefront of your customer's minds, even after they place their order. Creating a brand allows you to build your own [Return portal](/docs/returns/return-portal/), advertise your social media presence via the [tracking page](/docs/archive/tracking/) feature, and keep your customers updated through automated tracking notifications. You can create multiple brands in your account and link them to your sender addresses. [Read our guide on creating and managing brands](https://support.sendcloud.com/hc/en-us/articles/360041212392-How-to-set-up-your-brand-). ## How to associate a brand with a sender address Brands must be associated with a [sender address](/docs/getting-started/sender-addresses). If you have multiple sender addresses, you can associate a different brand with each one. This, in turn, will allow you to create a unique return portal, tracking page and tracking email design for each of your sites or store locations. When you [create a parcel](/docs/archive/shipping/create-a-parcel/), the brand which is linked to it will be based on the `sender_address_id` you specify in your request. If you don't specify a sender address, then your default address will be used to create the parcel. ### Steps to link a brand to a sender address 1. Log in to your Sendcloud account 2. Go to your address settings 3. Edit an address 4. Select the brand you want to associate with this address from the dropdown menu and **Save**. **Assigning multiple brands to one sender addresss** Only one brand can be assigned to a sender address. You can, however, create duplicate sender addresses and assign a different brand to each one. It's advised to give each duplicate address a different label (**Settings > Addresses > Sender addresses**) so you can easily identify which address is which throughout the Sendcloud platform. # Cancel a shipment Source: https://sendcloud.dev/docs/shipments/cancel-a-shipment To cancel a shipment, make a request to the [Cancel a shipment](/api/v3/shipments/cancel-a-shipment) endpoint and specify the shipment `id` you wish to cancel. The shipment stays in the system under its original ID, appearing in the Cancelled labels tab on the platform Labels can also be cancelled from the Sendcloud platform on the "Created labels" tab. Note: Cancelling a multicollo shipment (with multiple parcels) automatically cancels all associated parcels and their labels. ## Conditions for shipment cancellation Not all announced shipments can be cancelled; success isn't guaranteed and may be async based on shipment status. Each carrier will have different cancellation deadlines. Some carriers do not accept cancellation requests regardless of whether or not the shipment is cancelled within the deadline. You can find out more about cancellation deadlines and supporting carriers in our [help center](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment). If you don’t manage to cancel a shipment within the deadline, don’t worry. You’ll be charged for the shipment, but if you cancel it within 42 days and it remains unshipped, the cost will automatically be reimbursed on your next invoice. When the cost for a label is deducted, it will be clearly stated on your invoice. For more information see the [help center](https://support.sendcloud.com/hc/en-us/articles/360025144511-How-undelivered-shipments-appear-on-your-invoice). # Connect your carrier contract Source: https://sendcloud.dev/docs/shipments/carrier-contracts You can connect your own direct carrier contract with your Sendcloud account, so you can create shipping and return labels through the API using your pre-negotiated rates. **Beta**: You can now upload your own carrier pricing to Sendcloud so that you'll be able to retrieve your own rates when you retrieve shipping methods via the API. For more information, see our [help center](https://support.sendcloud.com/hc/en-us/articles/5163547066004-How-to-upload-your-own-prices-from-your-direct-carrier-contract). ## How to enable your own carrier contract 1. [Log in](https://account.sendcloud.com/login/) to your Sendcloud account. 2. In the [Carriers](https://app.sendcloud.com/v2/shipping/carriers/list) section of your account, find your carrier in the list and click **Add contract**. 3. Enter your carrier contract information in the relevant fields and click **Add this contract**. You can repeat the steps above to add as many direct contracts as you like. Screenshot of the 'Add contract' page in the Sendcloud platform Our help center has more information on [how to add contracts for specific carriers](https://support.sendcloud.com/hc/en-us/categories/360001511752-Carriers-). # Create a shipment Source: https://sendcloud.dev/docs/shipments/create-a-shipment Shipments can be created using the Sendcloud [Shipments API](/api/v3/shipments) in two different ways: * **Synchronous**: You receive the carrier announcement result immediately. Best suited for small batches or testing flows. * **Asynchronous**: You receive a shipment object right away, but must poll another endpoint to know if the carrier successfully processed it. Recommended for production-scale or multi-parcel flows. You’ll be invoiced for any shipments you create if you don’t cancel them within the [cancellation deadline](https://support.sendcloud.com/hc/en-us/articles/360025143991-How-do-I-cancel-my-shipment). You can create [test labels](/docs/getting-started/creating-test-labels) without receiving a charge by using the shipping option Unstamped letter (`"shipping_option_code": "sendcloud:letter"`) see the [Cancel a shipment page](docs/shipments/cancel-a-shipment) for more details. ## Synchronous announcement Use the synchronous endpoint when you need immediate feedback on whether the shipment was successfully announced to the carrier (for example, when shipping single parcels or low volumes). | Key details | | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | **Endpoint** | [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) | | **Max parcels per shipment** | **15** | | **Response** | Includes full shipment and parcel data, current shipment status, and any carrier errors returned during announcement. | ## Asynchronous announcement Use the asynchronous endpoint for most production flows, especially when dealing with higher volumes or multicollo (multi-parcel) shipments. | Key details | | | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ | | Endpoint | [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) | | Max parcels per shipment | **50** (note: carrier-specific limits may be lower) | | Response | Includes shipment and parcel data but no confirmation of whether it was successfully announced to the carrier. | | To check shipment status | Use the [Retrieve shipments](/api/v3/shipments/retrieve-shipments) endpoint to retrieve the announcement result and any possible carrier errors. | ## Request example Below is a minimal JSON example required to create a shipment - valid for both synchronous and asynchronous endpoints. ```json Example request body theme={null} { "to_address": { "name": "John Doe", "company_name": "Sendcloud", "address_line_1": "Insulindelaan 115", "house_number": "115", "postal_code": "5642CV", "city": "Eindhoven", "country_code": "NL", "phone_number": "+31612345678", "email": "john.doe@sendcloud.com", "po_box": "PO Box 678" }, "from_address": { "name": "Marie Doe", "company_name": "Sendcloud", "address_line_1": "Stadhuisplein 10", "address_line_2": "2e verdieping", "house_number": "10", "postal_code": "5611 EM", "city": "Eindhoven", "country_code": "NL", "phone_number": "+31612345678", "email": "marie.doe@sendcloud.com", "po_box": "PO Box 478" }, "ship_with": { "type": "shipping_option_code", "properties": { "shipping_option_code": "postnl:standard", "contract_id": 517 } }, "parcels": [ { "weight": { "value": "1.320", "unit": "kg" } } ] } ``` A typical shipment includes: * Sender and recipient addresses * A `shipping_option_code` and contract * One or more parcels with weight * Optional fields: parcel dimensions, items, insurance, customs details, or branding Note: Some carriers calculate shipping costs based on volumetric weight rather than actual weight. Volumetric weight is typically calculated using the formula (W × L × H)/divisor, where the divisor is defined in your agreement with the carrier or with Sendcloud. For shipments using a `shipping_option_code` associated with these carriers, parcel dimensions must be provided in addition to weight. If the request is successful, you'll receive: * HTTP 200 status code * A shipment object in the response body See the API reference response example for full schema details. A successful response includes: * `id`: The unique shipment ID (e.g. `"id": 189169249`), used for retrieving shipment data later. * `parcels[]`: List of associated parcel objects, each with its own parcel ID used to fetch documents like labels or customs forms. * `label_file` and carrier announcement results/errors (for synchronous announcements only). * Shipments that have been successfully announced to the carrier start with the status “Ready to Send.” You can view these shipments and their associated parcels in the Sendcloud panel under the Created Labels tab. Screenshot: Created Labels tab in Sendcloud panel ## Error Handling Synchronous shipment creation endpoints may return an HTTP 200 status code even if the carrier announcement fails. Always inspect the response's `errors` object for issues and verify the `shipment.status` field. A status of "Announcement Failed" confirms the carrier announcement did not succeed. For carrier-related failures after an HTTP 200, create a new shipment request to resolve the issue. **Shipments in "Announcement Failed" status incur no charges**. See the API reference for full error response details for the: * [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) * [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) ## Advanced Options Now that you’ve mastered the basics of creating a shipment, it’s time to uncover the full potential of our Shipments API. Explore the features below to help you automate, customise, and scale your shipping operations with ease: * Shipping rules and defaults: Save time by automating your shipping preferences. Set rules to automatically select shipping options, insurance amounts, or default order values based on a set of conditions. * Multicollo (Multiple parcels): Got an oversized order that won’t fit in one box? No problem! Create shipments with multiple parcels and track them all under a single master tracking number. * Shipment protection: Safeguard your deliveries against loss, theft, or damage with Sendcloud Shipment Protection. If something goes wrong, you can easily request a refund for your items. * International shipping: Sending orders across borders? We’ll take care of customs requirements for you. Generate the necessary documentation automatically, no extra hassle required. # Fulfill orders Source: https://sendcloud.dev/docs/shipments/fulfill-orders The following instructions apply to v2 of the Sendcloud API. Find out how an order, synced via a webshop integration to Sendcloud, can be fulfilled using a custom integration. Find more information about the endpoints in the [API v2 documentation](/api/v2). Before starting, it's good to be familiar with the following entities used in the Sendcloud ecosystem: | Entity | Definition | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Order** | This dataset contains information about an order made in the webshop. | | **Shipment** | This dataset contains information about the order and its destination. Shipments can have a parcel linked to them. Note that shipments are visually represented in the Incoming orders view of the Sendcloud platform. This means that on the front end the word “shipment” is not used. When working with our APIs, use shipments, not orders. | | **Parcel** | This dataset contains information about a shipment's delivery. When you work with a parcel, it typically comes with a label that's connected to the carrier. | | **Label** | Shipping labels display the key information for a carrier to transport a package from its start destination (e.g. your warehouse), to its end destination (the customer). Label design may differ for each carrier, but all labels have addresses, names, weights, and tracking barcodes. | And the following fields used in the Sendcloud API: | Field | Definition | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `order_number` | The order number imported from your Webshop, ERP, or WMS. It may contain duplicates because the imported number will not necessarily be unique. If you use Pack & Go and have a duplicate of the `order_number`, keep in mind that scanning the field will result in a ‘The order has already been processed’ error. | | Parcel `id` | The parcel `id` is automatically generated by Sendcloud when creating a parcel and is used to identify parcels within the platform. | | `shipment_uuid` | When you create a shipment, Sendcloud generates the `shipment_uuid` to identify it within the platform. Every shipment, synced by a webshop integration has a `shipment_uuid`. This field can be used to link a parcel to a shipment. | ## Overview This setup is useful if you want to have Sendcloud in the checkout of your webshop, while fulfilling orders from a different system, such as an ERP or WMS. It allows using Sendcloud's plug-and-play webshop integrations, which already have many features implemented. In this setup, shipments are sent to Sendcloud via a webshop integration and must be fulfilled via the Sendcloud API. You can create labels for shipments already in Sendcloud, and you don't even have to log into Sendcloud to fulfill orders and print labels. This could be done through a system of your choice, such as an ERP or WMS. This setup also allows you to ship parcels to a service point that the customer has selected in the webshop. ## Basic flow The webshop sends over shipments to Sendcloud. The fulfillment system also has the shipment data and can request labels directly from Sendcloud for a specific order via the custom integration setup. You can request a label when you have a parcel for the order. When you link a parcel to the shipment and request a label, Sendcloud will automatically update the webshop with information on the parcel. Note that sending the parcel information back to the webshop depends on the webshop's system. Some webshops might not have a field for track-and-trace links or carrier statuses as specific as Sendcloud does, for example — a webshop might only have Open and Shipped statuses, while Sendcloud offers more. Diagram showing the basic flow for sending data between a webshop, Sendcloud and a fulfillment system ## Technical flow The following sequence diagram breaks down the detailed flow of the setup. The custom integration should cover the steps in the purple box in the middle of the diagram: Sequence diagram showing the detailed flow for sending data between a webshop, Sendcloud and a fulfillment system ## Fetch a shipment To acquire the shipment details of orders sent in by an official integration, make a `GET` request to the [Retrieve a list of shipments](/api/v2/integrations/retrieve-a-list-of-shipments) endpoint. In the `GET` request, specify a query parameter that matches the `order_number`, and `external_order_id` (if applicable) or `external_shipment_id` (if applicable) parameters. These fields are originally inserted by the shop system integration. In the request URL, specify the integration ID. To retrieve the integration ID, use the [Retrieve a list of integrations](/api/v2/integrations/retrieve-a-list-of-integrations) endpoint. Note that If you have multiple webshop integrations connected to your Sendcloud account, it should be clear which order number is attached to which integration ID. ## Fetch a parcel In some cases, the webshop integration might be directly creating **parcels** in Sendcloud rather than **shipments**, e.g. a custom webshop integration. In this case, make a `GET` request to the [Retrieve parcels](/api/v2/parcels/retrieve-parcels) endpoint. In the `GET` request, specify a query parameter that matches the `order_number` field. ## Create a parcel and request a label When the order details have been acquired, you can create the parcel and request the label. To do this, use the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint. Note that when creating the parcel, you can redefine most of the fields. The parcel fields do not need to be equal to the original shipment. However, some fields do need to be the same for the described setup to work as intended: | Field | Definition | | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `shipment_uuid` | The webshop feedback uses this field to link the parcel with the shipment. | | `service_point_id` | The service point ID of the shipment. | | `to_post_number` | The Post number field of shipment. | | `shipping_method_checkout_name` | This is a text field used for matching in shipping rules. It usually has the webshop checkout's shipping method name, but can be changed if the name isn't clear enough for setting a rule. | ## Fetch the label The [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint response includes various ways to fetch the label: 1. The `label` field in the response: * `normal_printer` provides an A4 document with the label on it. The default format is PDF. Note that the `start_from` parameter in each URL determines where the label will be printed on the page: top left, top right, bottom left and bottom right. See the [Retrieve a PDF label](/api/v2/labels/retrieve-a-pdf-label) endpoint. * `label_printer` provides an A6 label document for label printers. See the [Retrieve a PDF label for a specific label printer](/api/v2/labels/retrieve-a-specific-pdf-label-for-a-label-printer) endpoint. 2. The `documents` field contains a `label` URL, plus (if applicable) additional documents for international shipments outside of the EU. See the [Retrieve parcel documents](/api/v2/parcel-documents/retrieve-parcel-documents) endpoint. * Note that it is possible to get the label in different formats including ZPL using the API v3 [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint. To download the label, redirect to that link and provide the same API credentials used to request the label. The link cannot be opened if these credentials are not provided. # Overview Source: https://sendcloud.dev/docs/shipments/index You can create and manage [Shipments](/docs/getting-started/key-concepts#shipments) programmatically using the [Shipments API v3](/api/v3/shipments). This API lets you automate the complete shipment lifecycle without manual input in the Sendcloud platform. All shipments remain visible in your Sendcloud account, so you can review, troubleshoot, or adjust them when needed. ## What you'll learn This guide explains how to: * Create and announce shipments (synchronous and asynchronous flows) * Use shipping rules and shipping defaults for shipment creation (synchronous and asynchronous flows) * Retrieve or cancel shipments * Manage advanced scenarios, such as branding shipments, handling multi-parcel (multicollo) shipments, and sending international orders Note: This guide covers our latest version, Shipments API v3. For full endpoint and schema documentation, see the [API reference](/api/v3/shipments). ## When to use the Shipments API Use the Shipments API when you already have shipping-ready data and want to move directly into fulfillment - without first creating orders in Sendcloud. Typical use cases include: * Shipping directly from an ERP, WMS, or fulfillment system * Creating shipping labels without storing commercial order data * Managing high-volume or complex shipments programmatically * Creating multi-parcel (multicollo) shipments with per-parcel details Shipments do not require an order. While you can combine the Orders and Shipments APIs, the Shipments API is designed to operate independently when commercial data is handled elsewhere in your workflow. # International shipping Source: https://sendcloud.dev/docs/shipments/international-shipping Sendcloud enables you to deliver orders from Europe to destinations across the globe, through a large selection of reliable and cost-effective shipping methods. ## Customs documents Customs documents are **always required** for parcels shipping to destinations outside the EU. In most cases a commercial invoice is required by commercial carriers (e.g. UPS and DHL), however postal carriers (e.g. PostNL and Royal Mail) require a CN22 or CN23 form. Sendcloud will automatically generate the correct type of documentation for your parcel when you create an international parcel through our API. You just need to include some additional properties in your API call, as listed below. **Tip:** You can find extensive guides to help you navigate the various types of documentation required for international shipping, and tips on shipping post-Brexit, in our [help center](https://support.sendcloud.com/hc/en-us/sections/360008404271-International-Shipping). ## Required fields for international shipments When you [create a parcel](/docs/archive/shipping/create-a-parcel) for an international shipment, you need to include the properties below in your request. This is to ensure that customs documentation can be correctly rendered, and that the items in your order are listed alongside their value and description, as required. | Parameter | Type | Required | Description | | --------------- | -------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ | | `country_state` | `string` | Yes (for Australia, Canada, Italy and USA) | Code of the state (e.g. New York = `NY`). | | `parcel_items` | `array` of `parcel_item` objects | Yes | An array of objects describing the items in the parcel. See the [parcel item object](#parcel-item-object) section below for details. | ### Parcel item object The following properties should be included in each object in the `parcel_items` array: | Parameter | Type | Required | Description | | ---------------- | ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------ | | `description` | `string` | Yes | Description of the product | | `quantity` | `integer` | Yes | Number of items shipped | | `weight` | `string` (as a decimal number) | Yes | Weight of the product in kilograms | | `value` | `string` (as a decimal number) | Yes | Value of the product, to 2 decimal places | | `hs_code` | `string` | Yes | 8 digit [Harmonized System](https://en.wikipedia.org/wiki/Harmonized_System) code for the product | | `origin_country` | `string` | Yes | [ISO 3166-1 alpha-2 country code](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) for the product's origin | | `product_id` | `string` | No | Your internal ID for the product | | `properties` | `array` of `property` objects | No | Properties of the product, e.g. `color: "Black"` | ```json Example parcel_items array theme={null} { "parcel_items": [ { "description": "T-Shirt", "hs_code": "6109", "origin_country": "SE", "product_id": "898678671", "properties": { "color": "Blue", "size": "Medium" }, "quantity": 2, "sku": "TST-OD2019-B620", "value": "19.95", "weight": "0.9" } ] } ``` **Tip:** Adding items to commercial invoices & CN22/23 customs forms The amount of items you can include on a single commercial invoice differs depending on the type of shipping carrier you have selected. For a full overview, refer to our [help center](https://support.sendcloud.com/hc/en-us/articles/360042555232-How-to-download-customs-documents-through-Sendcloud) ## Providing additional customs information with the `customs_information` object The `customs_information` object contains optional customs information that should be provided for international parcels. The parameters are listed in the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels#body-parcel-customs-information) endpoint specification. The tax number validation for the `tax_number` field in this object is implemented with the following principles: * By Sender: the country code can match either the sender country code or the destination country code. * By Receiver or Importer of record: the country code can match only the destination country code * For IOSS, the country code can contain any value in the EU and does not follow the logic above. ## Downloading customs documents Once you have created an international parcel via the API, the response will contain customs documents for the parcel in the `documents` object. ```json Example response body theme={null} { // ... other parcel properties "documents": [ { "type": "commercial-invoice", "size": "a4", "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/commercial-invoice" }, { "type": "label", "size": "a6", "link": "https://panel.sendcloud.sc/api/v2/parcels/1/documents/label" } ] } ``` In most cases, you'll need to download and print the documents, ready to attach them to your parcel. Note that some carriers require multiple copies of the commercial invoice or CN23 form to be attached to the parcel. You can download documents using the URL provided in the response, or via the [Retrieve parcel documents](/api/v2/parcel-documents/retrieve-parcel-documents) endpoint by providing the parcel `id`. **Tip: Paperless trade** Sendcloud supports digital sending of customs documents for carriers who support Paperless trade. You can find a list of supporting carriers in our [help center](https://support.sendcloud.com/hc/en-us/articles/4417349714452-Send-your-customs-documents-digitally-via-Paperless-Trade-). # Multicollo Source: https://sendcloud.dev/docs/shipments/multicollo ## What is multicollo? Multicollo is a feature that allows sending multiple parcels to be shipped and delivered simultaneously at a higher chance of lower costs by supported carriers. It is handy for merchants who usually send bulky items (e.g. bicycles, gym stations) or different items purchased together that do not fit in one parcel. In this context, a shipment is a group of parcels that are announced together, and each parcel has its own items and shipping label. All multicollo parcels must be sent from the same sender address to the same destination address. ## Creating multicollo shipments Multicollo shipments can be created using the Sendcloud [Shipments API (v3)](/api/v3/shipments) or manually in the Sendcloud platform (learn more in [our help center](https://support.sendcloud.com/hc/en-us/articles/360038716852-How-to-create-multicollo-shipments)). If you are currently using the legacy Parcels API (v2), see the [migration section below](docs/shipments/multicollo#migrating-from-the-parcels-api-v2-to-the-shipments-api-v3). Using the Shipments API allows you to provide detailed parcel information such as weight, dimensions, and items for each parcel in the shipment. Providing more accurate parcel details ensures a smoother shipping process, reduces the chance of unexpected carrier surcharges, and may reduce shipping costs depending on your carrier contract and rates. Some carriers currently support multicollo shipments only via the Sendcloud platform or legacy APIs. See the [supported carriers](/docs/shipments/multicollo#supported-carriers) section below for details. ## Creating multicollo shipments via the Shipments API Use the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint to create and announce a multicollo shipment asynchronously. For each parcel in a multicollo shipment, add a separate object to the `parcels` array in your request. We recommend providing weight and dimensions info per parcel to avoid potential carrier surcharges. After creating the shipment: * Use the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint to check the announcement results * Use the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) endpoint to retrieve the labels ## Supported carriers Not all carriers support multicollo shipments. To retrieve shipping options that support multicollo shipments, use the [Shipping options API](/api/v3/shipping-options/create-a-list-of-shipping-options) and make a `POST` request with `{"functionalities": {"multicollo": true}}` in the body. The response returns shipping options that support multicollo shipments. Currently international multicollo shipments are only supported in API v3. Some restrictions apply to multicollo shipments. See our [help center](https://support.sendcloud.com/hc/en-us/articles/360038716852-How-to-create-multicollo-shipments) for more information. ## Multicollo labels The shipping label will reflect the total number of parcels in the consignment and, depending on the carrier, each parcel's position in the shipment (for example: 1/3, 2/3, 3/3). Each parcel will have a **unique tracking number**, but the customer will only receive **one tracking email** for the entire shipment. Example of a multicollo label for DPD. The label says 'Packages 1 of 5'. ## Avoid being charged for unused multicollo shipments If you create a shipment using this API but decide not to ship it, you can avoid being charged by using the [Cancel a shipment](/api/v3/shipments/cancel-a-shipment) endpoint. When a multicollo shipment is canceled, all labels from that shipment become canceled. ## Finding the `shipping_option_code` Make a request to the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint. The top-level `code` field in each shipping option object is the `shipping_option_code` to be used with the Shipments API. In the example response below, the value `dpd:home` is the `shipping_option_code` used in the `ship_with` field when creating a shipment: ```json Response body theme={null} { "data": [ { "code": "dpd:home", // This is the shipping_option_code "carrier": { "code": "dpd", "name": "DPD" }, "product": { "code": "dpd:home", "name": "DPD Home" }, "functionalities": { // ... trimmed for brevity }, "contract": null, "weight": { "min": { "value": "0.001", "unit": "kg" }, "max": { "value": "31.501", "unit": "kg" } }, "max_dimensions": { "length": "175.00", "width": "0.00", "height": "0.00", "unit": "cm" }, "billed_weight": { "unit": "kg", "value": "1.320", "volumetric": false }, "requirements": { "fields": [], "export_documents": false }, "quotes": null } // ... other shipping options ] } ``` ## Migrating from the Parcels API (v2) to the Shipments API (v3) If you previously created multicollo shipments using the Parcels API (v2), you can migrate to the Shipments API (v3) to benefit from improved multicollo functionality. Key differences: * **Parcels API (v2)**: Multicollo shipments were created by specifying the number of parcels in the quantity field. * **Shipments API (v3)**: Each parcel is defined individually inside the parcels array. 1. Use the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint instead of the [Create a parcel or parcels](/api/v2/parcels/create-a-parcel-or-parcels) endpoint 2. To find a `shipping_option_code` for use in the `ship_with` field for the Shipments API, you can use the [Create a list of shipping options](/api/v3/shipping-options/create-a-list-of-shipping-options) endpoint * Also, if you have a direct contract with the carrier, you can add the `contract_id` to the request body (the id can be obtained through the [Retrieve a list of contracts](/api/v3/contracts/retrieve-a-list-of-contracts) endpoint) 3. Update your payload to match the expected request body in the [Create and announce a shipment asynchronously](/api/v3/shipments/create-and-announce-a-shipment-asynchronously) endpoint * For multicollo, the main change is that instead of specifying a `quantity` when creating a parcel, you can now specify each parcel's details by adding a separate parcel object in the `parcels` array for each parcel in your multicollo shipment. Providing parcel-specific details (weight, dimensions, items) allows more accurate carrier announcements and improves shipping reliability. # Pack and Go Source: https://sendcloud.dev/docs/shipments/pack-and-go Pack & Go is a Sendcloud feature available to users on our **Growth** subscription plan and above. It's designed to let you print labels for large volumes of orders, either by scanning a picking list or individual packing slips with a barcode scanner, or by manually processing orders one by one from the Pack & Go interface. ## How to process parcels created via the API with Pack & Go Pack & Go supports processing orders created via the API, using the [Orders API](/api/v3/orders) endpoint. These orders will appear in the Pack & Go interface, so you can then use Pack & Go to pack your orders, verify the items and print the shipping label. Find out more about Pack & Go and how it works in [our help center](https://support.sendcloud.com/hc/en-us/articles/26015547617297-Understanding-Pack-Go). # Pickups Source: https://sendcloud.dev/docs/shipments/pickups You can schedule a carrier pickup to have your parcels collected by a delivery driver. When you schedule a pickup via the Sendcloud API, the sender address is dynamic, which means that you can request the pickup to take place at an address of your choice. You can only schedule a **one-time** (incidental) pickup using the v3 [Pickups API](/api/v3/pickups/create-a-pickup). If you ship large volumes of orders every week and would like to schedule a recurring pickup on a weekly or bi-weekly basis, you can [contact your sales representative](https://support.sendcloud.com/hc/en-us/articles/360046514071-Contact-us-) to arrange this on your behalf. ## How to schedule a pickup Pickups can be scheduled by making a `POST` request to the [Create a pickup](/api/v3/pickups/create-a-pickup) endpoint. You can specify a time window for the pickup to take place when you make the request. Tip: You should schedule your collection at least 2 working days in advance to allow for processing time. # Print your labels Source: https://sendcloud.dev/docs/shipments/print-your-labels Now that you have created a shipment, it’s time to generate and download the shipping labels for the parcels in that shipment. You can obtain labels in three main ways: 1. Use the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) or [Retrieve multiple parcel documents](/api/v3/parcel-documents/retrieve-multiple-parcel-documents) endpoints and pass the parcel IDs of the parcels you want labels for, with `type=label` as the document type parameter. 2. Use any announcement endpoint of Shipments API v3. In their responses you receive a `parcels.documents` array containing links to the [Retrieve a parcel document endpoint](/api/v3/parcel-documents/retrieve-a-parcel-document); select the document where `type` is `"label"` to download the label. 3. Use the [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) or [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously) endpoints for single-parcel shipments (single collo). In this case, the label file is immediately available in the response in `parcels.label_file`. Besides using the API, you can also download labels directly from the Sendcloud platform under the *Created labels* tab. In the platform, each parcel is marked with a status: **Printed** if the label has already been downloaded, or **Not printed** if it has not yet been downloaded. Note: When using the [Create and announce a shipment synchronously](/api/v3/shipments/create-and-announce-a-shipment-synchronously) or [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously) endpoints for single-parcel shipments (single collo) announcement, the shipping labels are immediately marked as **“Printed”** because a label file is instantly returned in the API response. ## Label formats and sizes By default, labels are returned as PDF in the original carrier label size, which for most carriers is A6. You can change both the file format and, when retrieving documents, the paper size. Supported formats: * PDF (default for all carriers). * ZPL (native or converted, see below). * PNG (converted from PDF). Supported paper sizes when retrieving labels: * A4 * A5 * A6 (original label size for most carriers) ### Change label size To change the size of a label, set the paper\_size parameter (for example `paper_size=A4`) on the [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) or [Retrieve multiple parcel documents](/api/v3/parcel-documents/retrieve-multiple-parcel-documents) endpoints. It is not possible to set the label size during shipment creation; label size is only adjustable at retrieval time. ### ZPL labels Sendcloud supports two ways of generating ZPL labels: * **Native carrier ZPL**: For carriers that support native ZPL, you can request a native ZPL label by setting `"label_details.mime_type": "application/zpl"` during shipment creation. When you request a native ZPL label from a carrier, the resulting label format is fixed. Later calls to [Retrieve a parcel document](/api/v3/parcel-documents/retrieve-a-parcel-document) or [Retrieve multiple parcel documents](/api/v3/parcel-documents/retrieve-multiple-parcel-documents) endpoints for that label will always return ZPL and cannot be converted to another file type. * **Converted ZPL from PDF**: For carriers that do not support native ZPL, Sendcloud converts PDF labels to ZPL using a carrier-approved internal conversion process. You can obtain a converted ZPL label either by setting `"label_details.mime_type": "application/zpl"` on shipment creation for carriers that do not support native ZPL labels or by setting the `Accept` header to `application/zpl` when calling the [Retrieve a parcel document endpoint](/api/v3/parcel-documents/retrieve-a-parcel-document). Most carriers use a resolution of 203 DPI for ZPL labels. Make sure your Zebra or other thermal printer is configured to print at the same DPI as the label to avoid scaling and readability issues. ### PNG labels PNG labels are always generated by converting a PDF label to a PNG image inside Sendcloud. You can obtain PNG labels in two ways: * Set `"label_details.mime_type": "image/png"` during shipment creation. * Set the Accept header to image/png when calling the Retrieve a parcel document endpoint. For PNG labels you can control the image resolution with the `dpi` parameter, typically set to 150 or 300 DPI, depending on your printer capabilities and desired quality. Congrats! You’ve just created your first shipment and downloaded the shipping label via the API. # Retrieve a shipment Source: https://sendcloud.dev/docs/shipments/retrieve-a-shipment Access all shipment details through two dedicated endpoints that return identical per-shipment data. ## Retrieve Shipments Endpoint Use the [Retrieve shipments](/api/v3/shipments/retrieve-shipments) endpoint to list multiple shipments efficiently. You can use query filters to narrow your results such as announcement time, update time, integration, and other fields - full list in the [API reference](/api/v3/shipments/retrieve-shipments#parameter-one-of-0). You can also specify up to 100 shipment IDs for targeted retrieval. The endpoint supports pagination via Link headers (`next` and `prev`) ## Retrieve a Shipment Endpoint Use the [Retrieve a shipment](/api/v3/shipments/retrieve-a-shipment) endpoint for details on one specific shipment. Ideal when you know the exact shipment ID, no filtering or pagination needed Both endpoints ensure a consistent data structure for seamless integration. # Shipping options & quotes Source: https://sendcloud.dev/docs/shipments/shipping-options-and-quotes Choosing a shipping option code is required when creating a shipment via the Sendcloud API. Use the [Return a list of available shipping options](/api/v3/shipping-options/return-a-list-of-available-shipping-options) endpoint to retrieve available options based on shipment details like from/to countries, weight, dimensions, and carrier. This ensures you select the correct `shipping_option_code` for creating shipments or returns. Some shipping options are only available when you [connect a direct carrier contract](/docs/shipments/carrier-contracts), while others are enabled once you [activate a carrier in your Sendcloud account](https://support.sendcloud.com/hc/en-us/articles/360025133311-Choose-your-carriers-), so you can start shipping with them straight away. Note: When creating a return you will also be required to provide a `shipping_option_code`. You can follow the exact same process as when choosing a `shipping_option_code` for an outgoing shipment. ## Retrieve shipping options To retrieve a list of shipping options which can be used to create a shipments, make a `POST` request to the [Return a list of available shipping options](/api/v3/shipping-options/return-a-list-of-available-shipping-options) endpoint. The shipping options that will be retrieved appear based on the following factors: * The carriers you have [enabled in your Sendcloud account](https://support.sendcloud.com/hc/en-us/articles/360025133311-Choose-your-carriers); * The from and to countries you define; * Weight and Dimensions of the parcels you define; * More advanced options such as [functionalities](#shipping-functionalities) of the shipping options you wish to use or [service points you wish to ship to](#service-point-shipping-options) Use the `from_address` and `to_address` objects to specify the origin and destination. The more address details you provide (such as `postal_code`, `city`, `address_line_1`, and `state_province_code`), the more accurate the pricing will be — including zonal prices and remote area surcharges. For the most accurate pricing, use `from_address` and `to_address` with as many fields filled in as possible. Below you can see an example JSON request payload you could send to request a list of shipping options: ```json Example request payload theme={null} { "from_address": { "country_code": "NL", "postal_code": "1012AB", "city": "Eindhoven" }, "to_address": { "country_code": "NL", "postal_code": "2000AB", "city": "Amsterdam" }, "carrier_code": "dhl", "calculate_quotes": true } ``` No query parameters are required to retrieve shipping options. Without filters, the endpoint returns all shipping options activated in your account. Adding filters narrows results using AND logic - the more filters applied, the fewer matches returned. For example, combining a `from_address` with `"country_code": "NL"` and `"carrier_code": "dhl"` shows only DHL options available from the Netherlands. It does not include all Netherlands options plus all DHL options separately. The legacy flat fields (`from_country_code`, `from_postal_code`, `to_country_code`, `to_postal_code`) are still supported but deprecated. The address objects and flat fields are **mutually exclusive** — do not combine them in the same request. If the request is successful, you'll receive: * HTTP 200 status code * A list of shipping options in the response body See the [API reference response section](/api/v3/shipping-options/return-a-list-of-available-shipping-options#response-data-one-of-0) for full schema details. A successful response includes: * `code`: The unique shipping option code to be used when creating a shipment * `requirements`: List of fields that will be required when creating a shipment with a given option (e.g.: email, dimensions) * Other more advanced fields such as [quotes](#shipping-options-quotes) and [functionalities](#shipping-functionalities) You will still get a HTTP 200 status code when an empty list of shipping options is returned. This indicates no active options in your account match the applied filters. Activate additional options by following [this guide](https://support.sendcloud.com/hc/en-us/articles/40787957696145-Enable-shipping-methods). ## Shipping options quotes ### Receive discounts on your shipping labels You don't need to have a carrier contract to access shipping options in Sendcloud. You can create shipments using Sendcloud rates, and receive a discount on your label price based on your subscription plan. The higher your plan, the more discount you’ll receive. ### Retrieve shipping options quotes Set `"calculate_quotes": true` in the request to the Shipping Options endpoint to include pricing in responses. The response then contains a `quotes` object for each matching option. The `quotes` object returns empty if pricing can't be calculated, which occurs when: * No origin or destination is provided (via `from_address`/`to_address` or the legacy `from_country_code`/`to_country_code` fields) * Direct contracts lack uploaded rates (learn [how to connect your own contracts](/docs/shipments/carrier-contracts) and [how to upload your direct contract rates](https://support.sendcloud.com/hc/en-us/articles/5163547066004-How-to-upload-your-own-prices-from-your-direct-carrier-contract)) Each API call returns quotes for one contract per carrier only. Without a specified `contract_id`, Sendcloud uses your default contract per carrier. Compare same carrier contracts by making separate calls with different `contract_id` values. ## Advanced options ### Shipping functionalities Once you're familiar with making API calls to retrieve shipping options, you may want to filter for shipping options based on their added-value services, known as shipping functionalities. An example of this would be the ability to only retrieve shipping options which require a “Signature on receipt” or that allow you to ship fresh goods. Available functionalities and their meanings are listed in the [API reference](/api/v3/shipping-options/return-a-list-of-available-shipping-options#body-functionalities-one-of-0). ### Service point shipping options Use service point shipping options for shipments to pickup locations. Filter results with `"functionalities.last_mile": "service_point"` to show only compatible options. For a specific service point, add its `to_service_point_id` to the request. You can retrieve service point IDs via the Service Points endpoint. Service point IDs can be retrieved using the [Service Points API](/api/v2/service-points). Although this endpoint is currently available in API v2, it is [fully compatible with API v3](/docs/getting-started/migration-guidelines-for-api-v3#api-v2-endpoints-that-are-compatible-with-api-v3) and can be used together with the Shipments API V3. ### Return shipping options Return shipping options prioritize consumer experience and differ from standard outbound options. Filter for them by including `"functionalities.returns": true` in your request. # Shipping rules & shipping defaults Source: https://sendcloud.dev/docs/shipments/shipping-rules-and-shipping-defaults [Shipping rules](https://support.sendcloud.com/hc/en-us/articles/10274470454292-How-to-create-shipping-rules) and [shipping defaults](https://support.sendcloud.com/hc/en-us/articles/12213808740116-How-to-set-up-your-default-shipping-settings) are predefined actions that automatically apply to your shipments whenever certain conditions are met. You can configure these in your Sendcloud account to streamline and automate your shipping workflows. An example shipping rule: If \[parcel weight] *is less than* \[10kg], *ship with* \[PostNL Home address only] There’s a wide range of conditions and actions to choose from, covering nearly every part of the shipment creation process. Once configured, shipping rules and defaults can be applied to shipments created through the API. ## Applying Shipping Rules via the API You can apply shipping rules and defaults to your shipments in the same way as described in the [Create a shipment](/docs/shipments/create-a-shipment) section. There are two ways to do this: * [Synchronous creation](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously): Creates and announces the shipment immediately, returning the carrier’s response right away. Ideal for smaller batches or testing scenarios. * [Asynchronous creation](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously): Creates the shipment instantly, but you’ll need to poll another endpoint to check the carrier’s announcement status. Recommended for large-scale or multi-parcel operations. All conditions described in the [synchronous](/docs/shipments/create-a-shipment#synchronous-announcement) and [asynchronous](/docs/shipments/create-a-shipment#asynchronous-announcement) announcement endpoints also apply to these “create with rules/defaults” endpoints. Note: By default, shipping rules and shipping defaults are always applied when using the Create a shipment with rules and/or defaults endpoints ## Minimal Request Example Because shipping rules can set most parameters automatically, the only required field when creating a shipment with rules and/or defaults is the `to_address` object. All other shipment details can be filled in dynamically based on your rules. Below is a minimal JSON example required to create a shipment with shipping rules and/or shipping defaults - valid for both synchronous and asynchronous endpoints. ```json Example request body theme={null} { "to_address": { "name": "John Doe", "company_name": "Sendcloud", "address_line_1": "Insulindelaan 115", "house_number": "115", "postal_code": "5642CV", "city": "Eindhoven", "country_code": "NL", "phone_number": "+31612345678", "email": "john.doe@sendcloud.com", "po_box": "PO Box 678" } } ``` If you want to include a shipping option code in your request—even if a shipping rule will likely override it—use the placeholder option: `"shipping_option_code": "sendcloud:letter"` (Unstamped letter). When successful, the API returns: * **HTTP 200** status code * A shipment object in the response body See the API reference for detailed response schema examples: * [Create a shipment with rules and/or defaults and announce it synchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-synchronously) * [Create a shipment with rules and/or defaults and announce it asynchronously](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously) ## Overriding Shipping Rules or Defaults If you occasionally want to bypass automation for specific shipments, you can disable these features by setting: * `"apply_shipping_rules": false` * `"apply_shipping_defaults": false` If a shipment created with rules applied doesn’t meet your expectations, you can [cancel it](docs/shipments/cancel-a-shipment) and create a new one - either with or without shipping rules and/or defaults. ## Shipping Rules and Defaults API Limitations Not all shipping rules or actions can be applied through this API due to the shipment data available at the time of request. Some conditions and actions depend on information or processes that are only accessible within the Sendcloud Platform. Additionally, even rules that can normally be applied to single‑collo shipments may not fully work for multi‑collo shipments, as certain rule conditions are evaluated per parcel rather than per shipment. To view the complete list of shipping rule limitations for this endpoint, refer to the documentation [here](/api/v3/shipments/create-a-shipment-with-rules-and-or-default-and-announce-it-asynchronously#shipping-rules). # Introduction Source: https://sendcloud.dev/index Sendcloud is an **all-in-one shipping solution**, designed to make the lives of e-commerce retailers easier by automizing your processes and consolidating all of your shipping activities into a single platform. We connect online sellers to a diverse catalog of international shipping products and delivery options from **160+ carriers across Europe**. Alongside our partner carriers, we provide integrations with **100+ e-commerce platforms**, WMS systems, and marketplaces. Sendcloud APIs provide the necessary features and tools to help you build your shipping automation around the Sendcloud platform, enabling you to streamline your shipping process and automate your logistics flow. Quickly onboard with our APIs Guidelines to help you move from API v2 to API v3 ### Explore our APIs Create and manage shipments Create and manage orders Automate your returns Create a shipment and request a label in one step