Service Costs

General

Implement a custom fee service

The service costs feature enables you to implement complex variations for determining shipping fees. Basic service costs for shipping are already configurable via the SCAYLE Panel. Using this checkout extension allows you to use your very own logic to determine service costs and build a highly customized user experience around it.

Once you have configured the API Credentials for this service, checkout will execute calls to the given endpoint. The results of your calculation will be used and stored with the order.

How to implement

You need to provide a http service that can handle the usual load of your shop and which accepts requests from the SCAYLE networks.

If you want to limit incoming traffic by IP address, your SCAYLE Account Manager can provide more information about our networks.

This service needs to implement a POST endpoint according to the following schema:

Request

Your endpoint needs to be able to serve the following request.

Authentication

Basic auth according to SCAYLE Panel configuration.

Headers

Parameter	Details
X-Shop-Id	Integer The current shop-country id

Parameter

Details

X-Shop-Id

Integer

The current shop-country id

Body

Request example

{
    "id": 123,
    "address": {
        "billing": {
            "id": 998,
            "additional": "c/o AboutYou",
            "city": "Hamburg",
            "countryCode": "DEU",
            "houseNumber": "12",
            "isDefault": {
                "billing": false,
                "shipping": false
            },
            "recipient": {
                "firstName": "Anna",
                "gender": "m",
                "lastName": "Doe"
            },
            "referenceKey": "address-1324",
            "street": "Domstraße 10",
            "zipCode": "20095"
        },
        "shipping": {
            "id": 998,
            "city": "Hamburg",
            "collectionPoint": {
                "customerKey": "bced-234-234",
                "description": "Pedro's Kiosk",
                "key": "12345-a",
                "type": "hermes_parcelshop"
            },
            "countryCode": "DEU",
            "houseNumber": "10",
            "isDefault": {
                "billing": false,
                "shipping": false
            },
            "recipient": {
                "firstName": "Anna",
                "gender": "m",
                "lastName": "Doe"
            },
            "referenceKey": "address-1324",
            "street": "Domstraße 10",
            "zipCode": "20095"
        }
    },
    "cost": {
        "appliedReductions": [
            {
                "amount": {
                    "absoluteWithTax": 399,
                    "relative": 0.1
                },
                "category": "voucher",
                "code": "buxtehude",
                "type": "absolute"
            }
        ],
        "withoutTax": 12521,
        "withTax": 14900
    },
    "customData": {
        "key": "value"
    },
    "customer": {
        "id": 9876,
        "customData": {
            "isVip": true
        },
        "firstName": "Anna",
        "gender": "m",
        "lastName": "Doe",
        "referenceKey": "customer-1234"
    },
    "ipAddress": "",
    "items": [
        {
            "id": 1000000,
            "availableQuantity": 20,
            "currency": "EUR",
            "customData": {
                "pricePromotionKey": "010"
            },
            "deliveryForecast": {
                "deliverable": {
                    "key": "directShipping",
                    "quantity": 18
                },
                "subsequentDelivery": {
                    "key": "christmas",
                    "quantity": 2
                }
            },
            "key": "ac834d23e689u678",
            "merchant": {
                "id": 130
            },
            "price": {
                "appliedReductions": [
                    {
                        "amount": {
                            "absoluteWithTax": 399,
                            "relative": 0.1
                        },
                        "category": "campaign",
                        "type": "relative"
                    },
                    {
                        "amount": {
                            "absoluteWithTax": 399,
                            "relative": 0.1
                        },
                        "category": "sale",
                        "type": "relative"
                    },
                    {
                        "amount": {
                            "absoluteWithTax": 399,
                            "relative": 0.1
                        },
                        "category": "voucher",
                        "code": "buxtehude",
                        "type": "relative"
                    }
                ],
                "tax": {
                    "vat": {
                        "amount": 2379,
                        "rate": 0.19
                    }
                },
                "withoutTax": 12521,
                "withTax": 14900
            },
            "product": {
                "id": 234556,
                "attributes": {
                    "bulkyItem": {
                        "key": "bulkyitem",
                        "label": "Bulky Item",
                        "multiSelect": false,
                        "type": "",
                        "values": {
                            "id": 41048,
                            "label": false
                        }
                    },
                    "mkz": {
                        "key": "mkz",
                        "label": "MKZ",
                        "multiSelect": false,
                        "type": "",
                        "values": {
                            "id": 41047,
                            "label": "buxtehude_123"
                        }
                    }
                }
            },
            "variant": {
                "id": 1234567,
                "referenceKey": "SKU_something_01",
                "stock": {
                    "customData": {
                    },
                    "deliveryForecast": {
                        "deliverable": "directShipping",
                        "subsequentDelivery": "christmas"
                    },
                    "isSellableWithoutStock": false,
                    "quantity": 18,
                    "supplierId": 271
                }
            }
        }
    ],
    "payment": [
        {
            "amount": 1190,
            "key": "pay_instalments",
            "options": {
                "countOfInstallments": 3,
                "hasPaybreak": false
            }
        }
    ],
    "shipping": {
        "deliveredOn": "2019-11-29",
        "policy": "delivery_deadline"
    }
}

Request schema

id integer

address object (optional)
- billing object (optional)
  - id integer
  - additional string ([!-ɏ0-9 ]) (optional)
  - city string ([!-ɏ0-9 ])
  - countryCode string (optional) (minimum length: ) (maximum length: 3)
  - houseNumber string ([!-ɏ0-9 ])
  - recipient object
  - referenceKey string (optional)
  - state string (optional) (maximum length: 60)
  - street string ([!-ɏ0-9 ])
  - title string ([!-ɏ0-9 ]) (optional)
  - zipCode string ([A-z0-9\- ]{1,12})
- shipping object (optional)
  - id integer
  - additional string ([!-ɏ0-9 ]) (optional)
  - city string ([!-ɏ0-9 ])
  - collectionPoint object (optional)
  - countryCode string (optional) (minimum length: ) (maximum length: 3)
  - houseNumber string ([!-ɏ0-9 ])
  - recipient object
  - referenceKey string (optional)
  - state string (optional) (maximum length: 60)
  - street string ([!-ɏ0-9 ])
  - title string ([!-ɏ0-9 ]) (optional)
  - zipCode string ([A-z0-9\- ]{1,12})

cost object
- appliedReductions array (optional)
  - amount object
  - category enum (voucher)
  - code string (optional)
  - type enum (relative absolute)
- withoutTax integer
- withTax integer

customData object (optional)

customer object
- id integer
- customData object (optional) (object is extensible as desired)
- firstName string (optional)
- gender enum (m f d) (optional)
- lastName string (optional)
- referenceKey string (optional)

ipAddress string (optional)

items array
- id integer (optional)
- availableQuantity integer (optional)
- currency string (optional) (minimum length: ) (maximum length: 3)
- customData object (optional) (object is extensible as desired)
- deliveryForecast object (optional)
  - deliverable object
  - subsequentDelivery object
- key string
- merchant object (optional)
  - id integer
- price object
  - appliedReductions array (optional)
  - tax object
  - withoutTax integer
  - withTax integer
- product object
  - id integer
  - attributes object (object is extensible as desired)
- variant object
  - id integer
  - referenceKey string
  - stock object (optional)

payment array
- amount integer
- key string
- options object (optional)
  - countOfInstallments integer (optional)
  - hasPaybreak boolean (optional)

shipping object
- deliveredOn string ([0-9]{4}\-[0-9]{2}\-[0-9]{2}) (optional)
- policy enum (least_packages earliest_shipping delivery_deadline next_business_day_express) (optional)

Response

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

Response body

Response example

{
  "shipping": {
    "deliveryCosts": 599,
    "expressDeliveryCosts": 6
  }
}

Response schema

shipping object
- deliveryCosts integer
- expressDeliveryCosts integer (optional)

The response body will be written to the order.customData.fees property. In case the request failed, checkout will store "requestFailed": true.

Status Codes:

Code	Description	Response Body
`201`	request was successful
`401`	authentication failed	empty