Create a shipment with service point delivery

This guide explains how to create a shipment with service point delivery: find a compatible shipping option for the selected service point, then create and announce the shipment.

Before you start

You need the Sendcloud id of the service point selected for the shipment. Some service points also require a post number. If you haven’t implemented service point selection yet, choose one of these approaches:

Find service points with the API

Use Service Points API v3 to find service points and integrate them into your own flow.

Integrate the hosted service point picker into your checkout

Add Sendcloud’s hosted picker and let customers choose a service point during checkout.

Find a shipping option

Use the Return a list of available shipping options endpoint to find shipping options that can deliver to the selected service point. Include the selected service point id as to_service_point.id, together with the shipment details that affect shipping option availability, such as the origin, destination, and parcel weight.

Example request method and URL

POST https://panel.sendcloud.sc/api/v3/shipping-options

Example request body

{
  "from_address": {
    "country_code": "NL",
    "postal_code": "1000AA",
    "city": "Amsterdam"
  },
  "to_address": {
    "country_code": "NL",
    "postal_code": "5611EM",
    "city": "Eindhoven"
  },
  "to_service_point": {
    "id": "1000001"
  },
  "parcels": [
    {
      "weight": {
        "value": "1.500",
        "unit": "kg"
      }
    }
  ]
}

The response contains the shipping options available for the shipment and selected service point:

Example response body

{
  "data": [
    {
      "code": "postnl:pakjegemak",
      "name": "PostNL service point",
      "carrier": {
        "code": "postnl",
        "name": "PostNL"
      },
      <...>
    }
  ]
}

Choose one of the returned shipping options and keep its code. We’ll use postnl:pakjegemak when creating the shipment in the next section. See Shipping options & quotes for more on filtering options, calculating quotes, and shipping functionalities.

Find shipping options before selecting a service point

Some flows retrieve available delivery options before a service point has been selected. In this case, omit to_service_point and filter shipping options using functionalities.last_mile instead. For example, to find shipping options that support service point delivery:

Example request body

{
  "from_address": {
    "country_code": "NL",
    "postal_code": "1000AA",
    "city": "Amsterdam"
  },
  "to_address": {
    "country_code": "NL",
    "postal_code": "5611EM",
    "city": "Eindhoven"
  },
  "functionalities": {
    "last_mile": "service_point"
  },
  "parcels": [
    {
      "weight": {
        "value": "1.500",
        "unit": "kg"
      }
    }
  ]
}

This returns shipping options that support service point delivery without restricting the request to a specific service point.

service_point is one of the supported last_mile values. Other values can be used for different delivery types, including locker delivery and options that support either lockers or service points. See the Shipping Options API reference for the available last_mile values.

Create and announce the shipment

Use the Create and announce a shipment synchronously endpoint to create and announce the shipment. Include the selected service point id in to_service_point.id and the shipping option code from Find a shipping option in ship_with.properties.shipping_option_code.

Example request method and URL

POST https://panel.sendcloud.sc/api/v3/shipments/announce

Example request body

{
  "to_address": {
    "name": "John Doe",
    "address_line_1": "Stadhuisplein",
    "house_number": "10",
    "postal_code": "5611EM",
    "city": "Eindhoven",
    "country_code": "NL",
    "email": "john.doe@example.com"
  },
  "from_address": {
    "sender_address_id": 42
  },
  "to_service_point": {
    "id": "1000001"
  },
  "ship_with": {
    "type": "shipping_option_code",
    "properties": {
      "shipping_option_code": "postnl:pakjegemak"
    }
  },
  "parcels": [
    {
      "weight": {
        "value": "1.500",
        "unit": "kg"
      }
    }
  ]
}

The response includes the created shipment, the service point it will be delivered to, and a link to the label:

Example response body

{
  "data": {
    "id": "facade00-0000-4000-a000-000000000000",
    "ship_with": {
      "type": "shipping_option_code",
      "properties": {
        "shipping_option_code": "postnl:pakjegemak",
        "contract_id": 101
      }
    },
    "to_service_point": {
      "id": "1000001",
      "carrier_service_point_id": "12345"
    },
    "carrier": {
      "code": "postnl",
      "name": "PostNL"
    },
    <...>
  }
}

See Create a shipment for the full request schema, error handling, and advanced options such as customs and insurance.

Include a post number

Some service points require the recipient’s post number in addition to the service point id. For example, DHL Packstations in Germany require the recipient’s Postnummer. When a post number is required or provided, include it in to_address.po_box:

Example request body

{
  "to_address": {
    <...>
    "po_box": "1234567890"
  },
  "to_service_point": {
    "id": "1000001"
  },
  <...>
}

The hosted service point picker handles post number collection when needed and returns it along with the selected service point. If you’re using your own selection flow, check the selected service point’s requirements.post_number to decide whether to ask the customer for a post number:

Value	What to do
`required`	Ask the customer for a post number and include it in `to_address.po_box`. The carrier needs it to identify the recipient and deliver the shipment.
`optional`	You can ask for a post number and include it if provided. It’s not needed for shipment creation or delivery, but may enable additional features for the recipient, such as tracking in the carrier’s app.
`not_applicable`	Don’t ask for a post number.

Omitting a required post number (to_address.po_box) causes the shipment creation request to fail with a validation error.

Getting started

Shipments

Addresses

Orders

Dynamic Checkout

Returns

Service points

Parcel tracking

Marketplaces

Archive

Before you start

Find service points with the API

Integrate the hosted service point picker into your checkout

Find a shipping option

Find shipping options before selecting a service point

Create and announce the shipment

Include a post number

​Before you start

Find service points with the API

Integrate the hosted service point picker into your checkout

​Find a shipping option

​Find shipping options before selecting a service point

​Create and announce the shipment

​Include a post number

Before you start

Find a shipping option

Find shipping options before selecting a service point

Create and announce the shipment

Include a post number