docs

Shipping Options (hidden)

Introduction

This section explains how to set a shipping options in the SCAYLE Headless Checkout.

Carrier and Shipping options configuration must be done before implementing Shipping Options at checkout

SCAYLE checkout offers two main flows for shipping options:

  • Home delivery
  • Collection Point delivery

To streamline the process, the best-fitting shipping option will be preselected automatically. This is determined by:

  • The shipping option used in the customer’s most recent order, if it’s compatible with the current basket
  • Fallback to default selection based on business rules

Showing Shipping Options

Available shipping options and the selected shipping option are included in the state response.

In order to display shipping options for the customers, it should be aligned with a Carrier & Shipping configuration

Each shipping option contains multiple important keys:

KeyDescription
carrierGroupKeyGeneral name of the carrier, e.g "hermes" or "dhl"
carrierKeySpecific carrier key, e.g "dhl_de", "dhl_at"
deliveryOptionKeyWhether it is "home_delivery" or "collection_point_delivery"
shippingOptionKeyUsed to distinguish betweem different shipping types like "standard_delivery" or "express_delivery"

Display Home Delivery options

Location in State

  • Available under orderOptions.shipping.homeDelivery

When showing shipping options to the customer, it is recommended to group them by carrierGroupKey and list all available shippingOptionsKeys.

Display Collection Point Delivery options

Location in State

  • Available under orderOptions.shipping.collectionPointDelivery

To display available collection points, you will need to check for available carriers first and afterwards use the Search Collection Points endpoint.

Display selected Shipping Option

Location in State

  • Available under orderState.selected.shipping

Depending on the selected shipping option deliveryOptionKey you can either show the selected home delivery option or collection point delivery option.

Setting Home Delivery

Home Delivery is the default and most common shipping method.

  • If the current selected delivery option is Collection Point delivery, the collection point shipping address is automatically removed and a new home delivery address must be set.

Setting a home delivery shipping option is straight forward by providing the required keys, e.g:

{
    "data": {
        "carrierKey": "DHL_STD_NATIONAL",
        "carrierGroupKey": "dhl",
        "shippingOptionKey": "standard_delivery",
        "deliveryOptionKey": "home_delivery"
    }
}

Setting Collection Point Delivery

Endpoint: PUT /api/co/v3/state/order/delivery/option

For customers who prefer to pick up their order at a designated location.

  • A valid billing address MUST be set before or after choosing a collection point as the shipping option.

Setting a collection point shipping option works similarly to setting a home delivery option, with a few additional requirements. A collectionPointId, which can be retrieved via the Search Collection Points endpoint and the customers first and last name, need to be provided.

{
    "data": {
        "carrierKey": "HERMES_KLV",
        "carrierGroupKey": "hermes",
        "shippingOptionKey": "standard_delivery",
        "collectionPointType": "hermes_parcelshop",
        "deliveryOptionKey": "collection_points"
    },
    "specification": {
        "collectionPointId": "680962",
        "customer": {
            "firstName": "Max",
            "lastName": "Mustermann"
        }
    }
}

Search Collection Points

Endpoint: GET /api/co/v3/collection-points

To enable customers to find available collection points:

  • Use the Search Collection Points endpoint.
  • Typically filtered by ZIP code, city, or coordinates.
  • Returns a list of eligible pickup locations for the selected carrier and shipping country.
Map viewList view