Content in this article:
What is TimeSlots
More and more end customers expect to be able to choose between multiple delivery options and select a specific delivery time slot is something that some carriers are starting to offer.
In nShift we have developed a solution to support time slot bookings. It enables you to show products supporting time slots in your webshop, and let your end customer select the time slot that is right for them.
Time slot services are different from carrier to carrier. It can be used for delivery or pickup and some carriers apply additional fees for using these services. Ask your carrier for more information.
Note: Currently (September 2020), we are supporting Airmee and Porterbuddy time slot services. More are in development.
How does it work
Depending on what you want to do, the methods need to be executed in a certain order:
If you want to create a shipment
1. GetShipAdvise
Extract the Token and TimeSlotToken from the selected Product
See the example here or the documentation
2. AllocateTimeSlot
Add the Token and TimeSlotToken in the options object on the request.
Extract the AllocatedTimeSlotToken from the response
See the example here or the documentation
3. SubmitShipment
Add the Token and the AllocatedTimeSlotToken in the options object on the request
See the example here or the documentation
4. TransmitShipment
See this article or the documentation
If you want to cancel a shipment
1. DeleteShipment
See the documentation
2. VoidTimeSlot
Add the AllocatedTimeSlotToken in the options object on the request.
See the example here or the documentation
Request Examples
Note: Shipment Server expects the requests to be encoded as form-data or x-www-form-urlencoded
...
GetShipAdvise - Request Body
{
"data": {
"Kind": 1,
"Addresses": [
{
"Kind": 1,
"Name1": "Test Name1",
"Street1": "Test Address 1",
"PostCode": "11825",
"City": "Stockholm",
"Phone": "004612341234",
"Mobile": "004612341234",
"Email": "noreply@nshift.com",
"Attention": "Test Attention",
"CountryCode": "SE"
}
],
"Lines": [
{
"Number": 1,
"PkgWeight": 1000,
"Height": 100,
"Length": 100,
"Width": 100,
"References": [
{
"Kind": 23,
"Value": "Test Content"
}
]
}
]
},
"options": {
"ServiceLevel": "default",
"EarliestPickup": "2020-09-22T06:00",
"LatestPickup": "2020-09-22T21:00",
"PickupWindowCount": 1,
"TimeSlots": 1,
"TimeLog": 1
},
"key": "sample",
"actor": "134",
"command": "GetShipAdvise"
}Response Body
{
"Products": [
{
"ProdConceptID": 5599,
"ProdCSID": 1632,
"ProdName": "Airmee - Airmee",
"Token": "_-1_0_1603_5799_1632_5599_0_0__0__30/12/1899_30/12/1899___",
"SupportsDropPoint": 0,
"TimeSlots": [
{
"Start": "2020-09-11T17:00:00",
"End": "2020-09-11T22:00:00",
"TimeSlotToken": "eyJzdGFydCI6IjIwMjAtMDktMTFUMTc6MD...",
"Expires": ""
}
]
},
{
"ProdConceptID": 675,
"ProdCSID": 1029,
"ProdName": "UPS - UPS Standard®",
"Services": [
{
"serviceid": 60041,
"name": "Delivery to UPS Access Point"
}
],
"Token": "60041_2_0_1603_5799_1029_675_0_0__0__30/12/1899_30/12/1899___",
"SupportsDropPoint": 1
}
],
"Log": []
],
"Status": 8,
"CSRMessage": "Success : List of valid products returned",
"TimeLog": []
}...
AllocateTimeSlot - Request Body
{
"data": {},
"options": {
"TimeSlotToken": "eyJzdGFydCI6IjIwMjAtMDktMTFUM...",
"Token": "_-1_0_1603_5799_1632_5599_0_0__0__30/12/1899_30/12/1899___"
},
"key": "sample",
"actor": "134",
"command": "AllocateTimeSlot"
}Response Body
{
"Result": "Success",
"AllocatedTimeSlotToken": "YXRzdDtmZjIxYTlkMi1mM2ZhLTExZWEtYjY3...",
"Information": ""
}...
SubmitShipment - Request Body
{
"data": {
"Kind": 1,
"Addresses": [
{
"Kind": 1,
"Name1": "Test Name1",
"Street1": "Test Address 1",
"PostCode": "11825",
"City": "Stockholm",
"Phone": "004612341234",
"Mobile": "004612341234",
"Email": "noreply@nshift.com",
"Attention": "Test Attention",
"CountryCode": "SE"
}
],
"Lines": [
{
"PkgWeight": 1000,
"Height": 100,
"Length": 100,
"Width": 100,
"Number": 1,
"References": [
{
"Kind": 23,
"Value": "Test Content"
}
]
}
]
},
"options": {
"AllocatedTimeSlotToken": "YXRzdDtmZjIxYTlkMi1mM2ZhLTExZWEtYjY3N...",
"Labels": "ZPLGK",
"Token": "_-1_0_1603_5799_1632_5599_0_0__0__30/12/1899_30/12/1899___"
},
"key": "sample",
"actor": "134",
"command": "SubmitShipment"
}Response Body
{
"ShpCSID": 5238,
"ShpESID": ...,
"ShpTag": "...",
"InstallationID": "...",
"Kind": 1,
"ShpNo": "...",
"PickupDt": "2020-09-11T00:00:00",
"LabelPrintDt": "2020-09-11T08:58:54",
"SubmitDt": "2020-09-11T08:58:55",
"Weight": 1000,
"ActorCSID": 134,
"Temperature": 1,
"CarriagePayer": 1,
"CarrierConceptID": 658,
"CarrierCSID": 75,
"SubcarrierConceptID": 1388,
"SubcarrierCSID": 275,
"ProdConceptID": 5599,
"ProdCSID": 1632,
"StackCSID": 294,
"Addresses": [
{
"Kind": 1,
"Name1": "Test Name1",
"Street1": "Test Address 1",
"PostCode": "11825",
"City": "Stockholm",
"Phone": "004612341234",
"Mobile": "004612341234",
"Email": "noreply@nshift.com",
"Attention": "Test Attention",
"CountryCode": "SE"
},
{
"Kind": 2,
"Name1": "Test Name1",
"Street1": "Test Address 1",
"PostCode": "11825",
"City": "Stockholm",
"Phone": "004612345678",
"Mobile": "004612345678",
"Email": "noreply@nshift.com",
"Attention": "Test Sender Attention",
"CountryCode": "SE"
}
],
"Amounts": [...],
"References": [...],
"Messages": [...],
"CSEvents": [...],
"Lines": [
{
"LineCSID": 5937,
"LineTag": "A6DE8AB7-292E-4CAA-B5AC-6C8B5F374E32",
"LineWeight": 1000,
"PkgWeight": 1000,
"Height": 100,
"Length": 100,
"Width": 100,
"Pkgs": [...]
}
],
"References": [...]
}
],
"Labels": [
{
"Content": "....",
"Type": 13,
"Copies": 1,
"PkgCSID": 8886,
"PkgNo": "..."
}
]
}...
VoidTimeSlot - Request Body
{
"data": {},
"options": {
"AllocatedTimeSlotToken": "YXRzdDtmZjIxYTlkMi1mM2ZhLTExZWEtYjY3N..."
},
"key": "sample",
"actor": "134",
"command": "VoidTimeSlot"
}Response Body
{
"Result": "Success",
"Information": ""
}
Frequently asked questions
-
Does the AllocatedTimeSlotToken on a SubmitShipment call do anything else than updating the Delivery Date fields on a shipment?
Depends on the Carrier
- -
Do a TimeSlotToken expire?
Depends on the Carrier
- -
Does a customer pay for the allocation of a TimeSlot?
Depends on the Carrier
-
-
Is the AllocatedTimeSlot only activated when I do a SubmitShipment with it?
No, should be activated when calling the AllocateTimeSlot method
- -
What happens if you allocate a TimeSlot but never call the VoidTimeSlot method if you no longer need it?
Depends on carrier
- -
How do I know how many TimeSlots I have reserved?
The client needs to keep track
- -
If you have used the AllocatedTimeSlotToken on a SubmitShipment, do the DeleteShipment method call the VoidTimeSlot method or do we not need to do this?
Depends on Carrier implementation.