Skip to main content
POST
/
checkout
/
delivery-options
curl --request POST \
  --url https://panel.sendcloud.sc/api/v3/checkout/delivery-options \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "total_weight": {
    "value": "2500"
  },
  "total_price": {
    "value": "45.90"
  },
  "from_address": {
    "country_code": "NL"
  },
  "to_address": {
    "country_code": "NL",
    "postal_code": "5611EM"
  }
}
'
{
  "configuration_id": "bae462c1-d659-48d0-aacd-fb7e3550de14",
  "delivery_options": [
    {
      "id": "431c1736-9a8f-480a-bf27-234016918417",
      "title": "DHL Delivery - Standard",
      "internal_title": "standard_delivery_dhl",
      "description": "Reliable and cost-effective delivery for your order",
      "delivery_method_type": "standard_delivery",
      "cut_off_time": "2024-11-27T15:00:00+01:00",
      "checkout_identifier": {
        "type": "shipping_option_code",
        "value": "dhl:complete/standard"
      },
      "shipping_rate": {
        "value": "5.00",
        "currency": "EUR"
      },
      "carrier": {
        "code": "dhl",
        "name": "DHL",
        "logo_url": "https://sendcloud-prod-scp-static-files.s3.amazonaws.com/dhl/img/logo.svg"
      },
      "delivery_dates": null,
      "lead_time_hours": {
        "p10": 48,
        "p20": 48,
        "p30": 72,
        "p40": 72,
        "p50": 96,
        "p60": 96,
        "p70": 120,
        "p80": 120,
        "p90": 144,
        "p95": 168
      },
      "sustainability_rating": "high"
    }
  ]
}

Documentation Index

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

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

To use this API, you first need to create your own Dynamic Checkout configuration 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 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 endpoint, setting ship_with.type to "shipping_option_code" and ship_with.properties.shipping_option_code to the value of the checkout_identifier field.

Authorizations

​
Authorization
string
header
required

Basic Authentication using API key and secrets is currently the main authentication mechanism.

Body

application/json

Request body for searching delivery options based on cart or order details

​
total_weight
object
required

The total weight of the cart or order. Used to select the most suitable shipping option.

​
total_price
object
required

The total price of the cart or order, specified in the currency of the checkout configuration. Used to calculate the shipping rate and determine free shipping eligibility.

​
from_address
Address Object · object
required

The sender address for the shipment. You can either provide a sender_address_id to reference a pre-configured sender address, or provide address fields directly with at least country_code.

​
to_address
Address Object · object
required

The recipient's address. Must include at least country_code. Providing postal_code enables more precise delivery options via Checkout Rules.

​
parcel_dimensions
object

The dimensions of the parcel. All properties are optional. Can be used with Checkout Rules to control which delivery options are displayed during checkout.

​
metadata
object

A free-form object for passing key-value pairs related to the cart or order (maximum 5 keys, each value up to 128 characters). To use metadata with existing Checkout Rules, pass the value under the checkout_metadata key. This maps to the existing checkout_metadata rule condition. Support for arbitrary metadata keys in Checkout Rules will be added separately.

Example:
{ "checkout_metadata": "electronics" }

Response

Successful Response

Delivery options response

​
configuration_id
string<uuid>
required

The unique ID of the checkout configuration used to generate the delivery options in the response

Example:

"bae462c1-d659-48d0-aacd-fb7e3550de14"

​
delivery_options
Delivery Option Object · object[]
required

A list of delivery options available for the given cart or order details. Each delivery option corresponds to a configured delivery method and includes detailed information, such as shipping rates, delivery dates, and carrier information.

Example:
[
  {
    "id": "ec9ce3b9-7d3f-4298-bc1c-8f3aaa8d27e9",
    "title": "Same day delivery",
    "internal_title": "same_day_delivery_trunkrs",
    "description": "Order now and get your delivery today!",
    "delivery_method_type": "same_day_delivery",
    "cut_off_time": "2024-11-27T15:00:00+01:00",
    "checkout_identifier": {
      "type": "shipping_option_code",
      "value": "trunkrs:same_day"
    },
    "shipping_rate": { "value": "5.00", "currency": "EUR" },
    "carrier": {
      "code": "trunkrs",
      "name": "Trunkrs",
      "logo_url": "https://sendcloud-prod-scp-static-files.s3.amazonaws.com/trunkrs/img/logo.svg"
    },
    "delivery_dates": [
      {
        "delivery_date": "2024-11-27T15:00:00+01:00",
        "parcel_handover_date": "2024-11-27T15:00:00+01:00"
      }
    ],
    "lead_time_hours": {
      "p10": 0,
      "p20": 0,
      "p30": 0,
      "p40": 0,
      "p50": 0,
      "p60": 0,
      "p70": 0,
      "p80": 24,
      "p90": 24,
      "p95": 24
    },
    "sustainability_rating": "low"
  }
]