Integrate the hosted service point picker into your checkout

The service point picker is a Sendcloud-hosted interface that lets customers choose a service point during checkout. You add it to your checkout page with a small JavaScript snippet, and it opens as an overlay showing nearby service points on a map and in a list. The picker handles the service point search and selection interface for you. It finds and displays available service points, then returns the customer’s selection to your checkout through a JavaScript callback. This guide is for custom-built checkouts that integrate directly with Sendcloud. If you use one of our plug-and-play integrations, service point selection is already part of the integration.

You can try the picker and its configuration options in our interactive example. The example is a single HTML page, so you can view its source and use it as a starting point.

If you need more control over your service point integration, build it around Service Points API v3 instead.

Before you start

The picker uses the carriers enabled for service point delivery in your integration settings. Enable service point delivery and the carriers you want to offer before you start:

In the Sendcloud platform, go to your integration settings
Find your API integration and click Configure
Enable service point delivery
Enable the carriers you want to use for service point delivery and save your changes

You also need the public key of the same integration. You can find it on the integration settings page. See How to create your API keys.

The picker authenticates with the integration public key, which is safe to expose in client-side code. Keep the integration secret key private.

Add the picker script

Add the picker script to your checkout page:

Example: loading the picker script

<script src="https://embed.sendcloud.sc/spp/1.0.0/api.min.js"></script>

Once loaded, the script makes sendcloud.servicePoints available to your page. The next section explains how to use this object to display the picker and control its behavior.

If your checkout enforces a Content Security Policy, allow https://embed.sendcloud.sc in both script-src, for the picker script, and frame-src, for the picker overlay itself, which is an iframe served from that origin.

Display the picker

Use sendcloud.servicePoints.open() to display the picker. It takes three arguments:

open() method signature

sendcloud.servicePoints.open(config, onSuccess, onFailure)

Argument	Type	Description
`config`	`object`	Controls which service points are shown and where the picker initially searches. See Configuration options
`onSuccess`	`function`	Called with the customer’s selection when they choose a service point. See Handle the selection
`onFailure`	`function`	Called with an array of messages when opening fails or the customer closes the picker. See Handle failures

Configuration options

Option	Type	Required	Description
`apiKey`	`string`	Yes	Public key of your API integration
`country`	`string`	Yes	Country to show service points for, as an ISO 3166-1 alpha-2 code such as `NL` or `FR`
`language`	`string`	No	Language of the picker interface. One of `de-de`, `en-gb`, `en-us`, `es-es`, `fr-fr`, `it-it`, or `nl-nl`. Defaults to `en-us`
`postalCode`	`string`	No	Postal code to center the initial search on
`city`	`string`	No	City to center the initial search on
`address1`	`string`	No	Street, optionally with a house number, to center the initial search on
`carriers`	`string`	No	Comma-separated carrier codes to show service points for, such as `postnl,dhl`. If omitted, all carriers enabled for service point delivery in your integration settings are shown
`shopType`	`string`	No	Carrier-specific shop type to filter on, such as `parcelShop`, `packStation`, or `punto_poste`. The supported values depend on the carrier
`servicePointId`	`number`	No	Sendcloud `id` of a service point to center the picker on. The picker opens centered on that service point

The carriers option only filters the carriers enabled for service point delivery in your integration settings.

If you already have an address to center the initial search on, pass it using postalCode, city, and address1. The picker then opens near that address instead of requiring the customer to search for it again.

Handle the selection

When the customer selects a service point, the picker checks that it is still available before completing the selection. If the service point is available, the picker closes and calls your success callback with two arguments:

Argument	Type	Description
`servicePoint`	`object`	The selected service point. See Service point fields
`postNumber`	`string`	Post number entered by the customer when the selected location requires one, such as a DHL PackStation. Otherwise, an empty string

Service point fields

The servicePoint argument contains the selected service point details:

Example: selected service point

{
  "id": 1000001,
  "code": "NL-00001",
  "name": "Stadhuisplein Parcel Shop",
  "carrier": "postnl",
  "street": "Stadhuisplein",
  "house_number": "1",
  "postal_code": "5611EM",
  "city": "Eindhoven",
  "country": "NL",
  "latitude": "51.438022",
  "longitude": "5.478543",
  "shop_type": "parcelShop",
  "general_shop_type": "servicepoint",
  "formatted_opening_times": {
    "0": ["10:00 - 20:00"],
    <...>
    "6": []
  },
  "open_tomorrow": true,
  "open_upcoming_week": true,
  "distance": 85
}

Field	Type	Description
`id`	`number`	The Sendcloud `id` of the service point. You need it to create the shipment
`code`	`string`	The carrier’s own identifier for the service point
`name`	`string`	The name of the location, suitable for showing back to the customer
`carrier`	`string`	The code of the carrier operating the service point, such as `postnl`
`street`	`string`	The street name of the service point address
`house_number`	`string`	The house number of the service point address
`postal_code`	`string`	The postal code of the service point address
`city`	`string`	The city the service point is located in
`country`	`string`	The country the service point is located in, as an ISO 3166-1 alpha-2 code
`latitude`	`string`	The geographic latitude of the service point, returned as a string
`longitude`	`string`	The geographic longitude of the service point, returned as a string
`shop_type`	`string` or `null`	The carrier-specific classification of the location, such as `packStation`. `null` if the carrier does not provide one
`general_shop_type`	`string` or `null`	The normalized classification of the location. Carrier-specific shop types are mapped onto a fixed set of values: `servicepoint`, `locker`, `post_office`, or `carrier_depot`
`formatted_opening_times`	`object` of `string` arrays, keyed `"0"` through `"6"`	The opening hours for the current week, keyed by day number where `0` is Monday and `6` is Sunday. Each day holds an array of time range strings, and an empty array means the location is closed on that day
`open_tomorrow`	`boolean`	Whether the location is open tomorrow
`open_upcoming_week`	`boolean`	Whether the location is open at least once in the next seven days
`distance`	`number`	Distance in meters between the location and the point the picker searched around

The service point object returned in the callback uses a different structure than Service Points API v3 response.

Store the selected service point’s Sendcloud id with the order. If the picker returns a post number, store that as well. You’ll need these values when you create the shipment.

Handle failures

The failure callback receives a single argument, errors, which is an array of strings. Configuration problems can be reported together, so the array may contain more than one value. The failure callback can return values such as:

Value	When the picker returns it
`Closed`	The customer closed the picker without selecting a service point. See Close the picker
`Missing API key.`	`apiKey` was an empty string. The picker doesn’t open
`No country set.`	`country` was an empty string. The picker doesn’t open

Closed is the only value you should handle as a separate case. It represents normal customer behavior rather than an error. Treat other values as errors to log or report without assuming the list above is exhaustive. Errors handled inside the picker are not passed to your failure callback. For example, if the selected service point is no longer available, a search fails, or a required post number is missing, the picker handles the problem in its own interface and remains open.

Close the picker

The customer can close the picker with its close button or by pressing Esc. Both call your failure callback with ['Closed']. See Handle failures for how to handle this case. You can also close the picker from your code, for example when the customer returns to an earlier checkout step:

Example: closing the picker from your code

sendcloud.servicePoints.close()

Calling close() from your code does not trigger the success or failure callback.

Example integration

The following example puts the pieces together. Replace the public key with the one from your integration settings.

Example: minimal service point picker integration

<script src="https://embed.sendcloud.sc/spp/1.0.0/api.min.js"></script>

<button
  type="button"
  id="chooseServicePoint"
>
  Choose a service point
</button>

<input
  type="hidden"
  id="servicePointId"
  name="servicePointId"
/>
<input
  type="hidden"
  id="servicePointPostNumber"
  name="servicePointPostNumber"
/>

<p id="servicePointSummary"></p>

<script>
  function onServicePointSelected(servicePoint, postNumber) {
    const { id, name, street, house_number, city } = servicePoint
    const summary = `${name}, ${street} ${house_number}, ${city}`

    document.getElementById('servicePointId').value = id
    document.getElementById('servicePointPostNumber').value = postNumber
    document.getElementById('servicePointSummary').textContent = `Selected service point: ${id}: ${summary}`
  }

  function onServicePointPickerFailure(errors) {
    if (errors.includes('Closed')) {
      return
    }
    console.error('Service point picker error:', errors.join(', '))
  }

  document.getElementById('chooseServicePoint').addEventListener('click', () => {
    sendcloud.servicePoints.open(
      {
        apiKey: 'your-integration-public-key',
        country: 'NL',
        language: 'en-gb',
        postalCode: '5611 EM',
        city: 'Eindhoven',
      },
      onServicePointSelected,
      onServicePointPickerFailure,
    )
  })
</script>

Next step

Once you have stored the selected service point id and any post number returned by the picker, continue with creating the shipment.

Create a shipment with service point delivery

Use the selected service point to find a compatible shipping option, then create and announce the shipment.

Getting started

Shipments

Addresses

Orders

Dynamic Checkout

Returns

Service points

Parcel tracking

Marketplaces

Archive

Integrate the hosted service point picker into your checkout

Before you start

Add the picker script

Display the picker

Configuration options

Handle the selection

Service point fields

Handle failures

Close the picker

Example integration

Next step

Create a shipment with service point delivery

​Before you start

​Add the picker script

​Display the picker

​Configuration options

​Handle the selection

​Service point fields

​Handle failures

​Close the picker

​Example integration

​Next step

Create a shipment with service point delivery

Before you start

Add the picker script

Display the picker

Configuration options

Handle the selection

Service point fields

Handle failures

Close the picker

Example integration

Next step