openapi: 3.1.0
info:
title: Shipments Address Service Points API
version: 3.0.0
description: The Shipments API allows you to create and announce, retrieve, and cancel outgoing shipments and their associated parcels within the Sendcloud platform.
contact:
name: Sendcloud API Support
email: contact@sendcloud.com
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
- url: https://panel.sendcloud.sc/api/v3
description: Sendcloud Production
tags:
- name: Service Points
description: Service Points API
paths:
/service-points:
get:
summary: Retrieve a list of service points
description: Find service points for selected carriers in a given area.
x-mint:
href: /api/v3/service-points/retrieve-a-list-of-service-points
metadata:
tag: Beta
content: "Returns service points in a given country for selected carriers.\n\nThis endpoint is designed for checkout and delivery flows where customers need to choose a pickup location.\nIt can be used to display service points on a map, show them as a list, or support automatic service point selection.\n\n## Carrier selection\n\nA carrier scope must always be provided.\n\nUse `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).\n \n<Note>\n `carrier_code` and `use_integration_carriers` are mutually exclusive. Exactly one of them must be provided.\n</Note>\n\nIn some cases, returned service points may belong to a different carrier than the one that was requested.\nThis 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.\nAs a result, `carrier.code` in the response may differ from the requested `carrier_code`. This is expected behavior.\n\n<Note>\n 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.\n</Note>\n\n## Reference point and geocoding\n\nA 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.\n\nFree-text address input is usually the best fit when the address comes directly from a checkout form as a single string.\n\nStructured 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.\n\n<Note>\n `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.\n\n 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.\n</Note>\n\nThe geocoding result can be used to understand whether the address was resolved successfully and, if so, how precise the match is.\n\nWhen `data.geocoding.status` is `not_found`, the address could not be resolved and no service points are returned.\n\nWhen `data.geocoding.status` is partially_matched, the address was matched, but not all parts of the input could be used.\nFor example, a full address may be provided, but only the postal code could be matched.\nThe search still runs based on the matched parts, and `data.geocoding.precision` reflects the resulting match level.\n\nWhen the address is resolved, `data.geocoding.precision` can be used to understand how specific the match is.\nThis can help decide whether the result is precise enough for the current flow.\nFor 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.\n\n<Note>\n 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.\n We do our best to keep this reliable, but if it happens, retrying after a short delay usually resolves it.\n</Note>\n\n## Search area\n\nWhen a reference point is available, the API returns the closest matching service points around that location. By default, the closest `limit` results are returned.\n\nThe search area can be narrowed in two ways:\n- use `radius` to return only service points within a given distance from the reference point\n- use `ne_latitude`, `ne_longitude`, `sw_latitude`, and `sw_longitude` to search within a bounding box\n\nBounding boxes are especially useful for map-based interfaces where results should match the area currently visible on the map.\n\n<Note>\n `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.\n</Note>\n\n## Data freshness\nService 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.\n\nIn 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.\n\n## Results\nRequests 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.\n\nThis endpoint is designed for service point discovery in checkout and map-based flows, so results are not paginated by design.\nUse `limit` to control the maximum number of service points returned for the use case.\n\nFor example, if only the 5 closest service points need to be shown, a lower limit can reduce response size and avoid returning unnecessary results."
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
operationId: sc-public-v3-servicepoints-get-list_service_points
tags:
- Service Points
parameters:
- name: country_code
in: query
required: true
schema:
type: string
maxLength: 2
example: NL
description: Country to retrieve service points for, as an ISO 3166-1 alpha-2 code.
- name: carrier_code
in: query
required: false
schema:
type: array
items:
type: string
example: postnl
example:
- dhl
- postnl
style: form
explode: true
description: Carrier codes to filter results by.
- name: use_integration_carriers
in: query
required: false
schema:
type: boolean
description: Filters service points to carriers enabled in the authenticated integration's settings.
- name: address
in: query
required: false
schema:
type: string
example: Stadhuisplein 10, Eindhoven
description: Free-text address used as the reference point for the search.
- name: address_street
in: query
required: false
schema:
type: string
example: Stadhuisplein
description: Street of the reference address.
- name: address_house_number
in: query
required: false
schema:
type: string
example: '10'
description: House number of the reference address.
- name: address_postal_code
in: query
required: false
schema:
type: string
example: 5611 EM
description: Postal code of the reference address.
- name: address_city
in: query
required: false
schema:
type: string
example: Eindhoven
description: City of the reference address.
- name: latitude
in: query
required: false
schema:
type: number
format: double
example: 51.435046
description: Latitude of the reference point.
- name: longitude
in: query
required: false
schema:
type: number
format: double
example: 5.479507
description: Longitude of the reference point.
- name: ne_latitude
in: query
required: false
schema:
type: number
format: double
example: 51.49
description: Latitude of the north-east corner of the bounding box.
- name: ne_longitude
in: query
required: false
schema:
type: number
format: double
example: 5.57
description: Longitude of the north-east corner of the bounding box.
- name: sw_latitude
in: query
required: false
schema:
type: number
format: double
example: 51.38
description: Latitude of the south-west corner of the bounding box.
- name: sw_longitude
in: query
required: false
schema:
type: number
format: double
example: 5.36
description: Longitude of the south-west corner of the bounding box.
- name: radius
in: query
required: false
schema:
type: integer
minimum: 100
maximum: 50000
example: 5000
description: Search radius in meters from the reference point.
- name: carrier_service_point_id
in: query
required: false
schema:
type: array
items:
type: string
example: NL98765
example:
- '12345'
- NL98765
style: form
explode: true
description: Carrier-specific identifiers of the service points to return.
- name: carrier_shop_type
in: query
required: false
schema:
type: string
example: packStation
description: Filters results by carrier-specific shop type.
- name: general_shop_type
in: query
required: false
schema:
type: array
items:
type: string
enum:
- servicepoint
- locker
- post_office
- carrier_depot
example:
- servicepoint
- locker
style: form
explode: true
description: Filters results by general shop type. Use this to narrow results without having to handle each carrier's specific shop types separately.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 200
default: 100
example: 100
description: Maximum number of service points to return.
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/ServicePoint'
geocoding:
anyOf:
- $ref: '#/components/schemas/GeocodingResult'
- type: 'null'
required:
- results
- geocoding
required:
- data
examples:
ServicePointList:
summary: A list of service points near a reference location
value:
data:
results:
- id: 1000001
name: Stadhuisplein Parcel Shop
carrier:
code: dhl
name: DHL
logo_url: https://cdn.sendcloud.com/global-media/dhl/img/logo.svg
icon_url: https://cdn.sendcloud.com/global-media/dhl/img/icon.svg
carrier_service_point_id: NL-00001
carrier_shop_type: paketshop
general_shop_type: servicepoint
address:
street: Stadhuisplein
house_number: '1'
postal_code: 5611 EM
city: Eindhoven
country_code: NL
position:
latitude: 51.438022
longitude: 5.478543
contact:
email: ''
phone: ''
opening_times:
monday:
- start_time: 09:00
end_time: '17:00'
tuesday:
- start_time: 09:00
end_time: '17:00'
wednesday:
- start_time: 09:00
end_time: '17:00'
thursday:
- start_time: 09:00
end_time: '17:00'
friday:
- start_time: 09:00
end_time: '17:00'
saturday: null
sunday: null
is_open_tomorrow: true
next_open_at: '2026-03-11T09:00:00+01:00'
is_expired: false
distance: 85
- id: 1000002
name: Stationsplein Parcel Locker
carrier:
code: postnl
name: PostNL
logo_url: https://cdn.sendcloud.com/global-media/postnl/img/logo.svg
icon_url: https://cdn.sendcloud.com/global-media/postnl/img/icon.svg
carrier_service_point_id: NL-00002
carrier_shop_type: pakketautomaat
general_shop_type: locker
address:
street: Stationsplein
house_number: '1'
postal_code: 5611 AC
city: Eindhoven
country_code: NL
position:
latitude: 51.443218
longitude: 5.4816
contact:
email: ''
phone: ''
opening_times:
monday:
- start_time: '10:00'
end_time: '21:00'
tuesday:
- start_time: '10:00'
end_time: '21:00'
wednesday:
- start_time: '10:00'
end_time: '21:00'
thursday: null
friday:
- start_time: '10:00'
end_time: '21:00'
saturday:
- start_time: '10:00'
end_time: '21:00'
sunday: null
is_open_tomorrow: false
next_open_at: '2026-03-13T10:00:00+01:00'
is_expired: false
distance: 919
geocoding:
status: matched
precision: street
formatted_address: Stadhuisplein 10, 5611 EM Eindhoven, Nederland
NoServicePointsNearby:
summary: No service points nearby
value:
data:
results: []
geocoding:
status: matched
precision: house_number
formatted_address: Stadhuisplein 10, 5611 EM Eindhoven, Nederland
PartiallyMatchedAddress:
summary: Address matched only partially
value:
data:
results:
- id: 1000001
name: Stadhuisplein Parcel Shop
carrier:
code: dhl
name: DHL
logo_url: https://cdn.sendcloud.com/global-media/dhl/img/logo.svg
icon_url: https://cdn.sendcloud.com/global-media/dhl/img/icon.svg
carrier_service_point_id: NL-00001
carrier_shop_type: paketshop
general_shop_type: servicepoint
address:
street: Stadhuisplein
house_number: '1'
postal_code: 5611 EM
city: Eindhoven
country_code: NL
position:
latitude: 51.438022
longitude: 5.478543
contact:
email: ''
phone: ''
opening_times:
monday:
- start_time: 09:00
end_time: '17:00'
tuesday:
- start_time: 09:00
end_time: '17:00'
wednesday:
- start_time: 09:00
end_time: '17:00'
thursday:
- start_time: 09:00
end_time: '17:00'
friday:
- start_time: 09:00
end_time: '17:00'
saturday: null
sunday: null
is_open_tomorrow: true
next_open_at: '2026-03-11T09:00:00+01:00'
is_expired: false
distance: 412
geocoding:
status: partially_matched
precision: postal_code
formatted_address: 5611, Eindhoven, Noord-Brabant, Nederland
AddressNotFound:
summary: Address could not be geocoded
value:
data:
results: []
geocoding:
status: not_found
precision: null
formatted_address: null
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
RequiredParameterMissing:
summary: Required parameter missing
value:
errors:
- status: '400'
code: required
detail: Field required
source:
parameter: country_code
InvalidCountryCode:
summary: Invalid country code
value:
errors:
- status: '400'
code: invalid_choice
detail: '"XX" is not a valid country code'
source:
parameter: country_code
InvalidParameterType:
summary: Invalid parameter type
value:
errors:
- status: '400'
code: invalid
detail: Input should be a valid number, unable to parse string as a number
source:
parameter: latitude
InvalidEnumChoice:
summary: Invalid parameter value
value:
errors:
- status: '400'
code: invalid_choice
detail: Input should be 'servicepoint', 'locker', 'post_office' or 'carrier_depot'
source:
parameter: general_shop_type
MutuallyExclusiveParams:
summary: Mutually exclusive parameters used together
value:
errors:
- status: '400'
code: validation_error
detail: carrier_code and use_integration_carriers are mutually exclusive
source:
parameter: carrier_code
MutuallyInclusiveParams:
summary: Incomplete parameter group
value:
errors:
- status: '400'
code: validation_error
detail: ne_latitude, ne_longitude, sw_latitude, and sw_longitude must all be provided together
source:
parameter: ne_latitude
ServicePointsDisabledForIntegration:
summary: Service points not enabled
value:
errors:
- status: '400'
code: validation_error
detail: Service points are not enabled for the authenticated integration.
CarrierNotSupported:
summary: Carrier not supported
value:
errors:
- status: '400'
code: validation_error
detail: 'Service points are not supported for the requested carriers: acme.'
'503':
description: Service Unavailable
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
AddressLookupFailed:
summary: Address could not be resolved
value:
errors:
- status: '503'
code: null
detail: The address could not be resolved at this time. Try again later.
/service-points/{service_point_id}:
parameters:
- name: service_point_id
in: path
required: true
schema:
type: integer
format: int64
minimum: 1
example: 1000001
description: Unique Sendcloud identifier of the service point.
get:
summary: Retrieve a service point
description: Retrieve a single service point.
x-mint:
href: /api/v3/service-points/retrieve-a-service-point
metadata:
tag: Beta
content: '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.'
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
operationId: sc-public-v3-servicepoints-get-service_point
tags:
- Service Points
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/ServicePointDetail'
required:
- data
examples:
ServicePointDetail:
summary: A single service point
value:
data:
id: 1000002
name: Stationsplein Parcel Locker
carrier:
code: postnl
name: PostNL
logo_url: https://cdn.sendcloud.com/global-media/postnl/img/logo.svg
icon_url: https://cdn.sendcloud.com/global-media/postnl/img/icon.svg
carrier_service_point_id: NL-00002
carrier_shop_type: pakketautomaat
general_shop_type: locker
address:
street: Stationsplein
house_number: '1'
postal_code: 5611 AC
city: Eindhoven
country_code: NL
position:
latitude: 51.443218
longitude: 5.4816
contact:
email: ''
phone: ''
opening_times:
monday:
- start_time: '10:00'
end_time: '21:00'
tuesday:
- start_time: '10:00'
end_time: '21:00'
wednesday:
- start_time: '10:00'
end_time: '21:00'
thursday: null
friday:
- start_time: '10:00'
end_time: '21:00'
saturday:
- start_time: '10:00'
end_time: '21:00'
sunday: null
is_open_tomorrow: false
next_open_at: '2026-03-13T10:00:00+01:00'
is_expired: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ServicePointNotFound:
summary: Service point not found
value:
errors:
- status: '404'
code: not_found
detail: The service point could not be found
/service-points/{service_point_id}/check-availability:
parameters:
- name: service_point_id
in: path
required: true
schema:
type: integer
format: int64
minimum: 1
example: 1000001
description: Unique Sendcloud identifier of the service point.
post:
summary: Check availability of a service point
description: Check whether a service point is currently available.
x-mint:
href: /api/v3/service-points/check-availability-of-a-service-point
metadata:
tag: Beta
content: '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.'
operationId: sc-public-v3-servicepoints-post-check_availability
security:
- HTTPBasicAuth: []
- OAuth2ClientCreds: []
tags:
- Service Points
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
is_available:
type: boolean
description: Indicates whether the service point is currently available.
example: true
required:
- is_available
required:
- data
examples:
Available:
summary: Service point is available
value:
data:
is_available: true
NotAvailable:
summary: Service point is not available
value:
data:
is_available: false
'404':
description: Not Found
content:
application/json:
schema:
$ref: '#/components/schemas/errors'
examples:
ServicePointNotFound:
summary: Service point not found
value:
errors:
- status: '404'
code: not_found
detail: The service point could not be found
components:
schemas:
OpeningTime:
title: Opening Time
type: object
description: Opening hours for a specific time range.
properties:
start_time:
type: string
description: Start of the opening time range in 24-hour format (`HH:mm`).
example: 09:00
end_time:
type: string
description: End of the opening time range in 24-hour format (`HH:mm`).
example: '18:00'
required:
- start_time
- end_time
errors:
title: Errors
type: object
description: A standardized format for errors in JSON:API responses.
properties:
errors:
type:
- array
- object
items:
type: object
allOf:
- $ref: '#/components/schemas/ErrorObject'
required:
- status
- code
- detail
OpeningTimes:
title: Opening Times
type: object
description: 'Opening hours of the service point for the current week.
These hours reflect the service point''s actual availability this week and may differ from a typical week due to public holidays or other temporary schedule changes.'
properties:
monday:
anyOf:
- type: array
items:
$ref: '#/components/schemas/OpeningTime'
minItems: 1
- type: 'null'
description: Opening hours for Monday. `null` if the service point is closed that day.
tuesday:
anyOf:
- type: array
items:
$ref: '#/components/schemas/OpeningTime'
minItems: 1
- type: 'null'
description: Opening hours for Tuesday. `null` if the service point is closed that day.
wednesday:
anyOf:
- type: array
items:
$ref: '#/components/schemas/OpeningTime'
minItems: 1
- type: 'null'
description: Opening hours for Wednesday. `null` if the service point is closed that day.
thursday:
anyOf:
- type: array
items:
$ref: '#/components/schemas/OpeningTime'
minItems: 1
- type: 'null'
description: Opening hours for Thursday. `null` if the service point is closed that day.
friday:
anyOf:
- type: array
items:
$ref: '#/components/schemas/OpeningTime'
minItems: 1
- type: 'null'
description: Opening hours for Friday. `null` if the service point is closed that day.
saturday:
anyOf:
- type: array
items:
$ref: '#/com
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sendcloud/refs/heads/main/openapi/sendcloud-service-points-api-openapi.yml