Skip to main content

Documentation Index

Fetch the complete documentation index at: https://sendcloud.dev/llms.txt

Use this file to discover all available pages before exploring further.

Choosing a shipping option code is required when creating a shipment via the Sendcloud API. Use the 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, while others are enabled once you activate a carrier in your Sendcloud account, 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 endpoint. The shipping options that will be retrieved appear based on the following factors: 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:
Example request payload
{
  "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 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 and 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.

​
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:
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.

​
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. Although this endpoint is currently available in API v2, it is fully 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.