Collection Points

General

Checkout allows users to select Home Delivery or Collection Point for shipping. Collection points can be added in the SCAYLE Panel through API endpoints that retrieve available collection points based on carrier and location.

Prerequisites

In order to configure collection points you will first need to ensure:

At least one Shipping Option has been configured in Shops > Storefront > Checkout Settings > Shipping Options
At least one Collection Point Type has been created in Settings > General > Configuration > Collection Point Types (see Configurations)

Add Collection Point in the SCAYLE Panel

Collection Points are configured under Shops > Shop > Storefront > Checkout Settings > Collection Points.

To add a new collection point, click + Collection Point and complete the following:

Delivery Option: Collection Point or Click & Collect
- Note: Collection Points are staffed locations whereas Click & Collect are self service stations where an id card is needed for customers to pick up their package.
Collection Point Type (dropdown): Select from list of types (types are added in Configurations).
Delegation Name (string): Key used for order delegation request. Some suggestions will be provided.
Cloud Type (string): Type key for webhooks or Admin API responses, usually same as Collection Point Type but it can be customized if needed.
Merchants (multiple selection): Allows you to whitelist merchants or keep it null (in the null case, all merchants will be allowed).
Carrier Groups (multiple selection): Allows you to whitelist carriers or keep it null (in the null case, all carriers will be allowed).
Visibility (switch): If Inactive the configured collection points will not display in the front end.
API Search Type (string): Value used to generate a list from the provided API. See the extensionAPI docs.
- Preferred Carrier Key (string): Used to generate list from the provided API. See the extensionAPI docs.
Customer Name (selection): Mandatory/Enabled
Customer Number (selection): Mandatory/Enabled
API Config: Option to enable search via an external API. If enabled, enter the following fields:
- Host
- Username
- Password
- Endpoint get Collection Point by ID
- Endpoint get Collection Point List

Implementation a custom service

Implement a custom service for Collection Points

Checkout empowers you to integrate your own collection points seamlessly. This guide will walk you through creating an API that Checkout can utilize to both list and retrieve available collection points.

To achieve this, you'll need to implement a service that offers two distinct endpoints for interaction with Checkout:

findNearby - This endpoint will list nearby locations based on the provided address.
findById - This endpoint will return information about a single location based on its unique identifier

Make sure to align the endpoints (host, path, credentials etc.) with the configuration.

findNearby endpoint

Request

Headers

Parameter	Details
X-Carrier-Key	String Carrier code

Parameter

Details

X-Carrier-Key

String

Carrier code

Query parameters

Your endpoint will be called with the following query parameters:

Parameter	Details
latitude	Float latitude (-90 to 90)
longitude	Float longitude (-180 to 180)
streetHouseNumber	String maximum: 60 characters minimum: 1 character
zipCode	String maximum: 7 characters minimum: 4 characters
city	String maximum: 40 characters minimum: 1 character
maximumDistance	Integer default: 10000 in meters
maximumResults	Integer default: 10
type	Integer default: all (parcel_shop, post_office, packstation) multiple selections will be joined by comma, eg `type=parcel_shop,post_office

Example Request

GET /api/carriers/collection-points?streetHouseNumber=An+der+Zehnt+1&city=Dermbach&zipCode=36466&maximumDistance=5000&maximumResults=10&latitude=50.7147482&longitude=10.1240258&type=servicepoint%2Clocker%2Cparcel_shop%2Cpostoffice

Response

Your service needs to follow this specification when handling the checkout request.

Body

Response example

[
    {
        "id": "626092",
        "address": {
            "city": "Berlin",
            "streetHouseNumber": "Reuterstr. 35",
            "zipCode": "12047"
        },
        "businessHours": [
            {
                "openingHours": [
                    {
                        "from": "07:00",
                        "until": "12:00"
                    },
                    {
                        "from": "14:00",

Response schema

items:

id string (minimum length: )
address object
- city string (minimum length: ) (maximum length: 40)
- streetHouseNumber string (^(.+) (.+?)$) (minimum length: ) (maximum length: 60)
- zipCode string (^[0-9]{5}$|^[0-9]{4}$|^[0-9]{4}\s?[A-Za-z]{2}$|^([0-9]{3} [0-9]{2})$|^([0-9]{2}-[0-9]{3})$|^[0-9a-zA-Z\s-]{4,10}$) (minimum length: ) (maximum length: 10)
businessHours array (optional)
- openingHours array
  - from string ([0-9]{1,2}:[0-9]{2}) (minimum length: )
  - until string ([0-9]{1,2}:[0-9]{2}) (minimum length: )
- weekDay enum (sunday monday tuesday wednesday thursday friday saturday)
- coordinates object
  - latitude number
  - longitude number
- delegationId string (optional) (minimum length: )
- description string (optional)
- distanceToSearchAddress integer (optional)
- owner string (optional)
- phone string,null (^[0-9()+-/ ]*$) (optional) (minimum length: ) (maximum length: 40)
- type string

Status Codes:

Code	Description	Response Body
`200`	lists collection points	see schema
`401`	authentication failed	empty
`404`	no results	see schema

findById endpoint

For this endpoint the id is appended to the configured path. If the configured path looks like /api/carriers/collection-points, checkout will call /api/carriers/collection-points/{id}.