Custom Delivery Adapter
If you want total control of the provided delivery methods, you can build and host your own adapter that will empower Walley Checkout with delivery methods. This allows you to separate the items in the cart in multiple shipments, set specific pickup/delivery dates, add options to each delivery etc.
How to get started 🚀
- Contact Walley Merchant Services for help with setup in our test environment and for questions regarding integration with the Delivery Module.
- Build a delivery adapter (api) with an endpoint that Walley Checkout will do a GET request towards to get the delivery methods that should respond according to the response below. Use basic auth as authentication.
- Provide Walley Merchant Services with the adapter endpoint url, basic auth credentials as well as what fallback strategy to use.
Overview
GET delivery methods
Walley Checkout fetches the list of available delivery methods every time the customer changes any relevant information that might lead to a change in available delivery methods, e.g. the customer changes delivery address or updates the cart.
Custom request parameters
When the Checkout sends the GET request to the delivery adapter, apart from some default parameters, a merchant can send custom parameters called ShippingProperties that are related to the cart.
This is done in either Initialize checkout, Update checkout or Update cart.
{
"ShippingProperties": {
"height":"10",
"width": "20",
"isBulky": "true"
}
}
The following scenario would result in the following GET-request to the delivery adapter to fetch the available delivery methods:
https://{UriToDeliveryAdaptersGetDeliveryMethodsEndpoint}?currency={currency}&....&height=10&width=20&isBulky=true
Note that the example with height, width and isBulky are just examples. Any key/value pair can be used and will be translated to query parameters accordingly.
If using a custom delivery adapter, where the privateId is sent in the query, it is possible to Acquire Checkout Information to get more information. Consider that this will add some time for your customer in the checkout so use it only if necessary.
Default request query parameters
Below are the default query parameters that are included when fetching delivery methods.
| Parameter | Explanation |
|---|---|
| privateId | The checkout's private id which can be used to fetch information about the checkout |
| storeId | The storeId for the checkout session |
| currency | Currency used for the checkout session |
| language | The display language used for the checkout session. Supported language are: sv, no, fi, da, en |
| countryCode | The country code for the customer's current delivery address |
| postalCode | The postal code for the customer's current delivery address |
| cartPrice | The total price for cart |
| cartWeight | The total weight for the cart, sum of all the article's weights sent in set cart request |
| The customer's email address | |
| address | The address for the customer's current delivery address |
| storeType | CustomerType for the checkout session, b2b or b2c |
| loyalty-isMember | Customer loyalty membership, see below |
Loyalty booster synergies
If you are using any of our loyalty boosters we will include loyalty membership as a query parameter loyalty-isMember=Yes/No/New where
- Yes: The customer is an existing member.
- No: The customer is not a member and has opted out of becoming one.
- New: The customer is not a member but has opted in to become one.
Response from adapter
The response can contain a lot of data and options that will be available for the customer, but not many of them are required. Here is an example of a successful response as well as an error response.
Response header
| Header | Required | Explanation |
|---|---|---|
| Expires | No | A DateTime set if the choices should be valid only for a certain time. We will force the customer to reload delivery methods if a selection is made with delivery methods that has expired. Supported formats are RFC-7234 or .NET DateTimeOffset for example "Tue, 01 Jan 2002 00:00:00 GMT" or "2002-01-01 00:00:00 +00:00". If the header cannot be parsed, no expiration date is used |
Response body
| Property | Required | Explanation |
|---|---|---|
| shipments | Yes | Array of shipments, at least one must be present |
Shipment Property
| Property | Required | Explanation |
|---|---|---|
| id | Yes | Id of the shipment |
| name | Yes | Name of shipment, will be displayed as a header for the entire shipment selection |
| shippingChoices | Yes | Array of choices that the customer can choose from for the shipment, at least one must be present |
| metadata | No | Any metadata for the delivery, will not be used in checkout but returned every time you acquire checkout information |
| info | No | Shipment specific info for costumer with a title and description |
Info Property
| Property | Required | Explanation |
|---|---|---|
| title | Yes | Informational title regarding shipment |
| description | Yes | Informational text regarding shipment |
ShippingChoice Property
| Property | Required | Explanation |
|---|---|---|
| id | Yes | Id of the choice |
| name | Yes | Name of the choice, will be the title for the selection |
| description | No | Description of the choice, will be the subtitle for the selection |
| icon | No | Icon for the choice. Available icon property values can be found below. If none is provided, a default icon will be used. |
| fee | No | Fee for the option, if combined with destinations and/or options, this fee will be added to all of them |
| destinations | No | Array of destinations that will be a subselection for the shipping choice |
| options | No | Array of options that the customer can add optionally to add to the shipping choice |
| metadata | No | Any metadata for the shipping choice, will not be used in checkout but returned every time you acquire checkout information |
| badges | No | Array of Badges with text and color for information regarding shipping choice |
Destinations Property
| Property | Required | Explanation |
|---|---|---|
| id | Yes | Id of the destination |
| name | Yes | Name of the destination, will be the title of the selectable destination |
| description | No | Description of the destination, will be the subtitle of the selectable destination |
| deliveryDates | No | Array of available delivery dates for the destination |
| fee | No | Fee for the specified destination |
| metadata | No | Any metadata for the destination, will not be used in checkout but returned every time you acquire checkout information |
DeliveryDate Property
| Property | Required | Explanation |
|---|---|---|
| date | Yes | DateTime of the selectable delivery date |
| timeFrom | Yes | Time of the day from where the selectable delivery date option starts |
| timeTo | Yes | Time of the day from where the selectable delivery date option ends |
| fee | No | Fee for the specified delivery date |
| metadata | No | Any metadata for the delivery date, will not be used in checkout but returned every time you acquire checkout information |
Option Property
| Property | Required | Explanation |
|---|---|---|
| id | Yes | Id of the option |
| description | Yes | Description of the option |
| type | Yes | Type of the option, available types: "bool" - checkbox, "string" - text field, "number" - digits only |
| fee | No | Fee for the specified option |
| metadata | No | Any metadata for the option, will not be used in checkout but returned every time you acquire checkout information |
Badge Property
| Property | Required | Explanation |
|---|---|---|
| text | Yes | Badge text |
| color | No | Badge color |
Badges
Each shipping choice can have multiple badges with text and predefined color. These can be used to add extra information regarding a shipment, such as faster or environmentally friendly shipping. Below are the available colors.
| Color property value | Icon |
|---|---|
| default | Default |
| discrete | Discrete |
| red | Red |
| green | Green |
| yellow | Yellow |
| blue | Blue |
Icons
The available icons available for a shippingChoice is described under Delivery Icons
Error message response
If the GET-request is received successfully but no delivery methods can be returned, you can choose to return a non-2xx response with the following properties to inform the customer what is wrong and what action to take. This requires the fallback strategy to be set to true.
| Property | Required | Explanation |
|---|---|---|
| title | No | The title of the failure displayed in the Checkout. Truncated to a maximum of 512 characters. |
| message | No | The message with a more descriptive text why no delivery methods was found, and how the customer should proceed. Truncated to a maximum of 512 characters. |
A default message will be shown if not overridden with title and message from the response. Both title and message must be specified in the response to be used.
Response examples
- Delivery methods response - 200
- Custom error message response - non 2xx
/*
Expires: "Tue, 01 Jan 2002 00:00:00 GMT"
*/
{
"configurationId": "config-1"
"shipments": [
{
"id": "shipmentId-1",
"name": "Delivery 1",
"info": {
"title": "Delivery time affected",
"description": "Your cart contains sensitive items which may affect delivery time"
},
"metadata": {
"key-for-shipment": "metadata-for-shipment"
},
"shippingChoices": [
{
"id": "choiceId-1",
"name": "Pickup in store",
"icon": "walley-store",
"description": "Pick up your order within five days from your chosen day for pick up",
"badges": [
{
"text": "Express delivery",
"color": "red"
}
],
"metadata": {
"key-for-shipping-choice": "metadata-for-shipping-choice"
},
"destinations": [
{
"id": "destinationId-gothenburg",
"name": "Gothenburg",
"description": "Kortedala",
"metadata": {
"key-for-destination": "metadata-for-destination"
},
"deliveryDates": [
{
"date": "2021-02-25T00:00:00+00:00",
"timeFrom": "07:00",
"timeTo": "17:00",
"fee": 0.0,
"metadata": {
"duringOpenHours": "true"
}
},
{
"date": "2021-02-25T00:00:00+00:00",
"timeFrom": "17:00",
"timeTo": "21:00",
"fee": 250.0,
"metadata": {
"duringOpenHours": "true"
}
},
{
"date": "2021-02-25T00:00:00+00:00",
"timeFrom": "21:00",
"timeTo": "22:00",
"fee": 500.0,
"metadata": {
"duringOpenHours": "false"
}
},
{
"date": "2021-02-26T00:00:00+00:00",
"timeFrom": "07:00",
"timeTo": "17:00",
"fee": 100.0
},
{
"date": "2021-03-01T00:00:00+00:00",
"timeFrom": "07:00",
"timeTo": "17:00",
"fee": 0.0
}
]
},
{
"id": "destinationId-varberg",
"name": "Varberg",
"description": "Hunnestad",
"deliveryDates": [
{
"date": "2021-02-28T00:00:00+00:00",
"timeFrom": "09:00",
"timeTo": "16:00",
"fee": 0.0
},
{
"date": "2021-02-28T00:00:00+00:00",
"timeFrom": "16:00",
"timeTo": "18:00",
"fee": 250.0
}
]
}
],
"fee": 0,
"options": [
{
"id": "option-1",
"description": "Rent trailer",
"type": "bool",
"fee": 500
},
{
"id": "option-2",
"description": "Help to pack",
"type": "bool",
"fee": 250
},
{
"id": "option-3",
"description": "Additional information",
"type": "string",
"fee": 0
}
]
},
{
"id": "choiceId-2",
"name": "Home delivery",
"icon": "walley-home",
"description": "Goods will be delivered as close to your home as possible",
"badges": [
{
"text": "Lightning fast!",
"color": "yellow"
},
{
"text": "Environmentally friendly",
"color": "green"
},
{
"text": "Carried to your door",
"color": "red"
}
],
"destinations": [
{
"id": "destinationId-home",
"name": "The most comfortable delivery",
"description": "Select day for delivery",
"deliveryDates": [
{
"date": "2021-03-11T00:00:00+00:00",
"timeFrom": "07:00",
"timeTo": "17:00",
"fee": 200.0
},
{
"date": "2021-03-12T00:00:00+00:00",
"timeFrom": "07:00",
"timeTo": "17:00",
"fee": 50.0
}
]
},
{
"id": "destinationId-home-express",
"name": "Express - a lot faster",
"description": "When you are in a hurry",
"fee": 500,
"deliveryDates": [
{
"date": "2020-10-01T00:00:00+00:00",
"timeFrom": "08:00",
"timeTo": "18:00"
}
]
}
],
"fee": 500,
"options": [
{
"id": "option1",
"description": "Notify when delivered",
"type": "bool",
"fee": 500
}
]
},
{
"id": "choiceId-3",
"name": "Pick up at service point with Postnord",
"icon": "postnord",
"description": "Select service point",
"badges": [
{
"text": "At your own leisure",
"color": "default"
},
{
"text": "Environmentally friendly",
"color": "green"
}
],
"destinations": [
{
"id": "service-point-1",
"description": null,
"name": "Postnord store, Avenyn"
},
{
"id": "service-point-2",
"description": null,
"name": "Postnord store, Backa"
}
],
"fee": 29
},
{
"id": "choiceId-4",
"name": "Pick up at service point with Schenker",
"icon": "dbschenker",
"description": "Select service point",
"badges": [
{
"text": "Pick up",
"color": "green"
}
],
"destinations": [
{
"id": "service-point-1",
"description": null,
"name": "Schenker store, Avenyn"
},
{
"id": "service-point-2",
"description": null,
"name": "Schenker store, Backa"
}
],
"fee": 29
},
{
"id": "choice-without-destination",
"name": "Pick up at central warehouse, Kalmar",
"icon": "walley-store",
"description": "Kalmar street 8",
"destinations": null,
"fee": 100
}
]
},
{
"id": "shipmentId-2",
"name": "Delivery 2",
"info": {
"title": "Longer delivery time",
"description": "Your cart contains items which are not in stock, this may affect delivery times"
},
"shippingChoices": [
{
"id": "choice-home-delivery",
"name": "Home delivery",
"icon": "walley-home",
"badges": [
{
"text": "Lightning fast!",
"color": "yellow"
},
{
"text": "Environmentally friendly",
"color": "green"
}
],
"destinations": [
{
"id": "standard-home-delivery",
"description": "Delivery within 5-7 days",
"name": "Standard, the most comfortable delivery"
},
{
"id": "express-home-delivery",
"description": "Delivery within 2 days",
"name": "Express - a lot faster",
"fee": 500
}
],
"fee": 1500,
"options": [
{
"id": "option1",
"description": "Bring my old stuff out",
"type": "bool",
"fee": 500
}
]
},
{
"id": "choice-without-destination-2",
"name": "Pick up at warehouse",
"icon": "walley-store",
"destinations": null,
"fee": 100
}
]
}
]
}
{
"title": "Title to be displayed",
"message": "Message to be displayed"
}
The 200-response from the example above will render the following delivery methods to the customer.
POST create external shipment
Creating an external shipment is an optional step with the intent to produce an identifier that we will give to the merchant as an easier way to reference the shipment. For each shipment on the order we will make a POST call to a configured endpoint. The data is a slimmed down version of the shipments data we recieved in GET delivery methods, but only containing the information selected by the customer.
Request
/*
POST https://{UriToDeliveryAdaptersCreateExternalShipmentEndpoint} HTTP/2.0
Authorization: Basic Auth
Content-Type: application/json
*/
{
"configurationId": "config-1",
"storeId": 123456,
"reference": "ABCDEFGHJIKLMNOP",
"customer": {
"email": "test@walleytest.se",
"mobilePhoneNumber": "+46701111111",
"deliveryAddress": {
"firstName": "Lars-Erik Rudolf",
"lastName": "Viberg",
"companyName": null,
"coAddress": null,
"address": "Sommarstugevägen 2",
"address2": null,
"postalCode": "85353",
"city": "Sundsvall",
"countryCode": "SE"
}
},
"shipment": {
id: "shipmentId-1",
"metadata": {
"key-for-shipment": "metadata-for-shipment"
},
"shippingChoice": {
"id": "choiceId-1",
"metadata": {
"key-for-shipping-choice": "metadata-for-shipping-choice"
},
"destination" : {
"id": "destinationId-gothenburg",
"metadata": {
"key-for-destination": "metadata-for-destination"
},
"deliveryDate": {
"date": "2021-02-25T00:00:00+00:00",
"timeFrom": "17:00",
"timeTo": "21:00",
"metadata": {
"duringOpenHours": "true"
}
}
},
"options": [
{
"id": "option-1",
"value": "true"
},
{
"id": "option-3",
"value": "The dog is friendly"
}
]
},
}
,
}
Response
{
"externalShipmentId": "external-shipment-id-1"
}